Drive Crusader from Claude Code (MCP)

01Why drive Crusader from an agent

An MCP client gives a coding agent first-class access to the same project an analyst works in — the captured history, the site map, the scope, the saved identities — without screen-scraping a GUI or shelling out blind. The agent reads structured results, reasons over them, and (on Hunter Pro) replays requests, runs the passive and active scanner, and files findings, all inside your local workspace.

Two things keep this safe to hand to an agent:

• A read-only floor. On Free the server exposes only read tools. An agent can search history, walk the site map, and rank next moves, but it cannot send a single packet at a target.
• Plan, don't fire. Even with the full write tool set, the planning loop's agent.plan.commit writes a task pack — an ordered, scoped plan — and never auto-executes network actions. A human (or an explicit tool call) pulls the trigger.

02Step 1 — Start the MCP server

The server runs over stdio: JSON-RPC framed as JSONL on stdin/stdout. There is no HTTP transport — your MCP client launches the crusader process and talks to it through the pipe, so nothing listens on a port.

# start the MCP server (your client normally launches this for you)
crusader mcp serve

# print the tool catalog + a license snapshot, then exit
crusader mcp tools

The handshake reports protocol version 2025-11-25 and serverInfo.name crusader. Its initialize response instructs clients to call agent.guide before anything else — see Step 3. Run crusader mcp tools any time to see exactly which tools your current license exposes.

03Step 2 — Connect your client

Crusader can print the wiring for you. crusader agent mcp-config emits a connection JSON block; add --toml for a Codex config.toml block.

Claude Code

The fastest path is the Claude Code CLI — it registers the server in one command:

claude mcp add crusader -- crusader mcp serve

Prefer editing config by hand? Use the generic mcpServers form that Crusader emits. Drop this into your client's MCP config:

{
  "mcpServers": {
    "crusader": {
      "command": "crusader",
      "args": ["mcp", "serve"]
    }
  }
}

Codex

For Codex, print the TOML and paste it into your global config at %USERPROFILE%\.codex\config.toml:

crusader agent mcp-config --toml

Then start (or restart) Codex and confirm the server registered with /mcp in the Codex TUI. The same /mcp check works to list Crusader's tools once it's connected.

04Step 3 — Call agent.guide first

Every session starts with agent.guide. The initialize handshake tells clients to call it before anything else, and it's the one tool that orients the agent: it points at the current project, the scope, and the right next tools to use — so the agent isn't guessing at your engagement.

From there the agent orients with the other read tools — project.current, scope.list, history.search_safe, and sitemap.tree — before it plans anything. The _safe variants return redacted results suitable for an agent's context window (no raw cookies, tokens, or bodies); the plain history.search / history.get return full detail when you need it.

05Free vs Hunter Pro tools

The tool set splits cleanly by tier. Free exposes 17 read-only tools — enough for an agent to fully understand a project and rank what to do next, without touching the target. Hunter Pro adds 23 write tools (gated by FullMcp; a few need extra features such as ActiveScanner) that actually send traffic, file findings, and run hunts.

The pattern is consistent: Free can look and plan; Pro can act. An agent on Free can search every exchange, walk the site map, check whether a URL is in scope, list your identities, and rank a next move — it simply can't send a request, mutate scope, write a finding, or commit a plan.

06What a Pro tool returns on Free

Calling a Hunter Pro tool on a Free license does not throw an exception — it returns a structured, machine-readable result the agent can branch on. The shape:

{
  "ok": false,
  "code": "requires_upgrade",
  "statusText": "...",
  "error": "...",
  "message": "...",
  "feature": "...",
  "feature_name": "...",
  "required_tier": "...",
  "hint": "Run `crusader license status`...",
  "license": { /* current license snapshot */ }
}

Because ok is false and code is requires_upgrade, an agent can detect the gate and fall back to a read-only plan instead of crashing. The feature / required_tier fields name exactly what's missing, and the hint points at crusader license status. The 14-day Hunter Pro trial unlocks the write tools with just an email (no card); see pricing or the in-app License & billing screen.

07The agent-memory planning loop

Crusader gives agents a project-local, redacted memory and a planner so a hunt is deliberate, passive-first, and reproducible. Memory lives in agent_memory.db next to the project's history.db and stores redacted summaries, refs, fingerprints, task packs, and outcomes — never raw cookies, tokens, or bodies.

The loop, in order:

1. Orient. agent.guide, then project.current, scope.list, history.search_safe, sitemap.tree.
2. Extract. agent.memory.extract distills the project into redacted memory.
3. Rank a next move. agent.next_move returns ranked, passive-first suggestions.
4. Build a plan. agent.plan.init then agent.plan.expand — these generate no traffic.
5. Inspect & verify. agent.plan.frontier shows the live edge of the plan; agent.plan.verify checks it.
6. Commit. agent.plan.commit writes a task pack only — it never auto-executes network actions.
7. Record. agent.plan.record_outcome and agent.memory.write close the loop so the next session starts smarter.

The same loop is available from the CLI for scripting or CI: crusader agent guide|status|next|memory|plan|mcp-config|tools, with agent memory extract|search|write|status and agent plan init|expand|frontier|verify|commit|outcome.

08Troubleshooting

The client can't find or launch the server

Your MCP client runs the crusader binary directly, so it has to be on the PATH the client sees. Confirm crusader mcp serve runs from a fresh terminal; if it does there but not in the client, point the config's command at the absolute path to the binary.

The server starts but exposes no write tools

That's expected on Free. Run crusader mcp tools (or crusader license status) to see your tier and which tools it exposes. Pro tools are present in the catalog but return requires_upgrade until you're on Hunter Pro or the 14-day trial.

A tool call comes back { "ok": false, "code": "requires_upgrade" }

The agent called a Hunter Pro tool on a Free license. This is a structured result, not an error — check the feature and required_tier fields. Either start the trial / upgrade, or have the agent stick to the read-only tool set.

The agent tried to connect over HTTP

There is no HTTP transport — Crusader's MCP server is stdio only. Use the mcpServers command/args form (or claude mcp add crusader -- crusader mcp serve) so the client launches the process and talks over the pipe.

Codex shows no Crusader tools

Re-run crusader agent mcp-config --toml, confirm the block landed in %USERPROFILE%\.codex\config.toml, restart Codex, and check with /mcp in the TUI.

Want a guide that isn't here yet? Email hello@crusaderproxy.com.