MCP Tool Security Inspector

MCP Tool Security Inspector

Análisis estático determinista y explicable para metadatos de herramientas del Model Context Protocol.

Aviso de seguridad: MCP Tool Security Inspector es una herramienta de análisis defensivo. Identifica indicadores que pueden merecer revisión, pero no establece si una herramienta o servidor MCP es definitivamente malicioso o seguro.

Marcadores de posición de capturas de pantalla

• screenshots/clean-scan.png — resumen de catálogo limpio

• screenshots/suspicious-scan.png — evidencia y recomendaciones de hallazgos

• screenshots/drift-comparison.png — tabla de deriva de línea base

Related MCP server: mcp-guardian

El problema

Los clientes de IA a menudo exponen nombres de herramientas MCP, descripciones, esquemas y metadatos a un modelo. Ese catálogo es un límite de confianza: instrucciones engañosas, capacidades ocultas, campos de credenciales inesperados o cambios posteriores en el esquema merecen revisión incluso cuando no se ha ejecutado ninguna herramienta. mcpsec analiza esa superficie estática sin invocar herramientas ni obtener URLs de metadatos.

¿Qué son MCP y las herramientas MCP?

Model Context Protocol es un protocolo abierto para conectar aplicaciones de IA a servidores que exponen contexto y capacidades. Una herramienta es una capacidad invocable con nombre, con metadatos descriptivos y esquemas JSON para entradas y salidas opcionales. Esta versión se dirige a la especificación oficial 2026-07-28 y al SDK oficial estable de Python v2, tolerando a la vez envoltorios de catálogo comunes más antiguos.

Modelo de amenazas y envenenamiento de herramientas

Los metadatos de las herramientas pueden influir tanto en la aprobación humana como en la selección de herramientas por parte del modelo. Un publicador malintencionado, un servidor comprometido, una dependencia o una configuración accidental podrían añadir instrucciones dirigidas por el modelo, lenguaje de ocultación, campos privilegiados u ofuscación. Ver modelo de amenazas y envenenamiento de herramientas.

Características

• Carga de herramienta única, matriz, objeto tools directo y respuestas JSON-RPC tools/list

• Preservación de campos desconocidos y normalización Unicode NFC

• JSON canónico UTF-8 estable y huellas SHA-256 completas/por componente

• Líneas base respetuosas con la privacidad y clasificación de deriva a nivel de campo

• Detectores de anulación de instrucciones, ocultación, datos sensibles, esquema, discrepancia, ofuscación y capacidades

• Reglas YAML estrictas solo de datos mediante carga segura y coincidencia literal acotada

• Puntuaciones de riesgo explicables y con tope de 0 a 100

• Salida enriquecida para terminal, JSON, CSV y SARIF 2.1.0

• Redacción de evidencia y mitigación de inyección de fórmulas en hojas de cálculo

• Umbrales de gravedad para CI con códigos de salida documentados

• Sin telemetría, llamadas a herramientas, descargas de iconos, obtención de URLs ni ejecución de metadatos

Arquitectura

flowchart LR
  A["Hostile JSON catalog"] --> B["Bounded loader"]
  B --> C["Normalizer"]
  C --> D["Canonicalizer + SHA-256"]
  C --> E["Detectors + data-only rules"]
  E --> F["Capped risk engine"]
  D --> G["Baseline comparator"]
  F --> H["Terminal / JSON / CSV / SARIF"]
  G --> H

La implementación nunca envía el contenido del catálogo a un modelo ni ejecuta valores escaneados. Ver arquitectura.

Instalación

python -m venv .venv
# Windows: .\.venv\Scripts\Activate.ps1
# Linux/macOS: source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
mcpsec --help

Ver PREPARATION.md para el entorno auditado y las recomendaciones de editor.

Inicio rápido y escaneos

mcpsec scan examples/clean_tools.json
mcpsec scan examples/suspicious_tools.json
mcpsec scan examples/mixed_tools.json --format json
mcpsec scan examples/suspicious_tools.json --format csv --output report.csv --redact
mcpsec scan examples/suspicious_tools.json --format sarif --output report.sarif
mcpsec scan examples/mixed_tools.json --rules rules/default_rules.yml --fail-on high

Los informes estructurados no contienen secuencias de escape ANSI. Los campos CSV que comienzan con caracteres de fórmula de hoja de cálculo se prefijan con un apóstrofo.

Flujo de trabajo de línea base y deriva de esquema

mcpsec baseline examples/clean_tools.json --output baseline.json
mcpsec compare examples/clean_tools.json --baseline baseline.json
mcpsec compare examples/changed_tools.json --baseline baseline.json --verbose
mcpsec fingerprint examples/clean_tools.json

El fixture modificado cambia la descripción de la calculadora y el esquema de entrada, y añade unit_converter. Las líneas base almacenan hashes y resúmenes estructurales, no descripciones completas, valores predeterminados ni secretos de ejemplo. Ver deriva de esquema.

Puntuación de riesgo

La contribución configurada de cada hallazgo se multiplica por la confianza. Las contribuciones se agrupan y limitan a 35 por categoría; los riesgos de categoría se combinan usando 100 × (1 − Π(1 − categoría/100)). Dos correlaciones documentadas añaden sinergia acotada: anulación de instrucciones + ocultación suma 10, y ocultación + lenguaje de datos sensibles suma 7. El valor final se redondea y limita a 100.

Bandas: 0–19 informativo, 20–39 bajo, 40–59 medio, 60–79 alto, 80–100 crítico. Una puntuación prioriza la revisión; no es una probabilidad ni un veredicto.

Reglas y explicabilidad

mcpsec rules list
mcpsec rules validate rules/default_rules.yml
mcpsec explain SEC-001

Las reglas personalizadas permiten ID, nombre, categoría, campos, patrones literales, gravedad, confianza, puntuación, recomendación, justificación, uso benigno y estado habilitado. No pueden contener expresiones Python, comandos de shell, importaciones, plantillas ni expresiones regulares ejecutables. Ver reglas de detección.

Formatos de salida

La tabla de terminal resume recuentos de herramientas, totales limpios/afectados, gravedad, riesgo, IDs de regla, evidencia y recomendaciones. JSON conserva hallazgos tipados; CSV es apto para análisis; SARIF proporciona una estructura compatible con GitHub code scanning para integración futura.

Uso en CI

Los códigos de salida son 0 si no se supera ningún umbral configurado, 1 para un escaneo completado que supera --fail-on, 2 para entrada de usuario no válida y 3 para un fallo interno.

mcpsec scan catalog.json --fail-on medium

El flujo de trabajo de GitHub Actions incluido instala Python, ejecuta comprobaciones de Ruff lint/formato, mypy y pytest con cobertura. No requiere secretos, no se conecta a servidores y no publica.

Pruebas

ruff check .
ruff format --check .
mypy src
python -m pytest --cov=mcpsec --cov-report=term-missing --cov-report=html

En Windows, scripts\test.ps1 -q ejecuta el intérprete correcto del entorno virtual incluso cuando el entorno no está activado. Usa scripts\dev-inspector.ps1 para el servidor de demostración local; ver la guía del servidor de ejemplo. La dirección /sandbox impresa por Inspector es un endpoint de iframe interno, no la interfaz de usuario principal.

Las pruebas cubren formas de entrada, Unicode, canonicalización, hashes, líneas base, deriva, detectores, límites de riesgo, validación de reglas, YAML seguro, informes estructurados, neutralización CSV y códigos de salida de CLI.

Modelo de seguridad y falsos positivos

Toda entrada son datos no confiables. Los archivos tienen límite de tamaño; las cadenas tienen límite de longitud; YAML usa safe_load; el contenido del esquema se valida pero nunca se evalúa; la coincidencia personalizada es literal y acotada; los bytes de escape de terminal se neutralizan; los informes no renderizan HTML. Un hallazgo dice "sospechoso" o "requiere revisión", nunca afirma un compromiso. Cada regla integrada documenta su justificación, desencadenantes benignos y orientación mediante mcpsec explain.

Ver SECURITY.md, reglas de detección y limitaciones.

Limitaciones

Un escaneo limpio no establece confianza; un escaneo sospechoso no demuestra intención maliciosa. Los metadatos estáticos pueden diferir de la implementación en tiempo de ejecución. Las heurísticas no pueden entender todos los idiomas, contextos de negocio, referencias de esquema o variaciones de inyección de instrucciones. La revisión humana y los controles de tiempo de ejecución siguen siendo necesarios.

Hoja de ruta

• v0.2: recuperación de catálogo local opcional y en lista blanca usando solo tools/list del SDK

• Validación más rica de x-mcp-header de MCP 2026-07-28

• Sobres de línea base firmados y perfiles de política de línea base

• Versionado de paquetes de reglas, supresiones con justificación y SARIF delta

• Heurísticas adicionales conscientes del idioma y medición de falsos positivos basada en corpus

Contribuciones y licencia

Ver CONTRIBUTING.md. Los informes de seguridad siguen SECURITY.md. Licenciado bajo la Licencia MIT.