MCP SCANNER

SUPPLY CHAIN SECURITY FOR MODEL CONTEXT PROTOCOL

The MCP Scanner analyzes every server and tool in your MCP configuration for supply chain attacks. It runs locally in seconds and requires no account.

// 001

ANALYZERS

The scanner runs four independent analyzers against your MCP configuration. Each analyzer targets a distinct class of attack.

TOOL POISONING

HIGH RISK

Scans tool names and descriptions for language designed to redirect agent behavior. Attackers embed hidden instructions in tool descriptions that override the user's intended prompts. This analyzer flags tools whose descriptions contain unusual imperative language, cross-tool references, or patterns that attempt to hijack the agent's decision-making.

PROMPT INJECTION

HIGH RISK

Checks tool arguments and descriptions for prompt injection patterns. Malicious MCP servers may embed payloads in tool output or schema descriptions that, when processed by an LLM, cause the agent to take unintended actions. This analyzer identifies known injection signatures and suspicious instruction-like content.

SHADOWING

MEDIUM RISK

Detects tools that shadow legitimate system tools. When two MCP servers expose a tool with the same name, or when a tool name closely matches a well-known system function, an attacker can intercept calls meant for the real tool. This analyzer checks for name collisions across all configured servers and against a known-safe tool list.

SUSPICIOUS ENVIRONMENT

MEDIUM RISK

Checks for runtime hijacking via environment variable manipulation. Some MCP servers set or override environment variables that affect how other tools or processes behave at runtime. This analyzer flags server configurations that write to sensitive environment variable namespaces or override variables that could redirect network traffic, change binary paths, or escalate privileges.

// 002

GRADE SCALE

The scanner assigns a single letter grade based on the highest severity finding across all four analyzers. A clean configuration gets an A. Any critical finding results in an F.

Grade	Condition
A	0 findings
B	Low findings only
C	Medium findings
D	High findings
F	Critical findings

// 003

CLI FLAGS

$ npx @agentdefenders/mcp-scan [flags]

Flag	Description
--config <path>	Path to a custom MCP configuration file. Defaults to the standard locations for Claude Desktop, VS Code, and Cursor.
--format <console\|json\|sarif>	Output format. Use console (default) for human-readable terminal output, json for machine-readable results, or sarif for SARIF 2.1.0 output compatible with GitHub Code Scanning.
--fail-on <severity>	Exit with a non-zero status code if any finding meets or exceeds the given severity level. Useful in CI pipelines. Valid values: low, medium, high, critical.
--api-key <key>	Shield API key. When provided, scan results are uploaded to your Shield dashboard and tracked over time.
--watch	Run the scanner continuously, re-scanning whenever the MCP configuration file changes.
--interval <seconds>	When used with --watch, sets the polling interval in seconds. Defaults to 60.
--quiet	Suppress all output except findings and the final grade. Useful when scripting.

// 004

CI/CD INTEGRATION

Add the MCP Scanner to your GitHub Actions workflow to catch supply chain issues on every push and pull request. Results are uploaded to GitHub Code Scanning as SARIF, making findings visible directly in pull request reviews.

Add your Shield API key as a repository secret named AGENTDEFENDERS_API_KEY to persist results to your Shield dashboard.

.github/workflows/mcp-scan.yml

name: MCP Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  mcp-scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run MCP Scanner
        run: |
          npx @agentdefenders/mcp-scan \
            --format sarif \
            --fail-on high \
            > mcp-scan-results.sarif
        env:
          AGENTDEFENDERS_API_KEY: ${{ secrets.AGENTDEFENDERS_API_KEY }}

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: mcp-scan-results.sarif
          category: mcp-scanner

← Quickstart Shield Alarms →

Grade

Condition

0 findings

Low findings only

Medium findings

High findings

Critical findings

Flag

Description

--config <path>

Path to a custom MCP configuration file. Defaults to the standard locations for Claude Desktop, VS Code, and Cursor.

--format <console|json|sarif>

Output format. Use console (default) for human-readable terminal output, json for machine-readable results, or sarif for SARIF 2.1.0 output compatible with GitHub Code Scanning.

--fail-on <severity>

Exit with a non-zero status code if any finding meets or exceeds the given severity level. Useful in CI pipelines. Valid values: low, medium, high, critical.

--api-key <key>

Shield API key. When provided, scan results are uploaded to your Shield dashboard and tracked over time.

--watch

Run the scanner continuously, re-scanning whenever the MCP configuration file changes.

--interval <seconds>

When used with --watch, sets the polling interval in seconds. Defaults to 60.

--quiet

Suppress all output except findings and the final grade. Useful when scripting.

name: MCP Scan on: push: branches: [main] pull_request: branches: [main] jobs: mcp-scan: runs-on: ubuntu-latest permissions: security-events: write contents: read steps: - name: Checkout uses: actions/checkout@v4 - name: Run MCP Scanner run: | npx @agentdefenders/mcp-scan \ --format sarif \ --fail-on high \ > mcp-scan-results.sarif env: AGENTDEFENDERS_API_KEY: ${{ secrets.AGENTDEFENDERS_API_KEY }} - name: Upload SARIF to GitHub Code Scanning uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: mcp-scan-results.sarif category: mcp-scanner