Skip to content

MCP Mode#

APHIDS exposes all 40+ security tools as an AI-native Model Context Protocol (MCP) server. This allows AI assistants like Claude Desktop, Windsurf, and Cursor to use security tools directly through natural language.

Quick Start#

# Install with MCP support
pip install "aphids-cli[mcp] @ git+https://github.com/darksidesecurity/aphids.git"

# Start MCP server (offline)
aphids-cli --mcp

# Start MCP server (with Hive)
APHIDS_API_KEY="your-key" aphids-cli --mcp

How It Works#

  1. APHIDS starts an MCP server over stdio (or HTTP)
  2. The AI client discovers all available security tools automatically
  3. The AI can invoke any tool with natural language (e.g., "scan example.com with nmap")
  4. Results are returned as structured data the AI can analyze
  5. In online mode, results are also uploaded to Hive

Transport Modes#

Stdio (Default)#

Standard I/O — works with Claude Desktop, Windsurf, Cursor, and any MCP-compatible client:

aphids-cli --mcp

SSE (HTTP + Server-Sent Events)#

Legacy MCP remote transport:

aphids-cli --mcp --sse --host 0.0.0.0 --port 8000

Streamable HTTP#

Modern single-endpoint HTTP transport (MCP 2025-03-26+):

aphids-cli --mcp --stream --host 0.0.0.0 --port 8000

Client Configuration#

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aphids": {
      "command": "aphids-cli",
      "args": ["--mcp"],
      "env": {
        "APHIDS_API_KEY": "your-key-here"
      }
    }
  }
}

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "aphids": {
      "command": "aphids-cli",
      "args": ["--mcp"],
      "env": {
        "APHIDS_API_KEY": "your-key-here"
      }
    }
  }
}

Add to Cursor's MCP settings:

{
  "mcpServers": {
    "aphids": {
      "command": "aphids-cli",
      "args": ["--mcp"],
      "env": {
        "APHIDS_API_KEY": "your-key-here"
      }
    }
  }
}

Available Tools#

When you start APHIDS in MCP mode, the AI client gets access to:

Security Tools (30+)#

All standard APHIDS tools are available — nmap, nuclei, nikto, zap, sqlmap, etc. The AI can invoke them with natural language:

  • "Run an nmap service scan on 10.0.0.1"
  • "Check example.com for subdomain enumeration using subfinder"
  • "Scan my project for secrets with gitleaks"
  • "Run nuclei against https://example.com"

Workspace Tools#

For static analysis on local code:

  • run_semgrep — Static code analysis
  • run_gitleaks — Secret scanning
  • run_trufflehog — Secret detection
# Mount a workspace directory
aphids-cli --mcp --mcp-workspace /path/to/project

Admin Tools (Online Mode)#

When connected to Hive, additional tools are available:

Tool Description
set_engagement Configure engagement, scan group, team, and access
get_engagement Retrieve current engagement configuration
submit_findings Push vulnerability findings to Hive graph
submit_assets Submit discovered assets (URLs, IPs, domains, ports, applications)

Workspace Support#

Mount a local directory for SAST tools:

aphids-cli --mcp --mcp-workspace /path/to/your/project

The workspace is mounted read-only at /workspace inside the container. Tools like Semgrep, Gitleaks, and TruffleHog will scan this directory.

Tool Discovery & Caching#

APHIDS discovers available tools from the container on first run and caches the registry:

  • Cache location: ~/.aphids/cache/tool-registry.json
  • Cache TTL: 24 hours
  • Force refresh: aphids-cli --mcp --mcp-refresh

Security#

MCP mode includes comprehensive security hardening:

  • Input validation — Type checking for all parameters
  • Path traversal prevention — Canonicalized paths, symlink detection
  • Command injection prevention — Shell metacharacter filtering
  • SSRF protection — Blocks localhost and private network targets
  • DoS prevention — Max string length (2048), max array size (100)
  • Null byte detection — Rejects null bytes in all inputs
  • Error sanitization — Internal paths stripped from error messages
  • Read-only mounts — Workspace directories mounted as read-only
  • Network isolation — SAST tools run with --network none

Timeouts#

Setting Default Maximum
Per-tool timeout 30 minutes 2 hours
Output truncation 500 KB —

Configure default timeout:

export APHIDS_TOOL_TIMEOUT=3600  # 1 hour
aphids-cli --mcp