Configuration¶

MCP-Scan can be configured via a YAML file (.mcp-scan.yaml) in your project root.

Initialize Configuration¶

mcp-scan init

This creates a .mcp-scan.yaml with documented defaults.

Configuration File Structure¶

# Configuration version
version: "1"

# File discovery patterns
include:
  - "**/*.py"
  - "**/*.ts"
  - "**/*.js"
  - "**/*.go"

exclude:
  - "node_modules/**"
  - "venv/**"
  - ".venv/**"
  - "dist/**"
  - "build/**"
  - "**/*.min.js"
  - "**/*.test.ts"
  - "**/*_test.py"
  - "**/*_test.go"
  - "vendor/**"

# Rules configuration
rules:
  # Disable specific rules
  disabled:
    - "MCP-N001"  # Don't report missing lockfile

  # Override severity levels
  severity_overrides:
    "MCP-E001": "critical"  # Escalate hardcoded secrets
    "MCP-E002": "high"

  # Custom rules (advanced)
  custom:
    - id: "CUSTOM-001"
      pattern: "dangerous_pattern\\s*\\("
      severity: "high"
      confidence: "medium"
      description: "Custom vulnerability detected"
      remediation: "Remove dangerous_pattern usage"
      languages: ["python"]
      class: "A"

# Allowlists (reduce false positives)
allowlists:
  # Allowed hostnames for network requests
  hosts:
    - "api.example.com"
    - "*.trusted-domain.com"
    - "localhost"

  # Allowed URL schemes
  url_schemes:
    - "https"

  # Allowed paths (won't flag path traversal)
  paths:
    - "/var/log/**"
    - "/tmp/**"

# Custom secret patterns
secrets_patterns:
  # Additional patterns to detect
  additional:
    - "MY_SECRET_[A-Z0-9]{32}"
    - "INTERNAL_KEY_[a-f0-9]{64}"

  # Patterns to ignore (false positives)
  ignore:
    - "example_api_key"
    - "test_token_.*"

# Scan settings
mode: fast              # fast or deep
timeout: 5m             # Duration (e.g., 30s, 1h, 5m)
fail_on: ""             # Severity threshold (info, low, medium, high, critical)
workers: 0              # 0 = auto-detect CPU count

# Output settings
output:
  format: json          # json, sarif, evidence
  redact_snippets: false  # Hide code in output
  include_trace: true   # Include taint traces

# Baseline settings
baseline:
  path: ""              # Path to baseline file
  auto_accept: false    # Auto-accept low severity findings

Configuration Options Detail¶

include / exclude¶

Glob patterns for file discovery:

include:
  - "src/**/*.py"
  - "lib/**/*.ts"

exclude:
  - "**/__pycache__/**"
  - "**/node_modules/**"
  - "**/*.generated.*"

rules.disabled¶

Disable specific rules by ID:

rules:
  disabled:
    - "MCP-N001"  # Don't check for lockfiles
    - "MCP-E002"  # Allow secret variable names

rules.severity_overrides¶

Change severity for specific rules:

rules:
  severity_overrides:
    # Escalate
    "MCP-E001": "critical"

    # Downgrade
    "MCP-F001": "low"

Valid severities: info, low, medium, high, critical

rules.custom¶

Define custom pattern-based rules:

rules:
  custom:
    - id: "CUSTOM-LOGGING"
      pattern: "console\\.log\\s*\\(.*password"
      severity: "high"
      confidence: "high"
      description: "Password logged to console"
      remediation: "Remove password from log statement"
      languages: ["javascript", "typescript"]
      class: "E"

allowlists.hosts¶

Trusted hosts that won't trigger SSRF warnings:

allowlists:
  hosts:
    - "api.mycompany.com"
    - "*.amazonaws.com"
    - "127.0.0.1"
    - "localhost"

secrets_patterns¶

Customize secret detection:

secrets_patterns:
  # Additional patterns to detect as secrets
  additional:
    - "CORP_API_[A-Z0-9]{24}"
    - "internal_token_[a-f0-9]{32}"

  # Patterns to ignore (test data, examples)
  ignore:
    - "example_.*"
    - "test_api_key"
    - "AKIA[A-Z0-9]{16}EXAMPLE"

Scan Mode¶

# Fast mode: intra-procedural analysis
mode: fast

# Deep mode: inter-procedural with additional rules
mode: deep

Timeout¶

Duration format accepts: 30s, 5m, 1h

timeout: 10m  # 10 minutes max

Workers¶

Parallel workers for scanning:

workers: 0   # Auto-detect (recommended)
workers: 4   # Fixed 4 workers
workers: 1   # Single-threaded

Output Settings¶

output:
  format: sarif         # Default output format
  redact_snippets: true # Don't include code in output
  include_trace: false  # Skip taint traces

Environment Variable Overrides¶

Configuration can be overridden via environment:

Variable	Config Key
`MCP_SCAN_MODE`	`mode`
`MCP_SCAN_TIMEOUT`	`timeout`
`MCP_SCAN_FAIL_ON`	`fail_on`
`MCP_SCAN_WORKERS`	`workers`

MCP_SCAN_MODE=deep MCP_SCAN_FAIL_ON=high mcp-scan scan .

Configuration Precedence¶

CLI flags (highest)
Environment variables
Configuration file
Defaults (lowest)

Example Configurations¶

CI/CD Pipeline¶

version: "1"
mode: fast
timeout: 2m
fail_on: high
output:
  format: sarif
rules:
  disabled:
    - "MCP-N001"  # Lockfile checked elsewhere

Security Audit¶

version: "1"
mode: deep
timeout: 30m
output:
  format: evidence
  include_trace: true
rules:
  severity_overrides:
    "MCP-E001": "critical"
    "MCP-A003": "critical"

Development¶

version: "1"
mode: fast
timeout: 1m
output:
  format: json
  redact_snippets: false
exclude:
  - "**/*_test.py"
  - "**/*.test.ts"
  - "tests/**"

Validating Configuration¶

The scanner validates configuration on startup. Invalid configs will show errors:

mcp-scan scan . --config my-config.yaml
# Error: invalid severity 'super-critical' for rule MCP-E001