@spys/mcp

⚠️ PRE-RELEASE — NOT YET FUNCTIONAL. Active development. Wait for 1.0.0 before installing — earlier versions (including this one) will not work end-to-end against production. Watch the npm page or the repo release feed for the 1.0.0 announcement.

MCP bridge to Spys.io — AI-native pentest toolkit with 90+ offensive security tools.

What it is

Connects your MCP-compatible AI client (Claude Desktop, Cursor, Cline, custom agents) to Spys.io infrastructure. Your agent gets access to a full pentest toolkit through a single MCP server.

Production-ready infrastructure for agentic pentesting: rewritten and enhanced versions of the tools red teamers actually use, plus custom-built tooling, paired with one of the largest curated knowledge bases of vulnerabilities, detection methodologies, and attack vectors. Built for AI agents from the ground up.

Zero setup — drop the MCP entry into your client config, paste the token, done. Outbound WSS only, so a public IP on your side is not required.

What's inside

• 90+ tools covering recon, web exploitation, network attacks, AD, cloud, post-exploitation, and reporting
• AI-augmented execution — AI works alongside each tool during runtime: refines parameters, recovers from errors, and optimizes results on the fly. Outputs are structured and agent-ready, no raw stdout parsing required.
• Context-efficient discovery — semantic search over the toolset (1.5K tokens) instead of dumping all tools into context (20K tokens)
• Actionable error responses — when something fails, the agent knows exactly what happened and what to do next. No guessing, no retry loops on vague "something went wrong" messages.
• Rewritten & custom-built tools — standard offensive tooling (sqlmap, nuclei, ffuf, BloodHound, hashcat, etc.) rewritten for AI orchestration, plus proprietary tools built from scratch for capabilities you won't find elsewhere

Tool categories

Recon & OSINT · Network & ports · TLS & crypto · Web & HTTP · Injection & vuln scanning · Active Directory · Post-exploit & C2 · Cloud · SAST/SCA · Reporting · Knowledge base

Configure your MCP client

{
  "mcpServers": {
    "spys": {
      "command": "npx",
      "args": ["-y", "@spys/mcp", "mcp"],
      "env": { "TOKEN": "spys_<your-token>" }
    }
  }
}

That's it — no install step. The bridge opens an outbound WSS to Spys.io; scan traffic is tunneled back through your own machine, so targets see your NAT-translated IP rather than ours.

Optional shell login if you'd rather keep the token out of your editor's config file:

npx -y @spys/mcp login spys_<your-token>   # writes ~/.spys/config.json @ 0600

Scan capability

All egress is userspace TCP / UDP. That gives you:

• TCP connect scan — full coverage including service / version detection and the entire NSE corpus.
• UDP probe scan — well-known protocols (DNS / NTP / SNMP / NetBIOS / SSDP / mDNS) get protocol-correct probes; everything else gets an empty datagram. Reports open (definite) vs no_reply (closed OR filtered OR open-but-silent — indistinguishable without raw ICMP).
• Out of scope: SYN-stealth, FIN / Xmas / NULL / ACK, OS fingerprinting. Run those from a box where you control raw sockets.

Supported platforms: any Node 20+ host (Linux x64 / arm64, macOS x64 / arm64, Windows 10+ x64 / arm64).

Diagnostics

spys-mcp doctor       # token + endpoint health, JSON output
spys-mcp status       # current config

Links

• Docs: https://docs.spys.io
• Tool reference: https://docs.spys.io/tools