CLI Reference¶

Complete reference for all MCP-Scan commands and options.

Global Structure¶

mcp-scan <command> [options] [arguments]

Commands¶

scan¶

Primary command - Scan a project for security vulnerabilities.

mcp-scan scan <path> [options]

Options¶

Option	Short	Default	Description
`--mode`	`-m`	`fast`	Analysis mode: `fast` or `deep`
`--output`	`-o`	`json`	Output format: `json`, `sarif`, `evidence`
`--fail-on`	`-f`	(none)	Fail on severity: `info`, `low`, `medium`, `high`, `critical`
`--config`	`-c`	`.mcp-scan.yaml`	Path to configuration file
`--rules`		(all)	Comma-separated rule IDs or classes: `A,B,E` or `MCP-A003,MCP-E001`
`--exclude`		(none)	Additional glob patterns to exclude
`--timeout`		`5m`	Maximum scan duration
`--workers`	`-w`	`0` (auto)	Number of parallel workers
`--baseline`	`-b`	(none)	Baseline file for accepted findings

Examples¶

# Basic scan
mcp-scan scan ./my-project

# Deep analysis with SARIF output
mcp-scan scan ./my-project --mode deep --output sarif

# Only run specific rules
mcp-scan scan ./my-project --rules A,E,G

# Fail CI on high severity
mcp-scan scan ./my-project --fail-on high

# Use baseline to ignore accepted findings
mcp-scan scan ./my-project --baseline .mcp-scan-baseline.json

# Custom config and timeout
mcp-scan scan ./my-project --config custom-config.yaml --timeout 10m

version¶

Display version information.

mcp-scan version

Output:

mcp-scan version 1.0.0
commit: abc1234
built: 2024-01-15T10:00:00Z

init¶

Initialize a configuration file in the current directory.

mcp-scan init [options]

Options¶

Option	Default	Description
`--output`	`.mcp-scan.yaml`	Output file path
`--force`	`false`	Overwrite existing file

Creates a .mcp-scan.yaml with default settings that you can customize.

surface¶

Display the detected MCP surface without running a full security scan.

Understanding surface vs scan: The surface command extracts only the MCP metadata (tools, transport, auth signals) from your code. The scan command runs the full pipeline which includes surface extraction PLUS vulnerability analysis. Think of surface as a "preview" of what the scanner sees before analyzing.

scan = [discovery] → [parsing] → [SURFACE] → [analysis] → [findings]
                                    ↑
                            surface command
                         (extracts only this part)

When to use surface: - Debug/understand what tools mcp-scan detects in your code - Quick preview before running a full scan - Generate inventory of your MCP server's exposed surface - Verify that expected tools are being detected correctly

When to use scan: - Find actual security vulnerabilities - CI/CD integration for automated security checks - Security audits and compliance scoring

mcp-scan surface <path> [options]

Options¶

Option	Default	Description
`--config`	`.mcp-scan.yaml`	Configuration file
`--format`	`text`	Output format: `text`, `json`

Example Output¶

MCP Surface Analysis
====================

Transport: stdio

Tools (3 detected):
  - read_file
    Description: Read contents of a file
    Handler: handle_read_file (src/tools.py:45)

  - write_file
    Description: Write contents to a file
    Handler: handle_write_file (src/tools.py:78)

  - execute_command
    Description: Execute a shell command
    Handler: handle_execute (src/tools.py:112)

Auth Signals:
  - JWT verification detected (src/auth.py:23)

baseline¶

Manage baseline files for tracking accepted findings.

baseline generate¶

Generate a baseline from current findings.

mcp-scan baseline generate <path> [options]

Option	Short	Default	Description
`--output`	`-o`	`.mcp-scan-baseline.json`	Baseline file path
`--reason`	`-r`	(none)	Reason for accepting findings
`--accepted-by`	`-a`	(none)	Who accepted the findings
`--config`	`-c`	`.mcp-scan.yaml`	Configuration file
`--mode`	`-m`	`fast`	Scan mode

# Generate baseline with metadata
mcp-scan baseline generate ./my-project \
  --reason "Reviewed and accepted" \
  --accepted-by "security@example.com"

baseline show¶

Display baseline contents.

mcp-scan baseline show <baseline-file> [options]

Option	Short	Description
`--stats`	`-s`	Show only statistics

# Show full baseline
mcp-scan baseline show .mcp-scan-baseline.json

# Show only stats
mcp-scan baseline show .mcp-scan-baseline.json --stats

baseline merge¶

Merge multiple baseline files.

mcp-scan baseline merge <baseline1> <baseline2> [baseline3...] [options]

Option	Short	Default	Description
`--output`	`-o`	(first file)	Output file

mcp-scan baseline merge team1.json team2.json --output combined.json

Exit Codes¶

Code	Meaning
0	Success, no findings above threshold
1	Findings found above `--fail-on` threshold
2	Configuration or usage error
3	Scan error (timeout, parse failure, etc.)

Environment Variables¶

Variable	Description
`MCP_SCAN_CONFIG`	Default config file path
`MCP_SCAN_MODE`	Default scan mode
`NO_COLOR`	Disable colored output

Analysis Modes¶

Fast Mode (Default)¶

Intra-procedural taint analysis
Pattern-based rule detection
Typical runtime: 2-5 seconds
Best for: CI/CD, quick checks

mcp-scan scan . --mode fast

Deep Mode¶

Inter-procedural taint analysis
Cross-function data flow tracking
Additional rules (H, I, J, K)
Typical runtime: 10-60 seconds
Best for: Security audits, thorough analysis

mcp-scan scan . --mode deep

Output Formats¶

JSON (Default)¶

Machine-readable format with full details:

mcp-scan scan . --output json

SARIF¶

GitHub Code Scanning compatible format:

mcp-scan scan . --output sarif > results.sarif

Evidence Bundle¶

Directory with individual evidence files:

mcp-scan scan . --output evidence
# Creates evidence-bundle/ directory

See Output Formats for detailed schema documentation.