Agent access (MCP)

Agents spend much of each iteration re-reading the tree to learn where a type lives or who calls a function. The Lumen index already knows. zurdo mcp serve hands those answers, and a few about runs and sign-offs, to any Model Context Protocol client.

The server

zurdo mcp serve speaks MCP over stdio. A client launches it as a subprocess in the repository root; it takes no flags and serves until stdin closes. It needs [lumen] enabled = true, and refuses at startup otherwise. To add it to your own client, register a stdio server with command zurdo and args ["mcp", "serve"].

The tools

• Structural tools repair the index before each call, so an agent asking about a file it just edited gets the new answer. limit defaults to 20; 0 lifts it. An empty answer is the text no results.
• Compound tools are read-only: match_lessons counts no lesson use, and run_report writes no file and refuses a PRD with no run.
• Review tools are covered on Signing off manual checks. pending_signoffs is read-only and takes no lock. sign_off writes: it appends to the review log and can flip a task to passed, irreversibly.
• find_related appears only with [pyxis] enabled = true. Its rows are labelled lexical or hybrid and point at files, never lines. See Pyxis.

← initialize
{"id":1,"result":{"capabilities":{"tools":{}},"protocolVersion":"2025-06-18",
 "serverInfo":{"name":"zurdo","version":"1.36.0"}}}
← tools/call find_callers {"name":"install_limiter"}
{"id":3,"result":{"content":[{"type":"text",
 "text":"install_limiter\tbuild_router\tsrc/app.rs:6:20"}],"isError":false}}
← tools/call search_symbols {"name":"load"}
{"id":4,"result":{"content":[{"type":"text",
 "text":"segment\tmethod\tAppConfig::load\tsrc/config.rs:6:5"}],"isError":false}}

Every answer is the CLI's own output. A call the CLI would refuse (a PRD outside the repo, an invalid address) comes back as a result with isError: true and the CLI's message, not as a protocol error.

Letting zurdo run hand the server to the agent

A run can register the server with the agent it launches. It's off by default:

[lumen]
enabled = true          # required: a server with no index has nothing to answer

[mcp]
inject_server        = true    # master switch
strict_claude_config = false   # claude only; see below

[mcp.adapters]                 # per-provider gates
anthropic = true
codex     = true
copilot   = false

All three gates must be open: inject_server, [lumen] enabled, and the provider's adapter. Otherwise the agent's command line is exactly what it would be without the feature. Zurdo registers the running binary once at run start:

copilot defaults off because an organization's policy can disable third-party MCP servers, which costs a failed connection every iteration. Verification never depends on the server: Zurdo still checks every criterion against the tree.

Troubleshooting