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

If port 27495 is occupied, choose a free local port. Replace the --port value and the port in the client URL with the same value.

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

Verify the stdio catalog

With the stdio process running, send this JSON-RPC message through its stdin as one line. The indented form below shows the fields; the client serializes it as one line on the wire.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "docs-check",
        "version": "1"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

The response has the same id and a result.tools array. Inspect each tool’s name and inputSchema before calling it. The active profile determines the returned tools.

Send a canonical HTTP request

POST the same JSON-RPC request to /mcp. Along with the credentials described below, send these headers for the tools/list example:

Keep MCP-Method equal to the JSON-RPC body’s method. The server returns mcp-method header does not match the request body's method when they differ.

For a tool call, set MCP-Method: tools/call and set MCP-Name to the body’s params.name. For example, calling codegraph_project_context_status requires MCP-Name: codegraph_project_context_status. Inspect the tool result after the response: denied with reason mcp_authentication_required requires authentication, even when the HTTP response is 200.

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

Governed mutations 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.

Set the profile in the environment of the process that starts the server. These commands explicitly select codex. For an owner connection, replace codex with the profile name from that connection’s settings.

CODEGRAPH_MCP_TOOL_PROFILE=codex python -m src.mcp --transport stdio

In PowerShell, set the variable before starting the server:

$env:CODEGRAPH_MCP_TOOL_PROFILE = 'codex'
python -m src.mcp --transport stdio

When an IDE starts the server, set this variable in the MCP connection’s environment settings. Reconnect the client and send tools/list to inspect the selected catalog.

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

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.