castellan mcp

MCP stdio JSON-RPC server exposing stigmergy, memory, and harness tools from the shared registry (12 operational tools + 3 meta tools — see MCP tools reference).

Usage

castellan mcp [--attach <goal_id|auto>]

Methods: initialize, tools/list, tools/call. Same registry as castellan run --mcp live episodes — no drift between editor and headless behavior.

Attach mode (live field instrument)

--attach binds the stdio server to a running castellan run --mcp goal via the .castellan/live/ session manifest:

• --attach auto binds to the current live session; --attach <goal_id> requires that exact goal to be live.
• Fails loudly (attach failed: no live session) when nothing is running — no silent standalone fallback.
• Deposits and snapshots route into the live field with source: "mcp_attach" provenance, which lands in the episode’s instrument_summary.
• Mutation tools (castellan_propose_mutation, castellan_resolve_mutation) are denied in attach mode; attached clients are instruments, not operators.
• If the session ends mid-attach, live tools return an attach_lost error.

castellan run --goal "demo" --mcp &   # session A: live engine
castellan mcp --attach auto           # session B: attached instrument

castellan doctor reports the live session state in its live_session stage.

Error responses

castellan_search_tools queries are capped at 256 characters.

Recipes

List tools (stdio):

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | castellan mcp

Discovery flow:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"castellan_search_tools","arguments":{"query":"deposit"}}}' \
  | castellan mcp

Describe before invoking (avoid -32602):

echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"castellan_describe_tool","arguments":{"name":"castellan_deposit_signal"}}}' | castellan mcp

Wire Cursor: see Cursor setup.

Related

• MCP tools reference
• MCP overview
• Agent guide