Keel

What Keel MCP server does

The Keel MCP server provides a control plane for authorized web security testing. An AI client communicates with Keel rather than invoking httpx, Nuclei, curl, or shell commands directly. Keel registers an engagement, validates scope, proposes small scan waves, queues background jobs, and exposes progress and cancellation controls.

Scanner observations are consolidated into semantic cards using vulnerability class, normalized route, method, and parameter. Related identifiers such as UUIDs, numeric IDs, and hexadecimal tokens can collapse into one finding. Cards move through evidence states including observed, hypothesis, corroborated, proven, and refuted. Informational and hardening results are excluded from the main triage view.

How it works

Start with begin_engagement, supplying an engagement ID and plain hostname scope. draft_waves prepares reachability and template micro-waves without making requests. execute_wave queues one job, while wave_status reports progress and results and cancel_wave stops queued or active scanning.

The scheduler permits one active wave per host and uses shared and per-host token buckets. Its documented defaults are 3 requests per second, a 120-second wave limit, and 120 requests per wave. Nuclei execution uses signed HTTP templates with concurrency set to one; OAST, redirects, retries, and intrusive, denial-of-service, fuzzing, and brute-force tags are excluded. HTTP 429 responses create a cooldown.

After scanning, query_cards returns prioritized findings. assess_exploitability identifies candidate impact, missing evidence, negative controls, and available playbooks. state_impact records a hunter hypothesis. engagement_health reports cooldowns, budgets, and pending waves, while engagement_audit exposes append-only application events.

Setup and configuration

Install Python 3.10 or newer, then install the keel-pentest package with pipx. The setup command downloads ProjectDiscovery httpx and Nuclei into ~/.keel/bin; doctor checks the installation. Configure an MCP client to launch the keel-pentest executable over stdio. The documented examples include Claude’s MCP command and Codex’s MCP command.

Use KEEL_CREDENTIALS_FILE to store tester credential secrets when proofs need them; tool calls should provide credential names rather than secret values. KEEL_APPROVAL_FILE is an optional team manifest for pinning scope, template IDs, and proof targets. Without it, authorization is self-attested through begin_engagement.

Tools and capabilities

The Keel MCP server exposes thirteen tools covering engagement setup, wave scheduling, status, cancellation, semantic triage, second looks, exploitability assessment, impact hypotheses, proof planning and execution, health checks, and audit records.

Safe proofs require draft_proof followed by execute_proof. Available playbooks cover cross-account reads, reflected markers, open-redirect canaries, unauthenticated access checks, and tester-owned session reachability. Proof requests are GET-only, budgeted, and restricted to allowlisted plans. Results include status codes, canary checks, truncation flags, hashes, impact text, and a replay script; response bodies and secrets are not persisted.

Limitations and notes

Use Keel only on programs and hosts you are authorized to test. Proofs need tester-owned data and, for cross-account or unauthenticated checks, a non-secret canary placed in the relevant object. The own-session playbook establishes reachability but never proves a vulnerability. A proven result depends on the playbook invariant; protected controls are treated as refuted.

The system is intentionally bounded: it does not provide writes, shells, payload spraying, OAST, redirects, or intrusive scanning. Its default scope and traffic controls remain in force even when optional approval configuration is not used.