Cursor setup

Outcome: wire Cursor as an operator — MCP tools for field/mux, pane agents for work.

Use Castellan in Cursor via MCP (castellan mcp). ACP is available for experiments (Zed-class editors) but MCP is the primary Cursor path.

Install

git clone https://github.com/Alphabetsoup16/Castellan.git && cd Castellan
./install.sh
export PATH="$PWD/target/release:$PATH"

Wire MCP in Cursor

Add a server entry to Cursor MCP config (Settings → MCP, or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "castellan": {
      "command": "/path/to/Castellan/target/release/castellan",
      "args": ["mcp"]
    }
  }
}

Set command to your built target/release/castellan path — Cursor spawns this exact binary, so a relative path or an unbuilt release binary will fail silently in the MCP panel. Restart Cursor after editing the config; MCP servers are loaded once at startup.

Discovery flow: castellan_search_tools → castellan_describe_tool → invoke. Full catalog: MCP tools.

First smoke

castellan run --goal "reach target" --plugin gridworld

castellan run --goal "reach target" --plugin gridworld --json

castellan mcp

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

Then in Cursor: open the MCP panel (Settings → MCP → castellan) and confirm the server shows connected with tools listed. Ask the agent to call castellan_discover_tools to verify the wire end-to-end.

MCP vs ACP

Path	Cursor use
`castellan mcp`	Primary — tool discovery, substrate read/write, same registry as live episodes
`castellan acp`	Experimental — in-process prompt bridge, no MCP tool bridging in Cursor today

Failure paths

Symptom	Likely cause	Fix
Server shows “no tools” in MCP panel	Binary not built, or wrong `command` path	`cargo build --release -p castellan-cli`; verify path with `which castellan` or absolute path
Server never connects	Cursor cached a stale process	Restart Cursor fully (not just reload window)
Tool call returns `-32601`	Tool name typo or stale Cursor cache of `tools/list`	Re-run `tools/list`; check name against MCP tools
Agent invents a tool name	Model hallucination, not a Castellan bug	Instruct the agent to call `castellan_discover_tools` before guessing
Deposits rejected	Governance `pre_execute` hook denied	Check `castellan.toml` governance section; see Governance

Skills and memory

Skills: .castellan/skills/ and ~/.cursor/skills/ are both scanned on castellan run.

Memory is the substrate (blackboard, field, episodes) — see Memory architecture. Vector RAG is deferred. Maintainer SQL schema and trait detail: MEMORY_ARCHITECTURE.md.

Agent onboarding

For paste-into-agent context: Agent guide.

Keyboard shortcuts

Castellan