mcp-security-scan

MCP Security Scanning

When the user asks to scan MCP servers or check for security issues in MCP configurations, use the uv run mcp-scanner CLI tool. This tool detects prompt injection, tool poisoning, command injection, data exfiltration, and other MCP-specific threats.

Important: Always run mcp-scanner using uv run mcp-scanner to ensure proper dependency management.

Threat Types Detected

• Prompt Injection: Malicious instructions embedded in tool descriptions or prompts
• Tool Poisoning: Tools that claim to do one thing but actually perform malicious actions
• Command Injection: Tools that execute arbitrary system commands
• Data Exfiltration: Tools that leak sensitive data to external endpoints
• Privilege Escalation: Tools that request excessive permissions
• Cross-Origin Attacks: Tools that access unauthorized resources
• Behavioral Mismatches: Discrepancies between documented and actual tool behavior

Analyzers

Analyzer	Description	Requirements	Best For
yara	Fast pattern-based detection using YARA rules	None	Quick scans, CI/CD pipelines
llm	LLM-powered semantic analysis	MCP_SCANNER_LLM_API_KEY	Deep analysis, prompt injection detection
api	Cisco AI Defense API	MCP_SCANNER_API_KEY	Enterprise-grade threat detection

Combine analyzers: --analyzers yara,llm,api for comprehensive scanning.

Scanning Modes

1. Remote MCP Server

Scan tools on a remote SSE or streamable HTTP MCP server:

# Basic scan
uv run mcp-scanner --analyzers yara remote --server-url https://mcp.example.com/mcp

# With authentication
uv run mcp-scanner --analyzers yara remote --server-url https://mcp.example.com/mcp --bearer-token "$TOKEN"

# With custom headers (e.g., MCP Gateway dual-token auth)
uv run mcp-scanner --analyzers yara remote --server-url https://gateway.example.com/mcp \
  --header "Authorization: Bearer ingress-token" \
  --header "X-Egress-Auth: Bearer egress-token"

2. Known Config Locations

Scan well-known MCP config paths (Windsurf, Cursor, Claude Desktop, VS Code):

# Quick summary scan
uv run mcp-scanner --scan-known-configs --analyzers yara --format summary

# Detailed scan
uv run mcp-scanner --scan-known-configs --analyzers yara --format detailed

# With authentication for remote servers in configs
uv run mcp-scanner known-configs --bearer-token "$TOKEN" --analyzers yara

Config locations scanned:

• ~/.codeium/windsurf/mcp_config.json (Windsurf)
• ~/.cursor/mcp.json (Cursor)
• ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop on macOS)
• VS Code MCP settings

3. Specific Config File

Scan a specific MCP configuration file:

uv run mcp-scanner config --config-path /path/to/mcp_config.json --analyzers yara --format detailed

4. Stdio MCP Server

Launch and scan a stdio-based MCP server:

# Using uvx
uv run mcp-scanner stdio --stdio-command uvx \
  --stdio-arg=--from --stdio-arg=mcp-server-fetch --stdio-arg=mcp-server-fetch \
  --analyzers yara --format summary

# Scan specific tool only
uv run mcp-scanner stdio --stdio-command uvx \
  --stdio-arg=--from --stdio-arg=mcp-server-fetch --stdio-arg=mcp-server-fetch \
  --stdio-tool fetch --analyzers yara

# With environment variables
uv run mcp-scanner stdio --stdio-command python --stdio-arg=server.py \
  --stdio-env API_KEY=secret --analyzers yara

5. Prompts

Scan MCP server prompts for prompt injection and manipulation:

# Scan all prompts
uv run mcp-scanner --analyzers llm prompts --server-url http://127.0.0.1:8000/mcp

# Scan specific prompt
uv run mcp-scanner --analyzers llm prompts --server-url http://127.0.0.1:8000/mcp --prompt-name "greet_user"

# Table format output
uv run mcp-scanner --analyzers llm --format table prompts --server-url http://127.0.0.1:8000/mcp

6. Resources

Scan MCP server resources for malicious content:

# Scan all resources
uv run mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp

# Scan specific resource
uv run mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp \
  --resource-uri "file://test/document.txt"

# Filter by MIME types
uv run mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp \
  --mime-types "text/plain,text/html,application/json"

7. Server Instructions

Scan server instructions from InitializeResult for prompt injection and misleading guidance:

uv run mcp-scanner instructions --server-url http://127.0.0.1:8000/mcp

# With LLM for semantic analysis
uv run mcp-scanner --analyzers llm instructions --server-url http://127.0.0.1:8000/mcp

8. Behavioral Code Analysis

Analyze MCP server source code to detect mismatches between documentation and implementation:

# Scan a single file
uv run mcp-scanner behavioral /path/to/mcp_server.py

# Scan a directory
uv run mcp-scanner behavioral /path/to/mcp_servers/

# With specific output format
uv run mcp-scanner behavioral /path/to/mcp_server.py --format by_severity

# Save results to file
uv run mcp-scanner behavioral /path/to/mcp_server.py --output results.json --format raw

Detects:

• Functions that claim to read but actually write
• Hidden network calls not mentioned in documentation
• Credential harvesting disguised as helper functions
• Data exfiltration in seemingly benign operations

9. Static/Offline Scanning (CI/CD Mode)

Scan pre-generated JSON files without connecting to a live server:

# Scan tools JSON (YARA-only, no API keys needed)
uv run mcp-scanner --analyzers yara --format summary static --tools /path/to/tools.json

# Scan prompts JSON
uv run mcp-scanner --analyzers llm static --prompts /path/to/prompts.json

# Scan resources JSON
uv run mcp-scanner --analyzers llm static --resources /path/to/resources.json

# Scan all types at once
uv run mcp-scanner --analyzers yara,llm,api --format detailed static \
  --tools /path/to/tools.json \
  --prompts /path/to/prompts.json \
  --resources /path/to/resources.json

Expected JSON format:

{
  "tools": [
    {
      "name": "tool_name",
      "description": "Tool description",
      "inputSchema": { "type": "object", "properties": {} }
    }
  ]
}

Output Formats

Format	Description	Use Case
summary	Concise overview with key findings	Quick checks
detailed	Comprehensive analysis with full breakdown	Investigation
table	Clean tabular format	Reports
by_severity	Results grouped by severity level	Prioritization
raw	Raw JSON output	Automation/CI

Environment Variables

Core Configuration

# Cisco AI Defense API (for api analyzer)
export MCP_SCANNER_API_KEY="your_cisco_api_key"
export MCP_SCANNER_ENDPOINT="https://us.api.inspect.aidefense.security.cisco.com/api/v1"

LLM Configuration

# OpenAI
export MCP_SCANNER_LLM_API_KEY="your_openai_api_key"
export MCP_SCANNER_LLM_MODEL="gpt-4o"

# Azure OpenAI
export MCP_SCANNER_LLM_BASE_URL="https://your-resource.openai.azure.com/"
export MCP_SCANNER_LLM_API_VERSION="2024-02-01"
export MCP_SCANNER_LLM_MODEL="azure/gpt-4"

# AWS Bedrock Claude
export AWS_PROFILE="your-profile"
export AWS_REGION="us-east-1"
export MCP_SCANNER_LLM_MODEL="bedrock/anthropic.claude-sonnet-4-5-20250929-v2:0"

# Local LLM (Ollama, vLLM, LocalAI)
export MCP_SCANNER_LLM_API_KEY="test"  # Required but can be any value
export MCP_SCANNER_LLM_ENDPOINT="http://localhost:11434"

# Extended thinking models (longer timeout)
export MCP_SCANNER_LLM_TIMEOUT=300

Severity Levels

• HIGH: Critical security issues requiring immediate attention
• MEDIUM: Potential security concerns that should be reviewed
• LOW: Minor issues or informational findings
• SAFE: No security issues detected

Best Practices

1. Start with YARA: Use --analyzers yara for quick initial scans (no API keys needed)
2. Add LLM for depth: Include llm analyzer for semantic analysis of suspicious tools
3. Use detailed format: Use --format detailed when investigating findings
4. CI/CD integration: Use static scanning with --format raw for pipeline integration
5. Scan before install: Always scan new MCP servers before adding to your configuration
6. Regular rescans: Periodically rescan existing configurations for new threats

Example Workflow

# 1. Quick scan of all local configs
uv run mcp-scanner --scan-known-configs --analyzers yara --format summary

# 2. If issues found, run detailed scan
uv run mcp-scanner --scan-known-configs --analyzers yara,llm --format detailed

# 3. For new server, scan before installing
uv run mcp-scanner --analyzers yara,llm remote --server-url https://new-mcp-server.com/mcp

# 4. For MCP server code you're reviewing
uv run mcp-scanner behavioral ./mcp-server-source/ --format by_severity