gfa-mcp

Model Context Protocol server wrapping the gfa Python SDK.

gfa-mcp is a sidecar that exposes 14 gfa primitives as MCP tools so off-the-shelf agent platforms (Claude Code, Cursor, Codex Agent, Cline, Continue.dev) can call them without bespoke per-platform integration.

The MCP server is a thin adapter — every tool maps 1:1 to an SDK method. Routing, caching, and threshold heuristics live in the SDK (gfa-sdk), not here. See docs/architecture/sdk-mcp.md in the gfa repo for the full design.

Install

pip install gfa-mcp

Quickstart

# Stdio (agent platform spawns gfa-mcp as a subprocess)
gfa-mcp --stdio --endpoint https://gfa.example.com --token "$GFA_JWT"

# HTTP (long-running, multiple agents on the same host)
gfa-mcp --port 8765 --endpoint https://gfa.example.com --key ~/.gfa/agent.pem

# Inspect the tool list without running the server
gfa-mcp --print-tools

Claude Code wiring

~/.claude-code/mcp.json:

{
  "mcpServers": {
    "gfa": {
      "command": "gfa-mcp",
      "args": [
        "--stdio",
        "--endpoint", "https://gfa.example.com",
        "--key", "/home/user/.gfa/agent.pem"
      ]
    }
  }
}

Cursor and Codex Agent use a similar shape per their respective docs.

Auth

--token JWT for pre-minted JWTs (simple, doesn't auto-rotate). --key PATH for ECDSA private keys (auto-rotates short-lived tokens via the SDK's FileKeyTokenProvider). Use --key for any session expected to live longer than the JWT's TTL.

Customer docs

The full agent integration guide — AGENTS.md template, system-prompt snippets, per-platform config — is M-055-CUSTOMER-DOCS in the gfa project backlog and ships separately from this package.