shieldpi-mcp 0.4.0

MCP server for ShieldPi Watchtower — run LLM security scans, generate drop-in guardrails from scan findings, operate the AI SOC analyst (incident triage + kill-chain reconstruction), and query the live agent monitor from Claude Desktop / Cursor / Continue.

shieldpi-mcp

MCP server for ShieldPi Watchtower — query 27,000+ LLM attack techniques, run scans, pull breach forensics, generate drop-in runtime guardrails from scan findings, and operate the Live Agent Monitor SOC from Claude Desktop / Cursor / Continue.

ShieldPi is the AI SOC platform:

• Scanner — 27,024+ attack techniques × 4 scan modes (Browser / API / Agent / Model), ExploitDepth L1–L4 scoring, and forensic kill-chain narratives with extracted breach evidence.
• Runtime monitor — the shieldpi SDK. Zero-code-change install for LangChain / LangGraph / OpenAI Assistants / Anthropic SDK: pip install "shieldpi[all]" then import shieldpi.auto. Every tool call, LLM call, and user message streams to ShieldPi's six detectors in real time.
• Auto-guardrails (new in v0.3.0) — every L2+ finding from a scan becomes a deployable runtime guardrail. Export as drop-in Python middleware, LangChain callback, or NeMo Colang.

This MCP server exposes all three surfaces inside any MCP-compatible LLM session.

What you get — 23 tools

Tier	Tool	API key?	Use it for
1	get_methodology	no	Pull the V7 scoring + dedup + judge methodology
1	get_attack_graph	no	Cross-customer success-rate graph by technique × model family
1	get_model_families	no	ShieldPi's family taxonomy + similarity edges
1	get_leaderboard_feed	no	Live data behind shieldpi.info
1	get_leaderboard	no	Top models by best security score
1	get_model_registry	no	All 38+ models ShieldPi can test
2	list_attack_categories	yes	The 15 categories + OWASP mappings
2	list_attack_techniques	yes	Browse the 27k catalog with filters
2	start_scan	yes	Kick off a scan against a target
2	get_scan_status	yes	Poll an in-progress scan
2	get_scan_intelligence	yes	Breach-forensics package for a completed scan
2	get_scan_guardrails	yes	Auto-generated runtime guardrails from scan findings
2	export_scan_guardrails	yes	Export guardrails as Python / LangChain / NeMo Colang
2	get_incidents 🆕	yes	AI-triaged incidents (clusters of related alerts)
2	get_incident_detail 🆕	yes	Kill chain + linked alerts + AI verdict for one incident
2	trigger_triage 🆕	yes	Run an on-demand triage pass (sync; beat also runs 60s)
2	set_incident_status 🆕	yes	Human override: escalate / resolve / suppress
2	get_live_alerts	yes	Runtime alerts from deployed monitored agents
2	get_alert_detail	yes	Full forensic detail for one alert (kill chain replay)
2	acknowledge_alert	yes	Mark an alert as triaged
2	resolve_alert	yes	Mark an alert as resolved
2	list_monitor_sessions	yes	Sessions across all monitored agents
2	get_session_events	yes	Full event chain for one session

🆕 = new in v0.4.0 (AI SOC analyst). Incidents are Claude-triaged clusters of raw alerts; each carries a structured verdict with severity, false-positive likelihood, attacker intent, kill-chain reconstruction, and a recommended action. A background Celery beat job runs triage every 60 seconds; trigger_triage forces an immediate run.

Tier-1 works the moment you install. Tier-2 needs a free ShieldPi API key — get one at shieldpi.io/dashboard/api-keys.

Companion: the shieldpi SDK

The MCP server is the read side of ShieldPi — it queries scans, alerts, and guardrails. The write side (capturing agent events in the first place) is the shieldpi Python SDK. In any monitored agent:

pip install "shieldpi[all]"
export SHIELDPI_SDK_KEY=shpi_live_...

import shieldpi.auto   # ONE line, zero code changes

That's it — LangChain / LangGraph / OpenAI Assistants / Anthropic tool-use calls are auto-captured. Alerts land in your dashboard, flow to Slack via webhook, and are queryable here via get_live_alerts. See the docs for the full wiring.

Install

Recommended (works on every OS, puts shieldpi-mcp on your $PATH):

pipx install shieldpi-mcp

Don't have pipx? brew install pipx && pipx ensurepath (macOS) or python3 -m pip install --user pipx && pipx ensurepath (Linux/Windows).

Why pipx: Claude Desktop / Cursor / Continue look up shieldpi-mcp on $PATH. pipx handles that automatically. Plain pip install may put the entry point somewhere your MCP client can't find.

Alternative — pip with an explicit modern Python (Python 3.10+ is required):

python3.11 -m pip install --user shieldpi-mcp
# then add ~/Library/Python/3.11/bin (macOS) or ~/.local/bin (Linux) to your PATH

If you see ERROR: Could not find a version that satisfies the requirement shieldpi-mcp, your default pip is using a Python older than 3.10 (common on macOS, where the system python3 is 3.9). Use pipx or pick a modern Python explicitly as above.

Or with uv:

uv tool install shieldpi-mcp

The package ships a shieldpi-mcp console entry point that runs the server over stdio — that's what every MCP client expects.

Configure your client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "shieldpi": {
      "command": "shieldpi-mcp",
      "env": {
        "SHIELDPI_API_KEY": "shpi_live_..."
      }
    }
  }
}

Restart Claude Desktop. Look for the 🔌 plug icon — shieldpi should be listed with 23 tools.

Claude Code

claude mcp add shieldpi -- shieldpi-mcp

Then set the env var in the same shell or in your .envrc:

export SHIELDPI_API_KEY="shpi_live_..."

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "shieldpi": {
      "command": "shieldpi-mcp",
      "env": { "SHIELDPI_API_KEY": "shpi_live_..." }
    }
  }
}

Continue (VS Code / JetBrains)

In ~/.continue/config.json:

{
  "mcpServers": {
    "shieldpi": {
      "command": "shieldpi-mcp",
      "env": { "SHIELDPI_API_KEY": "shpi_live_..." }
    }
  }
}

Try it

Once installed and configured, ask your LLM:

"Using the shieldpi tools, what's the current security ranking of Claude Sonnet 4.5 vs GPT-4o?"

"Pull the ShieldPi methodology and explain ExploitDepth scoring in plain English."

"Browse the prompt_injection category in the ShieldPi attack catalog and pick 3 techniques worth testing on my agent."

"Start a model-mode scan against anthropic/claude-sonnet-4.5 and report when it's done."

"Get the auto-generated guardrails for scan <uuid> as a LangChain callback I can paste into my agent."

"Check get_live_alerts for anything critical on my production agents in the last hour, group by detector, and walk me through the worst one via get_alert_detail."

"Call get_incidents with severity=critical. For each incident that isn't already suppressed, pull get_incident_detail, summarize the AI kill-chain reconstruction, and tell me which one deserves human escalation."

"Run trigger_triage on target {uuid} to get fresh verdicts on the last hour of alerts, then list any new incidents flagged as false positives."

Environment variables

Variable	Default	Purpose
SHIELDPI_API_KEY	(none)	Required for tier-2 tools (techniques catalog, scans). Free tier works.
SHIELDPI_API_BASE	https://api.shieldpi.io	Override for self-hosted ShieldPi or staging.
SHIELDPI_TIMEOUT	30	Per-request timeout in seconds.

Develop

git clone https://github.com/ShieldPi1/shieldpi-watchtower.git
cd shieldpi-watchtower/mcp-server
pip install -e ".[dev]"
pytest

The test suite hits live api.shieldpi.io for tier-1 endpoints and skips tier-2 unless SHIELDPI_API_KEY is set.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│            Claude Desktop / Claude Code / Cursor                 │
│                  (MCP Client over stdio)                         │
└──────────────────────────────┬──────────────────────────────────┘
                               │ MCP (JSON-RPC over stdio)
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    shieldpi-mcp (Python)                         │
│  ┌──────────────┐  ┌─────────────────┐                          │
│  │  10 MCP      │  │ ShieldPiClient  │                          │
│  │  tools       │  │   (httpx)       │                          │
│  └──────┬───────┘  └────────┬────────┘                          │
└─────────┼───────────────────┼────────────────────────────────────┘
          │                   │ HTTPS outbound only
          │                   ▼
          │       ┌─────────────────────────────┐
          │       │  https://api.shieldpi.io   │
          │       │  (FastAPI on Hetzner)       │
          │       └─────────────────────────────┘
          ▼
   stdout (MCP responses)

Outbound HTTPS only. No inbound ports. API keys are read from env vars, never logged. The server is single-process, stateless across requests — safe to drop into any client.

License

MIT. See LICENSE.

Links

• Product: shieldpi.io
• Leaderboard: shieldpi.info
• Methodology: shieldpi.io/methodology
• Research: shieldpi.io/research
• Issues: github.com/ShieldPi1/shieldpi-watchtower/issues