Referencia Completa de Comandos CLI¶

Esta guia documenta todos los comandos y opciones disponibles en mcp-scan.

Tabla de Contenidos¶

Estructura General
Comando scan
Comando surface
Comando baseline
Comando init
Comando version
Flags Globales
Codigos de Salida
Variables de Entorno

Estructura General¶

mcp-scan [comando] [argumentos] [opciones]

Ayuda¶

# Ayuda general
mcp-scan --help
mcp-scan -h

# Ayuda de un comando especifico
mcp-scan scan --help
mcp-scan baseline --help

Comandos Disponibles¶

Comando	Descripcion
`scan`	Ejecutar analisis de seguridad
`surface`	Extraer superficie MCP
`baseline`	Gestionar baselines
`init`	Generar archivo de configuracion
`version`	Mostrar version

Comando scan¶

El comando principal para analizar codigo.

Sintaxis¶

mcp-scan scan <ruta> [opciones]

Argumentos¶

Argumento	Descripcion	Requerido
`<ruta>`	Directorio o archivo a escanear	Si

Opciones Completas¶

Configuracion¶

Opcion	Alias	Tipo	Default	Descripcion
`--config`	`-c`	string	`.mcp-scan.yaml`	Ruta al archivo de configuracion

# Usar configuracion especifica
mcp-scan scan . --config /ruta/config.yaml
mcp-scan scan . -c mi-config.yaml

Modo de Analisis¶

Opcion	Alias	Tipo	Default	Descripcion
`--mode`	`-m`	string	`fast`	Modo de analisis: `fast` o `deep`

# Modo rapido (intra-procedural)
mcp-scan scan . --mode fast

# Modo profundo (inter-procedural)
mcp-scan scan . --mode deep
mcp-scan scan . -m deep

Formato de Salida¶

Opcion	Alias	Tipo	Default	Descripcion
`--output`	`-o`	string	`text`	Formato: `text`, `json`, `sarif`, `evidence`

# Salida JSON
mcp-scan scan . --output json > resultados.json
mcp-scan scan . -o json

# Salida SARIF (GitHub Code Scanning)
mcp-scan scan . --output sarif > resultados.sarif

# Evidence Bundle (auditorias)
mcp-scan scan . --output evidence > evidence.json

# Texto plano (por defecto)
mcp-scan scan . --output text

Umbral de Fallo¶

Opcion	Alias	Tipo	Default	Descripcion
`--fail-on`	`-f`	string	-	Severidad minima para codigo de salida no cero

Valores: info, low, medium, high, critical

# Fallar solo en critical
mcp-scan scan . --fail-on critical

# Fallar en high o superior
mcp-scan scan . --fail-on high
mcp-scan scan . -f high

# Fallar en cualquier hallazgo
mcp-scan scan . --fail-on info

Baseline¶

Opcion	Alias	Tipo	Default	Descripcion
`--baseline`	`-b`	string	-	Archivo baseline para filtrar hallazgos

# Usar baseline existente
mcp-scan scan . --baseline baseline.json
mcp-scan scan . -b baseline.json

Timeout¶

Opcion	Alias	Tipo	Default	Descripcion
`--timeout`	-	duration	`5m`	Tiempo maximo de escaneo

# Timeout de 10 minutos
mcp-scan scan . --timeout 10m

# Timeout de 30 segundos (para CI)
mcp-scan scan . --timeout 30s

# Sin timeout (usar con cuidado)
mcp-scan scan . --timeout 0

Filtrado de Reglas¶

Opcion	Alias	Tipo	Default	Descripcion
`--rules`	`-r`	string	`all`	Reglas a ejecutar (separadas por coma)

# Solo reglas especificas
mcp-scan scan . --rules MCP-A003,MCP-A004,MCP-E001

# Solo clase A (RCE)
mcp-scan scan . --rules "MCP-A*"

# Multiples clases
mcp-scan scan . -r "MCP-A*,MCP-B*,MCP-C*"

Exclusion de Rutas¶

Opcion	Alias	Tipo	Default	Descripcion
`--exclude`	`-e`	string	-	Patrones glob a excluir

# Excluir directorios
mcp-scan scan . --exclude "**/tests/**"

# Multiples exclusiones
mcp-scan scan . --exclude "**/tests/**" --exclude "**/vendor/**"
mcp-scan scan . -e "**/tests/**" -e "**/node_modules/**"

Paralelismo¶

Opcion	Alias	Tipo	Default	Descripcion
`--workers`	`-w`	int	`auto`	Numero de workers paralelos

# Usar 4 workers
mcp-scan scan . --workers 4
mcp-scan scan . -w 4

# Un solo worker (debug)
mcp-scan scan . --workers 1

# Auto-detectar (numero de CPUs)
mcp-scan scan . --workers 0

Ejemplos Completos¶

# Escaneo basico
mcp-scan scan ./src

# Escaneo completo para CI
mcp-scan scan ./src \
  --mode fast \
  --output sarif \
  --fail-on high \
  --timeout 5m \
  --exclude "**/tests/**" \
  > results.sarif

# Escaneo profundo para auditoria
mcp-scan scan ./src \
  --mode deep \
  --output evidence \
  --baseline baseline.json \
  --workers 8 \
  > audit-evidence.json

# Escaneo especifico de reglas
mcp-scan scan ./src \
  --rules "MCP-A*,MCP-D*,MCP-E*" \
  --output json \
  --fail-on critical

Comando surface¶

Extrae y muestra la superficie MCP de un proyecto sin ejecutar un analisis completo de seguridad.

Entendiendo surface vs scan: El comando surface extrae solo la metadata MCP (tools, transport, auth signals) de tu codigo. El comando scan ejecuta el pipeline completo que incluye extraccion de superficie MAS analisis de vulnerabilidades. Piensa en surface como una "vista previa" de lo que el scanner ve antes de analizar.

scan = [discovery] → [parsing] → [SURFACE] → [analysis] → [findings]
                                    ↑
                            comando surface
                         (extrae solo esta parte)

Cuando usar surface: - Debug/entender que tools detecta mcp-scan en tu codigo - Vista previa rapida antes de ejecutar un scan completo - Generar inventario de la superficie expuesta de tu servidor MCP - Verificar que los tools esperados se detectan correctamente

Cuando usar scan: - Encontrar vulnerabilidades reales de seguridad - Integracion CI/CD para verificaciones automaticas - Auditorias de seguridad y scoring de compliance

Sintaxis¶

mcp-scan surface <ruta> [opciones]

Argumentos¶

Argumento	Descripcion	Requerido
`<ruta>`	Directorio a analizar	Si

Opciones¶

Opcion	Alias	Tipo	Default	Descripcion
`--config`	`-c`	string	`.mcp-scan.yaml`	Archivo de configuracion
`--output`	`-o`	string	`text`	Formato: `text` o `json`

Ejemplos¶

# Ver superficie en texto
mcp-scan surface ./src

# Salida JSON
mcp-scan surface ./src --output json

# Con configuracion
mcp-scan surface ./src -c config.yaml -o json > surface.json

Salida¶

La salida incluye:

Tools: Herramientas MCP detectadas
Resources: Recursos MCP detectados
Prompts: Prompts MCP detectados
SDK: SDK detectado (mcp, fastmcp, @modelcontextprotocol/sdk)
Transport: Tipo de transporte (stdio, HTTP, WebSocket)
Auth Signals: Senales de autenticacion detectadas

MCP SURFACE ANALYSIS
====================

SDK: Python Official (mcp)
Transport: stdio

TOOLS (4):
  1. execute_command
     Handler: execute_command
     Description: Execute a system command.
     Parameters: command (str)

  2. read_file
     Handler: read_file
     Description: Read contents of a file.
     Parameters: filepath (str)

  ...

RESOURCES (0):
  No resources detected.

PROMPTS (0):
  No prompts detected.

AUTH SIGNALS:
  - Cookies: No
  - Headers: No
  - OAuth State: No

Comando baseline¶

Gestiona baselines de hallazgos aceptados.

Subcomandos¶

Subcomando	Descripcion
`generate`	Crear baseline desde resultados
`show`	Mostrar contenido de baseline
`merge`	Combinar multiples baselines

baseline generate¶

Genera un baseline desde resultados de escaneo.

mcp-scan baseline generate [opciones]

Opcion	Alias	Tipo	Default	Descripcion
`--from`	`-f`	string	-	Archivo JSON de resultados
`--output`	`-o`	string	`baseline.json`	Archivo de salida
`--reason`	`-r`	string	-	Razon para baseline
`--accepted-by`	`-a`	string	-	Quien acepto los hallazgos

# Generar baseline desde escaneo
mcp-scan scan . --output json > scan.json
mcp-scan baseline generate --from scan.json

# Con metadatos
mcp-scan baseline generate \
  --from scan.json \
  --output mi-baseline.json \
  --reason "Falsos positivos revisados" \
  --accepted-by "security-team@example.com"

baseline show¶

Muestra contenido y estadisticas de un baseline.

mcp-scan baseline show <archivo> [opciones]

Opcion	Alias	Tipo	Default	Descripcion
`--output`	`-o`	string	`text`	Formato: `text` o `json`

# Ver baseline en texto
mcp-scan baseline show baseline.json

# Salida JSON
mcp-scan baseline show baseline.json --output json

Salida de ejemplo:

BASELINE: baseline.json
=======================

Total Entries: 15

By Rule ID:
  MCP-E001: 8 entries
  MCP-E002: 4 entries
  MCP-A003: 2 entries
  MCP-B002: 1 entry

By File:
  src/server.py: 10 entries
  src/handlers.py: 5 entries

Recent Entries:
  - MCP-E001 @ src/server.py:47 (2026-01-20)
    Reason: Known API key for development
  ...

baseline merge¶

Combina multiples baselines en uno.

mcp-scan baseline merge <archivo1> <archivo2> [archivos...] [opciones]

Opcion	Alias	Tipo	Default	Descripcion
`--output`	`-o`	string	`merged-baseline.json`	Archivo de salida

# Combinar dos baselines
mcp-scan baseline merge baseline-dev.json baseline-qa.json

# Con nombre de salida
mcp-scan baseline merge \
  baseline-dev.json \
  baseline-qa.json \
  baseline-legacy.json \
  --output baseline-combined.json

Comando init¶

Genera un archivo de configuracion con valores por defecto.

Sintaxis¶

mcp-scan init [opciones]

Opciones¶

Opcion	Alias	Tipo	Default	Descripcion
`--output`	`-o`	string	`.mcp-scan.yaml`	Ruta del archivo
`--force`	`-f`	bool	`false`	Sobrescribir si existe

Ejemplos¶

# Crear configuracion por defecto
mcp-scan init

# Nombre personalizado
mcp-scan init --output config/mcp-scan.yaml

# Sobrescribir existente
mcp-scan init --force

Archivo Generado¶

# MCP-Scan Configuration
# Documentation: https://mcphub.io/docs/mcp-scan

# Files to include (glob patterns)
include:
  - "**/*.py"
  - "**/*.ts"
  - "**/*.tsx"
  - "**/*.mts"
  - "**/*.cts"
  - "**/*.js"
  - "**/*.jsx"
  - "**/*.mjs"
  - "**/*.cjs"

# Files to exclude (glob patterns)
exclude:
  - "**/node_modules/**"
  - "**/venv/**"
  - "**/.venv/**"
  - "**/env/**"
  - "**/.git/**"
  - "**/dist/**"
  - "**/build/**"
  - "**/__pycache__/**"
  - "**/.pytest_cache/**"

# Scan configuration
scan:
  mode: fast          # fast or deep
  timeout: 5m         # scan timeout
  fail_on: ""         # severity threshold (info, low, medium, high, critical)

# Rules configuration
rules:
  disabled: []        # Rule IDs to disable
  severity_overrides: {}  # Override severities
  custom: []          # Custom rules

# Allowlist configuration
allowlist:
  hosts: []           # Allowed hosts for SSRF checks
  url_schemes: []     # Allowed URL schemes

# Output configuration
output:
  redact_snippets: false  # Redact code snippets in reports

# LLM configuration (optional)
llm:
  enabled: false
  base_url: "http://localhost:11434"
  model: "llama3.2:3b"
  threshold: 0.7
  max_length: 5000

# ML configuration (optional)
ml:
  enabled: true
  confidence_threshold: 0.7

# CodeQL configuration (optional)
codeql:
  enabled: false
  cli_path: ""
  queries_path: ""

Comando version¶

Muestra informacion de version.

Sintaxis¶

mcp-scan version

Salida¶

mcp-scan version 2.0.0
Build: 2026-01-23T10:00:00Z
Commit: abc1234
Go: go1.24.0
OS/Arch: darwin/arm64

Opciones¶

Opcion	Alias	Tipo	Default	Descripcion
`--short`	`-s`	bool	`false`	Solo mostrar numero de version

# Version corta
mcp-scan version --short
# Salida: 2.0.0

Flags Globales¶

Estos flags estan disponibles en todos los comandos:

Flag	Alias	Tipo	Default	Descripcion
`--help`	`-h`	bool	`false`	Mostrar ayuda
`--verbose`	`-v`	bool	`false`	Salida detallada
`--quiet`	`-q`	bool	`false`	Suprimir salida no esencial
`--no-color`	-	bool	`false`	Desactivar colores

# Modo verbose
mcp-scan scan . --verbose

# Modo silencioso
mcp-scan scan . --quiet --output json > results.json

# Sin colores (para logs)
mcp-scan scan . --no-color 2>&1 | tee scan.log

Codigos de Salida¶

Codigo	Descripcion
`0`	Exito, sin hallazgos que excedan umbral
`1`	Hallazgos encontrados que exceden umbral
`2`	Error de configuracion
`3`	Error de entrada (archivo no encontrado, etc.)
`4`	Error interno
`5`	Timeout alcanzado

Ejemplos de Uso¶

# Verificar codigo de salida
mcp-scan scan . --fail-on high
if [ $? -eq 0 ]; then
  echo "Escaneo limpio"
else
  echo "Hallazgos encontrados"
fi

# En CI/CD
mcp-scan scan . --fail-on high || exit 1

Variables de Entorno¶

Variable	Descripcion	Default
`MCP_SCAN_CONFIG`	Ruta al archivo de configuracion	`.mcp-scan.yaml`
`MCP_SCAN_MODE`	Modo de analisis	`fast`
`MCP_SCAN_TIMEOUT`	Timeout de escaneo	`5m`
`MCP_SCAN_WORKERS`	Numero de workers	`auto`
`MCP_SCAN_NO_COLOR`	Desactivar colores	`false`
`MCP_SCAN_VERBOSE`	Modo verbose	`false`
`MCP_SCAN_LLM_URL`	URL de Ollama	`http://localhost:11434`
`MCP_SCAN_LLM_MODEL`	Modelo LLM	`llama3.2:3b`

# Configurar via variables de entorno
export MCP_SCAN_MODE=deep
export MCP_SCAN_TIMEOUT=10m
export MCP_SCAN_WORKERS=8

mcp-scan scan .

# O en una sola linea
MCP_SCAN_MODE=deep MCP_SCAN_TIMEOUT=10m mcp-scan scan .

Precedencia¶

La configuracion se aplica en este orden (mayor precedencia arriba):

Flags de linea de comandos
Variables de entorno
Archivo de configuracion
Valores por defecto

Combinaciones Comunes¶

CI/CD Pipeline¶

mcp-scan scan ./src \
  --mode fast \
  --output sarif \
  --fail-on high \
  --timeout 5m \
  --baseline baseline.json \
  > results.sarif

Auditoria de Seguridad¶

mcp-scan scan ./src \
  --mode deep \
  --output evidence \
  --workers 8 \
  > audit-$(date +%Y%m%d).json

Desarrollo Local¶

mcp-scan scan . \
  --mode fast \
  --exclude "**/tests/**" \
  --verbose

Integracion Continua¶

# Solo reglas criticas para PR checks
mcp-scan scan . \
  --rules "MCP-A*,MCP-D*" \
  --fail-on critical \
  --timeout 2m

Anterior: Inicio Rapido | Siguiente: Configuracion