Quick Start

Install mcp-scan, run your first security scan, and understand the results in under five minutes.

  4 min read  

MCP Scanner (mcp-scan) is a static security analyzer built specifically for MCP server implementations. This guide walks you through installation, running your first scan, and understanding what the output means.

Prerequisites

  • Go 1.24+ (for building from source) or download a pre-built binary
  • CGO_ENABLED=1 (required for tree-sitter parsing bindings)
  • Linux, macOS, or Windows

Installation

Using Go Install

The fastest way to get started:

go install github.com/mcphub/mcp-scan/cmd/mcp-scan@latest

Make sure $GOPATH/bin is in your PATH:

export PATH=$PATH:$(go env GOPATH)/bin

Building from Source

git clone https://github.com/mcphub/mcp-scan
cd mcp-scan
make build

The binary is produced at ./bin/mcp-scan.

Pre-built Binaries

Download from the Releases page.

Linux (amd64):

curl -LO https://github.com/mcphub/mcp-scan/releases/latest/download/mcp-scan-linux-amd64.tar.gz
tar xzf mcp-scan-linux-amd64.tar.gz
sudo mv mcp-scan /usr/local/bin/

macOS (arm64):

curl -LO https://github.com/mcphub/mcp-scan/releases/latest/download/mcp-scan-darwin-arm64.tar.gz
tar xzf mcp-scan-darwin-arm64.tar.gz
sudo mv mcp-scan /usr/local/bin/

Docker

docker run --rm -v $(pwd):/scan mcphub/mcp-scan scan /scan

Verify Installation

mcp-scan version

Expected output:

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

Your First Scan

1. Run a Basic Scan

Point mcp-scan at your MCP server project directory:

mcp-scan scan ./my-mcp-server

By default, this runs in fast mode and outputs JSON to stdout.

2. Understanding the Output

A typical scan result looks like this:

{
  "findings": [
    {
      "rule_id": "MCP-A003",
      "severity": "critical",
      "confidence": "high",
      "location": {
        "file": "src/tools/execute.py",
        "start_line": 42
      },
      "description": "Direct shell command execution detected",
      "remediation": "Use subprocess with shell=False"
    }
  ],
  "summary": {
    "total": 3,
    "by_severity": {
      "critical": 1,
      "high": 2
    }
  },
  "msss_score": {
    "total": 65.5,
    "level": 1,
    "compliant": true
  }
}

Key fields to look at:

FieldWhat It Tells You
findingsArray of all detected vulnerabilities, each with location, severity, and remediation guidance
summaryAggregate counts grouped by severity, class, and language
msss_score.totalYour security score from 0 to 100 (higher is better)
msss_score.levelCertification compliance level from 0 (not compliant) to 3 (certified)

3. Explore the MCP Surface

Before running a full scan, you can preview what tools and resources the scanner detects in your code:

mcp-scan surface ./my-mcp-server

This extracts the MCP surface (tools, resources, prompts, transport, auth signals) without performing vulnerability analysis.

Fast Mode vs Deep Mode

MCP Scanner offers two analysis depths:

AspectFast ModeDeep Mode
Commandmcp-scan scan . --mode fastmcp-scan scan . --mode deep
AnalysisIntra-procedural (within functions)Inter-procedural (across functions and files)
SpeedSecondsMinutes
Vulnerability ClassesA-G, L-N (10 classes)A-N (all 14 classes)
Best ForCI/CD, pull requests, quick checksSecurity audits, certification, release gates

Deep mode adds detection for four additional vulnerability classes that require call graph analysis:

  • H: Prompt Injection Flow – user input flowing into LLM prompts
  • I: Privilege Escalation – tools modifying their own permissions
  • J: Cross-Tool Data Leakage – sensitive data shared between tools
  • K: Authentication Bypass – tools circumventing auth checks

Run a Deep Scan

mcp-scan scan ./my-mcp-server --mode deep

Common Scan Commands

Fail on Severity (CI/CD Gates)

Make the scan exit with code 1 if any findings meet or exceed a severity threshold:

# Fail on high or critical findings
mcp-scan scan . --fail-on high

# Fail on any critical findings only
mcp-scan scan . --fail-on critical

Generate SARIF for GitHub Code Scanning

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

Generate Evidence Bundle for Audits

mcp-scan scan . --mode deep --output evidence

Scan Specific Rules or Classes

# Only check for RCE (A), Secrets (E), and Tool Poisoning (G)
mcp-scan scan . --rules A,E,G

# Check specific rule IDs
mcp-scan scan . --rules MCP-A003,MCP-E001

Use a Baseline to Ignore Accepted Findings

# Generate a baseline from current findings
mcp-scan baseline generate ./my-mcp-server \
  --reason "Initial review" \
  --accepted-by "[email protected]"

# Scan with the baseline applied
mcp-scan scan . --baseline .mcp-scan-baseline.json --fail-on high

Initialize a Configuration File

mcp-scan init

This creates a .mcp-scan.yaml with documented defaults that you can customize for your project.

Common Workflows

Development – Quick Feedback

# Fast check during development
mcp-scan scan . --mode fast

# Initialize and customize config
mcp-scan init
# Edit .mcp-scan.yaml to tune rules, exclusions, and allowlists

CI/CD – Automated Gate

# Run scan with baseline, fail on new high/critical findings
mcp-scan scan . --baseline .mcp-scan-baseline.json --fail-on high

Security Audit – Full Evidence

# Deep analysis with full evidence bundle
mcp-scan scan . --mode deep --output evidence

# Review the MCP surface separately
mcp-scan surface .

Exit Codes

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

Next Steps