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.

Install the Crusader Agent Skills

Skill-aware agents can also load Crusader's published workflows from crusadersecurity/Skills. These skills do not replace the MCP server; they teach the agent how to use agent.guide, scope-safe orientation, oracle-confirmed findings, Beacon/OAST, races, identity replay, verdict triage, and crusader://poc/ packaging.

# Hunting workflow
pnpm dlx skills add crusadersecurity/Skills --skill='crusader-mode'

# Findings triage workflow
pnpm dlx skills add crusadersecurity/Skills --skill='crusader-triage'

# Both skills
pnpm dlx skills add crusadersecurity/Skills --skill='*'

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.

The guide is generated by the running binary and includes the current JSON contract: continuous_use, planning_loop, data_access_model, sitemap_defaults, scope_management, feature_catalog, and the current mcp_tools list. Treat this page as a human map; treat agent.guide as the exact contract for the installed build.

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.

05Current MCP tool families

The current tool catalog is generated by the running binary. agent.guide and crusader mcp tools are the authoritative source for exact names, tier gates, and feature gates. At a high level, the surface is organized like this:

Free keeps agents on safe project-reading and planning paths. Hunter Pro unlocks the write-capable and traffic-sending families, plus advanced proof surfaces. Either way, the guide repeats the same safety rule: default to safe history and scoped planning, then call active tools explicitly when you mean to send traffic.

06What a gated tool returns on Free

Calling a gated 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-capable families 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.

Safety defaults agents should preserve

• Safe history first. Use history.search_safe and history.get_safe for broad triage. They expose method, host/path, status, redirects, header names, cookie names, and key-path classes without raw secrets.
• Scope is explicit. If scope.list reports open_scope=true or needs_scope_setup=true, call scope.suggest and ask which target patterns to add before active traffic. scope.add, scope.remove, and scope.reset only change project scope; they do not send target traffic.
• Sitemap is filtered for planning. sitemap.tree hides low-signal ghost static assets by default, including JS bundles, SVGs, images, CSS, fonts, and source maps. Use include_low_signal_ghosts=true only for explicit static asset or source review.
• Replay starts pristine. MCP repeater.send applies no saved or active identity unless identity_id or apply_active_identity=true is passed, and inherits no same-host cookies unless inherit_cookies=true is passed.

Planner branches include identity_compare, auth_boundary_compare, server_error_cluster_review, ghost_endpoint_review, transport_matrix, mutating_endpoint_preflight, websocket_frame_review, finding_escalation_plan, and project_orientation. The frontier defaults to in-scope actionable branches so old or out-of-scope project noise does not steer the hunt.

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 active tools

That's expected on Free. Run crusader mcp tools (or crusader license status) to see your tier and which tool families it exposes. Gated tools 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 gated 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 safe read-only project tools.

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 [email protected].