shieldpi-mcp

MCP server for ShieldPi Watchtower — query the LLM attack catalog, 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 — an attack catalog with Browser / API / Agent / Model scan modes, 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 configured 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.

Catalog and model availability change over time. Query list_attack_categories, list_attack_techniques, and get_model_registry for the current data and any reported totals; consult get_methodology for the published scope and scoring method. A registry entry does not by itself mean a model has been tested. See the leaderboard for published results and dates.

Available tools

Tier	Tool	API key?	Use it for
1	get_methodology	no	Pull the published 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	Published leaderboard data
1	get_leaderboard	no	Top models by best security score
1	get_model_registry	no	Query the current model registry
2	list_attack_categories	yes	Current attack categories + OWASP mappings
2	list_attack_techniques	yes	Browse the current attack 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
2	set_incident_status	yes	Human override: escalate / resolve / suppress
2	get_onboarding_status 🆕	yes	Account setup checklist — derived from live account state
2	download_scan_bundle 🆕	yes	CI bundle manifest (report + available guardrail formats + stats)
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.5.0 (customer onboarding + CI bundle). get_onboarding_status returns a live checklist (API key → first target → monitored agent → SDK event → webhook → first alert) derived from account state, so progress reflects the returned account data. download_scan_bundle returns a manifest + curl command for a zip containing report.json + report.pdf + the available guardrail formats, shaped for CI pipelines that want one curl + one unzip.

v0.4.0 shipped the AI SOC analyst (incident triage, kill-chain reconstruction, human override). Scheduled triage depends on the deployment configuration; trigger_triage requests an on-demand run.

Tier-1 does not require an API key, but requires access to the configured ShieldPi API. Tier-2 needs a ShieldPi API key — get one at shieldpi.io/dashboard/api-keys.

Companion: the shieldpi SDK

The MCP server queries scans, alerts, and guardrails and provides explicit actions such as scan creation and alert updates. Agent event capture is handled by 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 list its available 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 my configured target <target-uuid> and report its scan ID."

"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."

"Use get_onboarding_status to check my setup. For every step that's still pending, tell me exactly what to click and give me the copy-paste snippet."

"Call download_scan_bundle for scan {uuid} and give me a curl command I can drop into our GitHub Actions workflow so every CI run writes guardrails to our repo."

Starting scans

Use start_scan(target_id="<target-uuid>", mode="model") for an existing model target configured with a BYOK credential in the dashboard. The tool loads that target and starts the scan using its stored mode and credentials. It does not create a model target from a slug or URL, accept provider secrets, or provision BYOK credentials. A model request without target_id is refused locally.

For browser, API, or agent scans, supply an existing target_id or create a new target by passing target_url and mode. For new API targets, api_format and api_model describe the endpoint; configure any required endpoint credentials on a saved target first. Existing target configuration takes precedence over new-target arguments. Backend permissions, plan limits, and scan validation still apply.

The JSON result includes target_id, scan_id, status, and the dashboard URL. Agent scans also return agent_session when supplied by the backend. Use its connection details to connect the agent before polling get_scan_status; an unconnected agent cannot answer scan requests. Model/provider credentials are not included in scan requests made by this MCP tool.

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

Start from the sdist on PyPI, which ships the package and its tests:

pip download shieldpi-mcp --no-deps --no-binary :all:
tar xzf shieldpi_mcp-*.tar.gz
cd shieldpi_mcp-*/
pip install -e ".[dev]"
pytest

The test suite runs offline with httpx.MockTransport; it does not contact a live API, create a real target, or start a real scan. Ambient API credentials are removed in fixtures. It covers client authentication and errors, MCP tool registration, existing model targets with BYOK, local model-creation refusal, API format fields, and agent-session propagation. Live service behavior requires a separate authorized integration check.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│            Claude Desktop / Claude Code / Cursor                 │
│                  (MCP Client over stdio)                         │
└──────────────────────────────┬──────────────────────────────────┘
                               │ MCP (JSON-RPC over stdio)
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    shieldpi-mcp (Python)                         │
│  ┌──────────────┐  ┌─────────────────┐                          │
│  │  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 leaderboard
• Methodology: shieldpi.io/methodology
• Research: shieldpi.io/research
• Support: support@shieldpi.io