Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Armur-Ai/Pentest-Swarm-AI/llms.txt

Use this file to discover all available pages before exploring further.

The Model Context Protocol (MCP) is an open standard that lets AI clients call external tools over a structured JSON-RPC interface. Running pentestswarm mcp serve exposes the full pentestswarm tool set — scans, recon, campaign status, finding explanation — to any MCP-compatible client over stdio. This means you can drive an autonomous penetration test directly from a conversation in Claude Desktop or Cursor, with the AI deciding which tools to invoke and in what order.

​
Start the MCP server

pentestswarm mcp serve
The server starts immediately and writes a startup message to stderr: 
pentestswarm MCP server started (stdio)
All JSON-RPC traffic flows over stdin / stdout. The server implements the MCP 2024-11-05 protocol version and exposes tools and resources capabilities. It stays alive until the client disconnects or the process receives a signal. The server reads your API key from the same sources as the CLI — config.yaml first, then PENTESTSWARM_ORCHESTRATOR_API_KEY, then ANTHROPIC_API_KEY: 
export ANTHROPIC_API_KEY=sk-ant-your-key-here
pentestswarm mcp serve

​
Claude Desktop configuration

Add pentestswarm to your Claude Desktop MCP server list. Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on your OS: 
{
  "mcpServers": {
    "pentestswarm": {
      "command": "pentestswarm",
      "args": ["mcp", "serve"]
    }
  }
}
Restart Claude Desktop after saving. The pentestswarm tools appear in Claude’s tool panel — you can now ask Claude to run recon against a domain, start a full scan, or explain a finding, and Claude will call the appropriate MCP tool.

​
Cursor integration

Cursor uses the same MCP configuration format. Open Cursor Settings → Features → MCP and add a new server: 
{
  "mcpServers": {
    "pentestswarm": {
      "command": "pentestswarm",
      "args": ["mcp", "serve"]
    }
  }
}
Once added, Cursor’s AI composer can invoke pentestswarm tools inline while you are editing code. Ask it to scan a staging domain, check a dependency for known CVEs, or explain a security finding in the context of your codebase.

​
Available MCP tools

The following tools are registered by RegisterDefaultTools in internal/mcp/tools.go:
Tool nameDescriptionRequired inputs
scan_targetStart a full autonomous penetration test against a target. Returns findings summary when complete.target (string), scope (string)
quick_reconRun reconnaissance only against a target, returning the discovered attack surface (subdomains, ports, services, technologies).target (string)
explain_findingExplain a security vulnerability in plain English, tailored to the specified audience.description (string)
campaign_statusGet the current status of a running penetration test campaign.campaign_id (string)
list_toolsList all available security scanning tools and their status.(none)

​
Tool schemas

{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "description": "Target domain or IP"
    },
    "scope": {
      "type": "string",
      "description": "Scope (CIDR or domain)"
    },
    "objective": {
      "type": "string",
      "description": "What to find (default: find all vulnerabilities)"
    }
  },
  "required": ["target", "scope"]
}
Runs a 20-minute timeout campaign. Returns all campaign event strings as text — one line per agent event in the format [EventType] AgentName: detail.
{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "description": "Target to scan"
    }
  },
  "required": ["target"]
}
Runs a recon-only campaign with DryRun: true (no exploitation). Returns only EventToolResult and EventFindingDiscovered events — the discovered attack surface without any active exploitation output.
{
  "type": "object",
  "properties": {
    "description": {
      "type": "string",
      "description": "Vulnerability description or CVE ID"
    },
    "audience": {
      "type": "string",
      "enum": ["developer", "manager", "executive"],
      "description": "Target audience for the explanation"
    }
  },
  "required": ["description"]
}
Generates an audience-appropriate explanation of the vulnerability. Defaults to developer if audience is omitted.
{
  "type": "object",
  "properties": {
    "campaign_id": {
      "type": "string",
      "description": "Campaign UUID"
    }
  },
  "required": ["campaign_id"]
}
Returns the campaign’s current status and a link to the REST API endpoint for full detail.
{
  "type": "object",
  "properties": {}
}
Returns the list of available security scanning tools:
  • subfinder — passive subdomain discovery
  • httpx — HTTP probing with technology detection
  • nuclei — template-based vulnerability scanning
  • naabu — fast port scanning
  • katana — web crawling and endpoint discovery
  • dnsx — DNS resolution and reverse lookups
  • gau — fetch known URLs from Wayback Machine, Common Crawl

​
MCP server internals

The server speaks JSON-RPC 2.0 over stdin/stdout with newline-delimited messages. It handles four MCP methods:
MethodWhat it does
initializeReturns protocol version 2024-11-05 and capability declarations
tools/listReturns all registered tool names, descriptions, and input schemas
tools/callDispatches to the named tool’s handler function
resources/listReturns registered MCP resources
resources/readReturns the content of a resource by URI
Unknown methods return a JSON-RPC -32601 (Method not found) error. Parse errors return -32700. Tool errors are returned as isError: true content rather than JSON-RPC errors, following MCP convention.
The MCP server requires a valid API key to run scans — it reads from config.yaml, then PENTESTSWARM_ORCHESTRATOR_API_KEY, then ANTHROPIC_API_KEY. Make sure at least one of these is set before starting the server. The list_tools and explain_finding tools work without a key; scan_target, quick_recon, and campaign_status require one.
MCP mode is ideal for interactive, AI-assisted pentesting sessions where you want to explore a target iteratively — run recon, ask Claude to interpret the results, then decide whether to escalate to a full scan or run a targeted playbook. This is fundamentally different from a scripted CI scan: the human stays in the loop at every decision point, with the AI and the swarm acting as a force multiplier.

Bug Bounty

Use MCP to drive bug bounty scope imports and scan launches interactively.

Playbooks

Ask Claude to pick and run the right playbook for a given target via MCP.

GitHub Actions

Automate the same scans in CI without interactive oversight.

CTF Mode

Drive CTF solves conversationally with live event streaming via MCP.

Build docs developers (and LLMs) love

Get started for freeTalk to us