MCP Server Scanner

What the Scanner Does

The ShieldAgent MCP Scanner connects to any MCP server (HTTP or local stdio process), enumerates its tool definitions, and runs a suite of security checks across four categories: tool definition analysis, dependency CVE scanning, OAuth flow inspection, and supply-chain manifest review.

Results are returned as a structured ScanReport with findings grouped by severity, a finding summary, the enumerated tool list, and an optional CycloneDX 1.5 SBOM when package metadata is available.

Running a Scan

CLI

Point the scanner at any HTTP or local MCP server:

# Scan an HTTP MCP server
shieldagent-scan https://my-mcp-server.example.com

# Scan a local stdio server
shieldagent-scan stdio -- node ./dist/server.js

# Output as Markdown report to a file
shieldagent-scan --format markdown --output report.md https://my-mcp-server.example.com

# Output as SARIF (for GitHub Security tab / CI)
shieldagent-scan --format sarif -o results.sarif https://my-mcp-server.example.com

REST API

The scanner ships a built-in REST server for programmatic access. Start it with --serve and call the scan endpoint:

# Start the REST server
shieldagent-scan --serve

# Trigger a scan via the API
curl -s -X POST http://localhost:<scanner-port>/api/v1/scan \
  -H 'Content-Type: application/json' \
  -d '{
    "target": {
      "type": "http",
      "url": "https://my-mcp-server.example.com"
    }
  }' | jq .

Dashboard

Navigate to Scanner in the ShieldAgent dashboard sidebar. Enter the server URL and click Run Scan. The dashboard stores scan history and lets you compare results across runs. Findings link directly to the relevant policy management screen to accelerate remediation.

Severity Levels

Every finding has one of five severity levels. The CLI exits with code 1 when any Critical or High findings are present, and code 0 otherwise.

Tool Definition Analysis

The scanner inspects every tool definition returned by tools/list for three classes of risk:

Output Formats

CI/CD Integration

Dashboard Integration

The ShieldAgent dashboard surfaces scanner results alongside runtime monitoring data:

• Scan history— every scan run is stored with a timestamp, target, finding summary, and full report. Compare results before and after a server update.
• Remediation tracking— findings can be acknowledged, assigned, or linked to policy rules. Acknowledged findings are excluded from the active count but remain auditable.
• Policy shortcuts— High and Critical findings on a specific tool link directly to the Policy Management screen, pre-filled with a deny rule for that tool.
• SBOM viewer— when a CycloneDX SBOM is generated, it appears in the scan detail view with a searchable component list and vulnerability cross-references.

Scanner API Reference

Endpoints

Request body — POST /api/v1/scan

{
  "target": {
    "type": "http",
    "url": "https://my-mcp-server.example.com"
  }
}

Note: stdio targets are rejected by the REST API for security reasons. Use the CLI for local process scanning.

Response — ScanReport

{
  "id": "3f2a1c4d-...",
  "target": { "type": "http", "url": "https://..." },
  "scannedAt": "2026-04-24T12:00:00.000Z",
  "durationMs": 843,
  "serverInfo": {
    "name": "my-mcp-server",
    "version": "1.2.0",
    "protocolVersion": "2024-11-05"
  },
  "tools": [...],
  "findings": [
    {
      "id": "a1b2c3d4-...",
      "category": "tool_analysis",
      "severity": "high",
      "title": "High-privilege tool \"execute_shell\" lacks input constraints",
      "description": "Tool execute_shell appears to execute shell commands but defines no input schema constraints.",
      "remediation": "Add a strict JSON Schema with an allowlist of permitted values.",
      "metadata": { "toolName": "execute_shell" }
    }
  ],
  "summary": { "critical": 0, "high": 1, "medium": 0, "low": 0, "info": 0, "total": 1 }
}

Finding categories