MCP Server Scanner

Scan any MCP server for security vulnerabilities before connecting agents to it — tool injection patterns, command execution risks, known CVEs, and supply-chain issues.

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.

Check category	What is inspected
Tool analysis	Prompt injection language, command injection patterns, overly broad permissions in tool definitions and parameter schemas
Dependency CVEs	Known vulnerabilities in packages listed in the server's manifest or inferred from the server info response
OAuth flows	Insecure authorization code flows, missing PKCE, implicit grant usage, and misconfigured redirect URIs
Supply-chain manifest	Unsigned manifests, missing integrity hashes, and suspicious tool metadata in the server's tool list

Running a Scan

CLI

Install the scanner package and point it at any HTTP or local MCP server:

Not yet on npm

The @shieldagent/scanner package has not been published to npm yet. Install from the source repository:

bash

# Install from source
git clone https://github.com/shieldagent-io/shieldagent.git
cd shieldagent && pnpm install
npm install -g ./backend/apps/scanner

# 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 Fastify REST server for programmatic access. Start it with --serve and call the scan endpoint:

bash

# Start the REST server on port 4500
shieldagent-scan --serve --port 4500

bash

# Trigger a scan via the API
curl -s -X POST http://localhost:4500/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.

Severity	Meaning	CI exit code
Critical	Active attack vector — prompt injection, supply-chain poisoning. Block the server immediately.	1 (fail)
High	Command injection patterns, dangerous parameter schemas, connection failures. Remediate before connecting agents.	1 (fail)
Medium	High-privilege tools with constraints, OAuth misconfiguration. Review and mitigate.	0 (warn)
Low	Minor best-practice deviations. Low immediate risk.	0 (warn)
Info	Informational findings — no action required.	0

Tool Definition Analysis

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

Prompt injection

Tool names and descriptions are scanned for language designed to manipulate AI agent behaviour: phrases like "ignore previous instructions", "override safety", embedded [[SYSTEM]] blocks, jailbreak keywords (DAN), and role reassignment patterns. Any match is reported as Critical.

Command injection

Shell metacharacter patterns are matched against tool names, descriptions, and parameter schema descriptions: $() command substitution, backtick execution, shell operator chains (&&, ||), and direct calls to exec/eval/system. Matches are reported as High.

Overly broad permissions

Tools whose names or descriptions indicate shell or system-level access (execute_*, run_shell, keywords like "arbitrary command", "run as root", "sudo") are flagged. Tools with no input schema constraints at all are elevated to High; constrained high-privilege tools are flagged as Medium.

Output Formats

Format	Flag	Use case
JSON	--format json	Default. Full ScanReport with all findings, tool list, SBOM, and metadata. Ideal for programmatic processing.
Markdown	--format markdown	Human-readable report with findings grouped by severity. Share in PRs or issue trackers.
SARIF 2.1.0	--format sarif	GitHub Security tab and CI/CD integration. Upload to the GitHub code scanning API to surface findings in pull requests.

CI/CD Integration

Add the scanner to your GitHub Actions workflow to block deployments when high-severity findings are detected. The SARIF output integrates with the GitHub Security tab for in-PR annotations:

yaml

# .github/workflows/mcp-scan.yml
name: MCP Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install ShieldAgent Scanner from source
        # @shieldagent/scanner not yet on npm — build from source
        run: |
          git clone https://github.com/shieldagent-io/shieldagent.git
          cd shieldagent && npm install -g pnpm
          pnpm install --frozen-lockfile
          npm install -g ./backend/apps/scanner

      - name: Scan MCP server
        run: |
          shieldagent-scan --format sarif -o results.sarif \
            ${{ secrets.MCP_SERVER_URL }}

      - name: Upload SARIF to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Exit code 1 from the scanner will fail the CI step automatically when Critical or High findings exist — no additional configuration needed.

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

POST/api/v1/scan—Run a scan against an HTTP MCP server. Returns a full ScanReport.

GET/health—Liveness probe. Returns { status: "ok" }.

GET/metrics—Prometheus metrics endpoint (scan counts, error rates, latency).

Request body — POST /api/v1/scan

json

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

json

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

Category	Description
tool_analysis	Findings from inspecting tool definitions — injection patterns, broad permissions
dependency_cve	Known CVEs in packages discovered in the server manifest or SBOM
oauth_flow	OAuth 2.0 / PKCE misconfiguration in the server's authorization endpoints
connection	Scan-time connectivity or protocol errors
supply_chain	Unsigned manifests, missing integrity hashes, suspicious tool metadata