---
since: 1.1.3
---

# gitaiflow MCP Documentation

## Start here

There are two entry points depending on what you are doing.

### I only want to use gitaiflow MCP

Start with the installation section in [`MCP-README.md`](./README.md). For Claude Desktop, use the packaged MCPB installer. You do not need the developer Docker or Python verification procedures.

### I am developing or verifying gitaiflow MCP

Read these in order:

```text
1. MCP-GETTING-STARTED.md
2. MCP-LOCAL-VERIFICATION.md
3. MCP-DOCKER-VERIFICATION.md
4. MCP-INSPECTOR-VERIFICATION.md
5. MCP-CLAUDE-DESKTOP.md
6. MCP-RELEASE-SIGNING.md
7. MCP-RELEASE-CHECKLIST.md
```

Use [MCP troubleshooting](../runbooks/mcp-troubleshooting.md) whenever a verification step fails.

---

## Documentation map

| File | Read it when... |
|---|---|
| [`MCP-README.md`](./README.md) | You need the product overview or end-user installation path. |
| [`MCP-GETTING-STARTED.md`](./getting-started.md) | You are setting up MCP for the first time or need to understand the configuration boundary. |
| [`MCP-LOCAL-VERIFICATION.md`](./local-verification.md) | You need the complete verification order. |
| [`MCP-DOCKER-VERIFICATION.md`](./docker-verification.md) | You are testing Docker with one or multiple Git repositories. |
| [`MCP-INSPECTOR-VERIFICATION.md`](./inspector-verification.md) | You are validating MCP protocol, schemas, and tool calls. |
| [`MCP-CLAUDE-DESKTOP.md`](./claude-desktop.md) | You are configuring Claude Desktop, Docker stdio, or the packaged MCPB extension. |
| [`MCP-RELEASE-SIGNING.md`](../deployment/release-signing.md) | You are signing a release, rotating the signing key, or diagnosing a checksum/signature failure. |
| [`MCP-RUNBOOK.md`](../runbooks/mcp-troubleshooting.md) | Something failed and you need diagnosis without changing unrelated layers. |
| [`MCP-DEPLOYMENT.md`](../deployment/release-deployment.md) | You need information about MCP Extension and AOT Release deployments. |
| [`MCP-RELEASE-CHECKLIST.md`](../runbooks/mcp-release-checklist.md) | You are preparing the release. |

---

## Configuration concepts

Keep these boundaries distinct:

```text
End user
    ↓
Claude Desktop + MCPB
    ↓
managed local MCP

Developer
    ↓
source checkout
    ↓
.mcp.env                 MCP runtime configuration
~/.gitaiflow/config.env  gitaiflow AI/runtime configuration
    ↓
Native / Docker / Inspector verification
```

For Docker, host paths and container paths are different. In particular:

```text
Host parent workspace
    ↓ bind mount
/workspace
```

If that parent contains multiple independent Git repositories, the MCP tool `path` selects one of them:

```text
path="gitaiflow"
    ↓
/workspace/gitaiflow
```

The selected directory must be its own Git repository root.

---

## Recommended path

```mermaid
flowchart LR
    Install["End-user install"] --> Use["Claude Desktop"]
    Dev["Developer setup"] --> Native["Native"]
    Native --> Docker["Docker"]
    Docker --> Inspector["Inspector"]
    Inspector --> Claude["Claude"]
    Claude --> Release["Release"]
    Release -. future .-> Cloud["Cloud Run next"]
```

## One rule

**Do not debug a higher layer while a lower layer is failing.**

For example:

```text
/app/bin/gitaiflow missing
```

means:

```text
fix Docker/AOT mounting
```

not:

```text
debug MCP protocol
```

Likewise:

```text
Docker Git repository path is wrong
```

means:

```text
fix the Docker workspace mount/path selection
```

not:

```text
change workspace.py validation
```