MCP Agent Firewall

Una pasarela de seguridad determinista para el tráfico de Model Context Protocol (MCP) 2026-07-28.

Se sitúa entre un agente/cliente MCP y un servidor MCP remoto, y hace cumplir ambos lados del límite de confianza:

• antes de la ejecución: integridad del protocolo, política determinista, esquemas de herramientas fijados y aprobación humana firmada

• después de la ejecución: DLP de credenciales en el lado de la respuesta, inspección acotada, etiquetado explícito de contenido no confiable y auditoría de salida con privacidad minimizada

El LLM nunca posee la decisión de seguridad.

Hito actual — v0.5.0

v0.5 añade contención de salida en el lado de la respuesta.

Una llamada de herramienta autorizada ya no se asume que produce una salida confiable. Cada respuesta ascendente se inspecciona antes de devolverse al llamante. La salida con aspecto de secreto/credencial se bloquea, el texto con aspecto de inyección de prompt se marca, y todo el contenido ascendente que se deja pasar se etiqueta explícitamente como no confiable.

agent / MCP client
        |
        v
MCP header/body integrity
        |
        v
deterministic policy
        |
        +--> DENY ------------------------------> stop
        |
        v
pinned tool catalog + JSON Schema
        |
        v
signed human approval when required
        |
        v
mcp.upstream.dispatch                   [CLIENT span]
        |
        v
upstream MCP server
        |
        |  UNTRUSTED OUTPUT
        v
mcp.output.inspect
        |
        +--> credential / secret -------------> BLOCK 502 / -32046
        |
        +--> malformed / binary / oversized --> BLOCK 502 / -32046
        |
        +--> prompt-injection signal ----------> FLAG + pass through
        |
        +--> clean ----------------------------> pass through
        |
        v
explicit untrusted-content headers
        |
        v
agent / MCP client

Parallel controls:
- privacy-minimized request + output SQLite audit
- low-cardinality OpenTelemetry metrics
- optional OTLP HTTP export

Related MCP server: guardrails-mcp-server

Contención en el lado de la respuesta

DLP de credenciales/secretos

El escáner de salida determinista bloquea material de credenciales reconocido, incluyendo:

• claves estructuradas que contienen secretos como access_token, refresh_token, api_key, private_key, authorization, password, secret y variantes relacionadas

• material de claves privadas PEM

• credenciales de tipo bearer

• IDs de clave de acceso de AWS

• tokens estilo GitHub

• credenciales estilo OpenAI sk-

• cadenas de credenciales con forma de JWT

Una respuesta ascendente bloqueada se reemplaza con un error JSON-RPC generado por el firewall:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32046,
    "message": "Upstream MCP response blocked by output containment",
    "data": {
      "action": "block",
      "signals": ["sensitive_key"],
      "untrusted": true
    }
  }
}

El cuerpo de la respuesta bloqueada no se repite en el error.

Manejo de inyección de prompt

Las expresiones regulares de inyección de prompt en la salida son señales, no una autoridad de seguridad.

Por ejemplo, contenido como "ignora las instrucciones anteriores" se permite pasar si no contiene ninguna señal de secreto bloqueante, pero el llamante recibe:

Mcp-Firewall-Untrusted-Content: true
Mcp-Firewall-Output-Inspection: flagged
Mcp-Firewall-Output-Signals: prompt_injection_signal

Incluso la salida limpia recibe:

Mcp-Firewall-Untrusted-Content: true
Mcp-Firewall-Output-Inspection: clean

Esto preserva la distinción entre datos devueltos por una herramienta e instrucciones confiables.

Límites de respuesta con cierre ante fallo

La inspección de salida bloquea:

• JSON declarado que no se puede analizar

• salida binaria que no es UTF-8

• respuestas más grandes que MAX_RESPONSE_BYTES (por defecto 262,144 bytes)

• JSON más profundo de 32 niveles

• recorridos JSON por encima de 10,000 nodos

La salida UTF-8 que comienza con { o [ se analiza como JSON incluso cuando el servidor ascendente declara un tipo de medio no JSON engañoso, lo que previene la evasión simple del tipo de contenido del DLP de claves estructuradas.

Limitación actual: httpx almacena en búfer la respuesta ascendente antes de la comprobación de tamaño. Por lo tanto, el límite acota el comportamiento de inspección/devolución, pero aún no es un límite de memoria de red en streaming.

Auditoría de salida con privacidad minimizada

GET /v1/audit/output está protegido por el mismo control X-Operator-Token que el acceso a la auditoría de solicitudes.

Los registros de auditoría de salida contienen solo:

• marca de tiempo

• nombre del método/herramienta

• resultado clean, flagged o blocked

• nombres de señales de vocabulario fijo

• SHA-256 de la respuesta

• longitud en bytes de la respuesta

Los cuerpos de respuesta ascendentes sin procesar nunca se persisten en la auditoría de salida.

Observabilidad OpenTelemetry

Los spans centrados en seguridad incluyen:

• mcp.firewall.request

• mcp.policy.evaluate

• mcp.schema.validate

• mcp.approval.issue

• mcp.approval.verify

• mcp.approval.consume

• mcp.upstream.dispatch

• mcp.output.inspect

Métricas de baja cardinalidad:

Los nombres de herramientas y los hashes de solicitudes son solo de traza, no dimensiones de métricas. Las cadenas de traza se sanitizan y se limitan en longitud. Los argumentos de solicitud sin procesar, los cuerpos de respuesta, los recibos de aprobación, las identidades y los tokens de autenticación se excluyen de la telemetría.

Controles del lado de la solicitud conservados de v0.1–v0.4

• comprobaciones de integridad de MCP-Protocol-Version, Mcp-Method y Mcp-Name

• política de herramientas determinista de denegación por defecto

• patrones de denegación explícitos para herramientas de tipo shell/comando/credencial

• aprobación humana para herramientas consecuentes de enviar/crear/actualizar/eliminar/comprar/transferir/desplegar

• restricciones de solicitud anidadas de claves secretas, rutas protegidas, tamaño de cadenas y numéricas

• señales de inyección de prompt sin otorgar autoridad de seguridad a las expresiones regulares

• catálogo de herramientas confiables fijado con SHA-256

• validación de argumentos JSON Schema 2020-12

• verificación de encabezado-cuerpo confiable x-mcp-header / Mcp-Param-*

• recibos de aprobación de un solo uso de corta duración HMAC-SHA256

• autorización del llamante nunca reenviada aguas arriba

• limitación de tasa por proceso y cuerpos de solicitud acotados

• extracción de W3C TraceContext + propagación ascendente generada

• exportación opcional de trazas/métricas OTLP HTTP

Configurar

UPSTREAM_MCP_URL=https://your-mcp-server.example/mcp
MAX_BODY_BYTES=65536
MAX_RESPONSE_BYTES=262144

APPROVAL_SIGNING_KEY=<random-secret-at-least-32-bytes>
APPROVAL_ISSUER_TOKEN=<operator-only-token>
APPROVAL_DEFAULT_TTL_SECONDS=300
APPROVAL_MAX_TTL_SECONDS=900

TRUSTED_TOOL_CATALOG_PATH=./config/trusted_tools.example.json
TRUSTED_TOOL_CATALOG_SHA256=<canonical-catalog-sha256>

AUDIT_READ_TOKEN=<operator-only-token>

OTEL_ENABLED=false
OTEL_SERVICE_NAME=mcp-agent-firewall
OTEL_EXPORTER_OTLP_ENDPOINT=

Ejecutar todas las comprobaciones

pip install -e ".[dev]"
ruff check app tests scripts
pytest -q
python scripts/run_benchmark.py --fail-on-unsafe
python scripts/run_approval_benchmark.py
python scripts/run_schema_benchmark.py
python scripts/run_observability_benchmark.py
python scripts/run_output_benchmark.py
docker build -t mcp-agent-firewall:test .

Evidencia de regresión verificada para v0.5

Verificado en GitHub Actions para la implementación de v0.5:

• 74 pruebas pytest aprobadas

• benchmark de seguridad de políticas: 32/32 decisiones exactas

• benchmark de seguridad de políticas: 0 aceptaciones falsas inseguras, 0 bloqueos falsos

• benchmark de seguridad de aprobación firmada: 11/11 aprobados

• benchmark de seguridad de aprobación firmada: 0 aceptaciones falsas inseguras

• benchmark de esquema confiable / encabezado MCP: 12/12 aprobados

• benchmark de esquema confiable / encabezado MCP: 0 aceptaciones falsas inseguras, 0 bloqueos falsos

• benchmark de privacidad/propagación de observabilidad: 14/14 aprobados

• benchmark de observabilidad: 0 fugas de telemetría detectadas

• benchmark de contención de salida: 11/11 aprobados

• benchmark de contención de salida: 0 aceptaciones falsas inseguras

• Ruff: aprobado

• construcción Docker: aprobada

El benchmark de contención de salida cubre paso limpio, claves secretas estructuradas, claves privadas PEM, credenciales bearer, credenciales estilo GitHub, señalización de inyección de prompt, JSON malformado, salida binaria, límites de tamaño de respuesta, tipos de contenido engañosos y metadatos de inspección públicos sin eco.

El benchmark de observabilidad ejercita solicitudes reales FastAPI/MCP y comprueba el contexto padre W3C, los spans de política/esquema/aprobación/salida, las dimensiones de métricas acotadas, la propagación de traza ascendente generada, el etiquetado de salida no confiable y la ausencia de un centinela de secreto inyectado en la telemetría capturada.

Estas son pruebas de regresión sintéticas, no una afirmación de seguridad de producción universal ni de detección completa de credenciales/inyección de prompt.

Consulte docs/THREAT_MODEL.md para conocer los límites de confianza, los controles y los riesgos residuales.

Próximos hitos

1. rotación de la clave de firma de aprobación con IDs de clave y solapamiento acotado

2. aplicación del tamaño de respuesta en streaming y listas de permitidos opcionales de tipos de contenido seguros

3. estado compartido de repetición/límite de tasa para despliegue multi-réplica

4. detección de deriva en vivo de tools/list ascendente contra el catálogo fijado

5. backend opcional OPA/Rego con respaldo local determinista

6. corpus adversarial derivado de trazas MCP reales