Scan an MCP server

​

What this example tests

• The 10 ASI categories against the MCP server itself — tool poisoning, schema confusion, destructive-tool gating, session bleed — rather than a specific LLM client that happens to use the server.
• Supply-chain attacks specific to MCP: asi04.mcp-server-poison payloads try to register an untrusted MCP server (https://tools.attacker.test/mcp, etc.) and check whether the target acknowledged or began using it.
• Rules of Engagement enforcement: declare an allowlist/blocklist in YAML and the live RoE chokepoint blocks the call before contacting the server.

​

Prerequisites

• AgentGuardian installed — pip install agent-guardian.
• An MCP server reachable over Streamable HTTP (default) or legacy SSE.
• For OAuth-protected servers: client credentials available via env vars (the contract dereferences ${env:NAME} references).
• A model spec — --model stub for an offline dry-run, or a real model spec for a graded assessment.

​

Run target

version: 1
target:
  name: mcp-search
  environment: staging
  transport:
    kind: mcp
    url: https://mcp.example.com/rpc
    transport_type: streamable_http
    entry_tool: search
    prompt_argument: input
    init_timeout_ms: 30000
  response:
    output_path: $.output.text
  session:
    mode: stateless
roe:
  data_egress:
    allow_external: true
  tools:
    allowlist: [search]
    blocklist: [delete_everything]

target:
  # ... transport block as above ...
  auth:
    kind: mcp_oauth
    client_id: ${env:MCP_CLIENT_ID}
    client_secret: ${env:MCP_CLIENT_SECRET}   # omit for public clients
    scopes: [tools.read, tools.call]

​

Run AgentGuardian

agent-guardian scan \
  --contract ./agentguardian.yaml \
  --model stub \
  --mode fast \
  --output sarif \
  --output-path mcp-scan.sarif

• --contract PATH — drive the scan from a target contract (agentguardian.yaml).
• --model stub — offline default. Swap for a real model spec for a graded run.
• --mode fast — fast / smart / full (default).
• --output sarif --output-path mcp-scan.sarif — SARIF report, ready to upload to GitHub Code Scanning. Other formats: json, md, junit, pdf.

​

Expected output

{
  "scan_id": "scan_2026...",
  "target": {
    "mode": "contract",
    "name": "mcp-search",
    "environment": "staging",
    "transport": {
      "kind": "mcp",
      "endpoint": "https://mcp.example.com/rpc",
      "supports_tools": true,
      "session_modes": ["stateless", "server_session"],
      "discovered_tools": ["search", "delete_everything"]
    }
  },
  "aivss_score": 5.8,
  "findings": [
    { "id": "F-001", "probe": "asi04.mcp-server-poison", "severity": "MEDIUM" }
  ]
}

​

Common errors

• tool 'X' is not advertised by the server. The discovery step (tools/list) did not return a tool named in your entry_tool or RoE allow/blocklist. Run the MCP server’s own tools/list against your endpoint to see what it actually exposes.
• 401 Unauthorized on every call. The server is OAuth-protected and you used auth: kind: none (or omitted the block). Switch to auth: kind: mcp_oauth with the client_id / scopes block above.
• Scan finishes with error.category: PROTOCOL. The server returned a JSON-RPC error member that didn’t match a refusal hint (forbidden, denied, not allowed, blocked, unauthorized). Check the server logs — a malformed inputSchema or a missing required argument is the usual cause.
• EXIT_CONTRACT_INVALID on startup. Your agentguardian.yaml failed Pydantic validation. The error message names the offending field; cross-check it against the schema with agent-guardian contract schema (emits the contract JSON Schema).

​

Next step

• Author your agentguardian.yaml by hand, validating field names against agent-guardian contract schema.
• Compare with a framework-adapter target: Scan a LangGraph agent.
• Add the SARIF report to GitHub Code Scanning: Upload SARIF to GitHub Security.
• Read the MCP-specific probe under Attack library overview (ASI04 supply-chain).