MCP operator guide

Choose a transport

For a local client that starts CodeGraph as a subprocess, use stdio:

python -m src.mcp --transport stdio

For Streamable HTTP, bind explicitly and connect the client to http://127.0.0.1:27495/mcp:

python -m src.mcp --transport http --host 127.0.0.1 --port 27495

The supported transports are stdio and http. SSE and the retired SSE compatibility paths are not available.

Authentication and project scope

Stdio is a trusted local transport. HTTP requires authentication by default and accepts either Authorization: Bearer <jwt> or X-API-Key: <api-key>. Send X-Project-ID when a network tool call needs project scope; the server resolves that value against the authenticated identity and rejects a mismatched project_key or namespace.

--no-auth is a local-development mode. The command is rejected unless security.mcp_allow_no_auth_network_transports is enabled, and an unauthenticated server may bind only to a loopback host:

python -m src.mcp --transport http --host 127.0.0.1 --port 27495 --no-auth

Tool calls require the handler to verify the required role, exact carrier, and persisted approval. A full or owner-scoped profile defines the catalog available to the operator.

Select and verify a tool profile

The command starts with the codex profile unless CODEGRAPH_MCP_TOOL_PROFILE is set. Owner profiles are the normal route to lane-specific tools. Derive the current tool catalog from the selected profile.

For a source-checkout diagnostic, derive the current set instead of copying a count into docs:

$env:CODEGRAPH_MCP_TOOL_PROFILE = "full"
python -c "from src.mcp.surface_catalog import profile_family_tool_names; print(len(profile_family_tool_names('full')))"

Use profile_family_tool_names only as a local source diagnostic. The catalog returned to the connected MCP client is the runtime evidence that matters.

Follow the canonical wire contract

• Pass structured fields as native arrays and objects. Retired *_json aliases and JSON-encoded containers are not compatibility inputs and must fail closed.
• Pass story_id as a string and use compact canonical identifiers such as handoff_v1.
• Do not pass db_path or another storage path to agent-facing tools. Runtime storage is resolved from the authenticated project context.
• For PRD execution, pass traceability assertions and test executions as native typed arrays. Product acceptance evidence comes from revision-bound requirements, test executions, and lane decisions; command exit codes, paths, and historical status labels provide operational context.
• Approval, finance, and authority payloads come from values issued or persisted by the authoritative server workflow.

Use supported PRD status views

codegraph_digital_employee_prd_delivery_status accepts these exact view values:

Any other value returns unsupported_status_view; there are no summary or compact aliases.

Diagnose a failed call

1. Run python -m src.mcp --help and confirm the transport and bind options.
2. Reconnect the client after a server restart; refreshed discovery reports current runtime registration.
3. Verify the active profile and check whether the error names a required owner profile.
4. For HTTP, verify authentication and X-Project-ID before changing tool arguments.
5. Treat retired aliases, scalar/container coercion, and caller-authored authority as contract errors. Do not retry them through a fallback shape.