gitaiflow MCP — Getting Started

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

The developer path is:

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:

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:

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

Windows 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:

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:

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:

git rev-parse --show-toplevel

Confirm the repository root.

Verify the gitaiflow executable:

which gitaiflow
gitaiflow --version

Run gitaiflow independently:

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:

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:

/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:

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

The second command should produce no output.

#6. Load the environment

set -a
source .mcp.env
set +a

Confirm the important values without exposing the token:

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:

pytest tests/ -v

MCP-specific tests include:

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.

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

#Stage 3 — Inspector

Read Inspector verification.

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

#Stage 4 — Claude Desktop

Read Claude Desktop.

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:

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

Docker uses container filesystem paths:

MCP_WORKSPACE=/workspace
MCP_ALLOWED_WORKSPACES=/workspace

The mount is:

/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:

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

A tool call can then select:

path="gitaiflow"

which resolves to:

/workspace/gitaiflow

and Git must report:

/workspace/gitaiflow

as that repository's root.

#Do not use $PWD blindly

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

-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:

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

or define a clearly named variable:

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:

--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:

docker ps --filter name=gitaiflow-mcp

Then:

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:

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

Also verify the effective Docker configuration:

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:

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 for Verification map and order of operations.