---
since: 1.1.3
---

# gitaiflow MCP — Getting Started

This is the first document a developer should read.

If you are an end user who only wants Claude Desktop integration, use the packaged MCPB installation described in [MCP overview](./README.md) instead. The procedures below are for developers who are configuring or verifying the MCP server.

The developer path is:

```text
source checkout
    ↓
gitaiflow works
    ↓
MCP configuration
    ↓
native MCP
    ↓
Docker MCP
    ↓
MCP Inspector
    ↓
Claude Desktop
```

Do not start with Claude Desktop. Verify the lower layers first.

---

## 1. The mental model

There are three important runtime boundaries:

```mermaid
flowchart TB
    Client["MCP client"]
    MCP["gitaiflow MCP server"]
    AOT["gitaiflow AOT binary"]
    Repo["Git repository"]
    Config["~/.gitaiflow/config.env"]

    Client --> MCP
    MCP --> AOT
    AOT --> Repo
    AOT --> Config
```

MCP is an adapter. It does not become a second implementation of gitaiflow.

The simplest debugging rule is:

> If direct gitaiflow execution does not work, do not debug MCP yet.

---

## 2. End-user installation versus developer setup

### End user: Claude Desktop MCPB

If you only want to use gitaiflow MCP from Claude Desktop:

```bash
curl -fsSL https://install.djangoplay.org/gitaiflow-mcp | bash
```

Windows PowerShell:

```powershell
irm https://install.djangoplay.org/gitaiflow-mcp.ps1 | iex
```

The installer downloads the platform-specific `.mcpb` file to the default Downloads directory and prints the path. Open that `.mcpb` file with Claude Desktop to install the extension.

For this path, you do **not** need:

- a source checkout
- Python
- Docker
- `.mcp.env`
- a manually configured `docker run` command

The packaged extension handles the local MCP launch and gitaiflow binary resolution.

### Developer: source/Docker verification

Continue with the rest of this document.

---

## 3. Two configuration layers

### MCP runtime

`.mcp.env` contains MCP settings such as:

```text
MCP_TRANSPORT
MCP_API_TOKEN
MCP_WORKSPACE
MCP_ALLOWED_WORKSPACES
MCP_EXECUTION_TIMEOUT
MCP_RATE_LIMIT
MCP_RATE_WINDOW_SECONDS
```

### gitaiflow AI/runtime configuration

`~/.gitaiflow/config.env` contains:

```text
AI_PROVIDER
AI_API_KEY
AI_BASE_URL
AI_MODEL
```

The MCP adapter does not copy or reinterpret those AI settings.

Keep workspace paths, developer binary paths, and MCP tokens out of `~/.gitaiflow/config.env`.

---

## 4. First local checks

From the `gitaiflow` repository:

```bash
git rev-parse --show-toplevel
```

Confirm the repository root.

Verify the gitaiflow executable:

```bash
which gitaiflow
gitaiflow --version
```

Run gitaiflow independently:

```bash
gitaiflow --last-summary
```

If this fails, fix gitaiflow installation/configuration before testing MCP.

---

## 5. Create local MCP configuration

Use a local `.mcp.env` and never commit real secrets.

For a developer workspace containing multiple Git repositories, configure the **host parent workspace**, not an individual repository:

```text
MCP_TRANSPORT=streamable-http
MCP_API_TOKEN=local-test-token
MCP_WORKSPACE=/Users/<user>/pyc/missionmq/gl/
MCP_ALLOWED_WORKSPACES=/Users/<user>/pyc/missionmq/gl/
MCP_EXECUTION_TIMEOUT=120
MCP_RATE_LIMIT=100
MCP_RATE_WINDOW_SECONDS=60
```

The parent workspace may contain:

```text
/Users/<user>/pyc/missionmq/gl/
├── gitaiflow/.git
├── djangoplay-cli/.git
├── astwire/.git
└── issuetracker/.git
```

The MCP server resolves the repository selected by the tool `path` argument. For example, `path="gitaiflow"` resolves to the configured workspace's `gitaiflow` directory.

Check that `.mcp.env` is ignored:

```bash
git check-ignore -v .mcp.env
git ls-files .mcp.env
```

The second command should produce no output.

---

## 6. Load the environment

```bash
set -a
source .mcp.env
set +a
```

Confirm the important values without exposing the token:

```bash
printf 'MCP_TRANSPORT=%s\n' "$MCP_TRANSPORT"
printf 'MCP_WORKSPACE=%s\n' "$MCP_WORKSPACE"
printf 'MCP_ALLOWED_WORKSPACES=%s\n' "$MCP_ALLOWED_WORKSPACES"
printf 'MCP_EXECUTION_TIMEOUT=%s\n' "$MCP_EXECUTION_TIMEOUT"
printf 'MCP_RATE_LIMIT=%s\n' "$MCP_RATE_LIMIT"
printf 'MCP_RATE_WINDOW_SECONDS=%s\n' "$MCP_RATE_WINDOW_SECONDS"
```

Do not print `MCP_API_TOKEN` into logs or screenshots.

---

## 7. Run the test suite

Start with:

```bash
pytest tests/ -v
```

MCP-specific tests include:

```text
tests/mcp-server/test_mcp_config.py
tests/mcp-server/test_mcp_executor.py
tests/mcp-server/test_mcp_middleware.py
tests/mcp-server/test_mcp_workspace.py
```

The tests prove MCP internals. They do not replace end-to-end verification.

---

## 8. Follow the verification order

### Stage 1 — Native

Read `MCP-LOCAL-VERIFICATION.md`.

Proves the Python server, authentication, workspace authorization, and installed gitaiflow executable work together.

### Stage 2 — Docker

Read [Docker verification](./docker-verification.md).

Proves the container, multi-repository workspace mount, matching AOT binary, direct AOT execution, and MCP HTTP/stdio boundaries.

### Stage 3 — Inspector

Read [Inspector verification](./inspector-verification.md).

Proves the MCP protocol contract, schemas, and actual tool calls.

### Stage 4 — Claude Desktop

Read [Claude Desktop](./claude-desktop.md).

Proves Docker stdio launch, initialization, tool discovery, and an actual Claude tool invocation.

---

## 9. The most important Docker distinction

Native MCP uses host filesystem paths:

```text
MCP_WORKSPACE=/Users/<user>/pyc/missionmq/gl/
MCP_ALLOWED_WORKSPACES=/Users/<user>/pyc/missionmq/gl/
```

Docker uses container filesystem paths:

```text
MCP_WORKSPACE=/workspace
MCP_ALLOWED_WORKSPACES=/workspace
```

The mount is:

```text
/Users/<user>/pyc/missionmq/gl
        ↓
/workspace
```

This is a **parent workspace containing multiple Git repositories**. It is not required to be a Git repository itself.

For example:

```text
/workspace/
├── gitaiflow/.git
├── djangoplay-cli/.git
└── astwire/.git
```

A tool call can then select:

```text
path="gitaiflow"
```

which resolves to:

```text
/workspace/gitaiflow
```

and Git must report:

```text
/workspace/gitaiflow
```

as that repository's root.

### Do not use `$PWD` blindly

This is unsafe in documentation for a multi-repository workspace:

```bash
-v "$PWD:/workspace"
```

If `$PWD` happens to be `.../gl/gitaiflow`, the container gets only that repository at `/workspace`. Claude can no longer select sibling repositories by name.

Use the explicit parent workspace instead:

```bash
-v "/Users/<user>/pyc/missionmq/gl:/workspace"
```

or define a clearly named variable:

```bash
export MCP_HOST_WORKSPACE="/Users/<user>/pyc/missionmq/gl"
-v "$MCP_HOST_WORKSPACE:/workspace"
```

### `.mcp.env` versus Docker `-e`

It is normal for `.mcp.env` to contain host paths while the Docker command overrides them:

```bash
--env-file .mcp.env \
-e MCP_WORKSPACE=/workspace \
-e MCP_ALLOWED_WORKSPACES=/workspace
```

The explicit `-e` values are the effective values inside the container. Do not rewrite `.mcp.env` just for Docker.

---

## 10. Docker preflight before MCP

After starting the container, verify the actual filesystem before testing Claude or MCP protocol behavior:

```bash
docker ps --filter name=gitaiflow-mcp
```

Then:

```bash
docker exec gitaiflow-mcp sh -c '
echo "=== WORKSPACE ==="
ls -lad /workspace

echo
echo "=== GITAIFLOW ==="
ls -lad /workspace/gitaiflow
ls -lad /workspace/gitaiflow/.git

echo
echo "=== GITAIFLOW ROOT ==="
git -C /workspace/gitaiflow rev-parse --show-toplevel

echo
echo "=== OTHER REPO ==="
git -C /workspace/djangoplay-cli rev-parse --show-toplevel
'
```

Expected:

```text
/workspace/gitaiflow/.git
/workspace/gitaiflow
/workspace/djangoplay-cli
```

Also verify the effective Docker configuration:

```bash
docker exec gitaiflow-mcp sh -c '
echo "MCP_TRANSPORT=$MCP_TRANSPORT"
echo "MCP_WORKSPACE=$MCP_WORKSPACE"
echo "MCP_ALLOWED_WORKSPACES=$MCP_ALLOWED_WORKSPACES"
echo "MCP_EXECUTION_TIMEOUT=$MCP_EXECUTION_TIMEOUT"
echo "MCP_RATE_LIMIT=$MCP_RATE_LIMIT"
echo "GITAIFLOW_BINARY=$GITAIFLOW_BINARY"
'
```

This is the fastest way to catch an incorrect mount or an unexpected environment override.

---

## 11. When something fails

Use this isolation order:

```text
Does gitaiflow work directly?
        ↓ yes
Does native MCP work?
        ↓ yes
Is the Docker parent workspace mounted correctly?
        ↓ yes
Does the selected repository have its own .git?
        ↓ yes
Does the matching AOT binary exist?
        ↓ yes
Does direct AOT work inside Docker?
        ↓ yes
Does /health work?
        ↓ yes
Does MCP initialize?
        ↓ yes
Does the tool call work?
        ↓ yes
Does Inspector work?
        ↓ yes
Does Claude Desktop work?
```

If a lower layer fails, stop there.

Move to next document: [`MCP-LOCAL-VERIFICATION.md`](./local-verification.md) for Verification map and order of operations.