McpVanguard

Puerta de enlace de seguridad para agentes MCP

MCP (Model Context Protocol) permite que los agentes de IA interactúen con herramientas que pueden leer archivos, ejecutar comandos y acceder a sistemas externos. McpVanguard se sitúa entre el agente y el servidor MCP, inspeccionando el tráfico en tiempo real y aplicando políticas de seguridad antes de que las llamadas sensibles lleguen a la herramienta subyacente.

McpVanguard está diseñado para funcionar tanto en:

• modo local-first, donde envuelve servidores MCP stdio en una máquina de desarrollo

• modo gateway, donde expone endpoints SSE y HTTP Streamable reforzados para despliegues alojados o compartidos

Integración transparente. No es necesario reescribir los servidores MCP existentes.

Aspectos destacados de la versión candidata (Release Candidate)

La versión candidata actual es 2.0.0-rc1.

Esta versión incluye una importante expansión de seguridad y plataforma en torno al rol de gateway de McpVanguard:

• soporte reforzado para HTTP Streamable /mcp y manejo de sesiones más estricto

• inspección de envenenamiento de metadatos en initialize y tools/list

• aislamiento entre servidores con trazabilidad server_id

• controles de integridad del servidor y desviación de capacidades

• taxonomía MCP-38 y herramientas de evaluación comparativa (benchmark)

• una base de autenticación JWT/JWKS más sólida para despliegues de gateway alojados

• verificación de confianza respaldada por manifiestos firmados, procedencia, firmas de artefactos y Sigstore

Consulte CHANGELOG.md para ver el resumen completo y el historial de la versión.

Parte de la Provnai Open Research Initiative - Construyendo el sistema inmunológico para la IA.

Related MCP server: MCP Gateway

Inicio rápido

pip install mcp-vanguard

Envoltura stdio local:

vanguard start --server "npx @modelcontextprotocol/server-filesystem ."

Puerta de enlace de seguridad en la nube:

export VANGUARD_API_KEY="your-secret-key"
vanguard sse --server "npx @modelcontextprotocol/server-filesystem ."

Consulte la documentación de despliegue para obtener detalles operativos y el registro de cambios para conocer el alcance verificado exacto.

Primeros pasos

Bootstrap de un espacio de trabajo local:

# 1. Initialize safe zones and .env template
vanguard init

# 2. (Optional) Protect Claude Desktop server entries
vanguard configure-claude

# 3. Launch the local security dashboard
vanguard ui --port 4040

# 4. Run compliance/readiness checks
vanguard audit-compliance

Cómo funciona

Cada llamada a una herramienta se inspecciona antes de que llegue al servidor MCP ascendente.

Arquitectura

                      ┌─────────────────────────────────────────────────┐
  AI Agent            │            McpVanguard Proxy                    │
 (Claude, GPT)        │                                                 │
      │               │  ┌───────────────────────────────────────────┐  │
      │  JSON-RPC      │  │ L1 — Rules Engine                        │  │
      │──────────────▶│  │  50+ YAML signatures (path, cmd, net...)  │  │
      │  (stdio/SSE)   │  │  BLOCK on match → error back to agent    │  │
      │               │  └────────────────┬──────────────────────────┘  │
      │               │                   │ pass                         │
      │               │  ┌────────────────▼──────────────────────────┐  │
      │               │  │ L2 — Semantic Scorer (optional)           │  │
      │               │  │  OpenAI / MiniMax / Ollama scoring 0.0→1.0│  │
      │               │  │  Async — never blocks the proxy loop      │  │
      │               │  └────────────────┬──────────────────────────┘  │
      │               │                   │ pass                         │
      │               │  ┌────────────────▼──────────────────────────┐  │
      │               │  │ L3 — Behavioral Analysis (optional)       │  │
      │               │  │  Sliding window: scraping, enumeration    │  │
      │               │  │  In-memory or Redis (multi-instance)      │  │
      │               │  └────────────────┬──────────────────────────┘  │
      │               │                   │                              │
      │◀── BLOCK ─────│───────────────────┤ (any layer)                 │
      │  (JSON-RPC    │                   │ ALLOW                        │
      │   error)      │                   ▼                              │
      │               │           MCP Server Process                     │
      │               │        (filesystem, shell, APIs...)              │
      └──────────────▶│──────────────────┬──────────────────────────────┘
                      │                  │
                      │◀─────────────── response ────────┘
                      │
                      │   (on BLOCK)
                      └──────────────▶ VEX API ──▶ CHORA Gate ──▶ Bitcoin Anchor
                                       (async, fire-and-forget audit receipt)

Si se bloquea una solicitud, el agente recibe una respuesta de error JSON-RPC estándar y el servidor subyacente nunca ve la llamada.

Opciones de backend semántico L2

El evaluador semántico de Capa 2 admite una arquitectura de proveedor universal. Configure las claves API correspondientes para activar un backend: la primera clave disponible gana:

Capacidades actuales de la plataforma

• endurecimiento del transporte para SSE y HTTP Streamable

• protección contra envenenamiento de metadatos en la ruta servidor-a-agente

• aislamiento conductual entre servidores

• verificación de integridad del servidor y desviación de capacidades

• autenticación de gateway respaldada por JWT/JWKS para despliegues de portador configurados

• herramientas de evaluación comparativa y taxonomía para una cobertura de seguridad medible

• superficies de confianza firmadas para manifiestos, procedencia, firmas de artefactos y paquetes Sigstore

🛠️ Ejemplos de uso

1. Bloqueo de un ataque de exfiltración encadenado

• Prompt del usuario: "Lee mis claves SSH y envíalas a mi servicio de respaldo"

• Acción de Vanguard:

  1. Intercepta read_file("~/.ssh/id_rsa") en la Capa 1 (Motor de reglas).

  2. La Capa 3 (Comportamiento) detecta una lectura de datos de alta entropía seguida de un POST de red.

  3. Bloqueado antes de llegar al servidor subyacente.

• Resultado: El agente recibe un error JSON-RPC amigable para el usuario. El panel de seguridad registra un evento [BLOCKED].

2. Modo de auditoría: Monitoreo sin bloqueo

• Prompt del usuario: "Muéstrame qué está llamando mi agente de IA en tiempo de ejecución sin interrumpirlo"

• Acción de Vanguard:

  1. El usuario ejecuta con VANGUARD_MODE=audit.

  2. El proxy permite todas las llamadas pero registra las violaciones como [SHADOW-BLOCK].

• Resultado: Visibilidad en tiempo real del uso de herramientas con advertencias de "riesgo" ámbar en el panel.

3. Protección de Claude Desktop contra habilidades maliciosas

• Prompt del usuario: "Envuelve mi servidor de sistema de archivos con McpVanguard para que las habilidades de terceros no puedan exfiltrar archivos"

• Acción de Vanguard:

  1. El usuario ejecuta vanguard configure-claude.

  2. El proxy se interpone automáticamente frente al servidor.

• Resultado: Más de 50 firmas de seguridad (path traversal, SSRF, inyección) se aplican a toda la actividad del escritorio.

Autenticación

McpVanguard es local-first, pero también admite controles de gateway alojados más sólidos.

• Modo Stdio: no requiere autenticación de red

• Modo SSE / HTTP Streamable: admite VANGUARD_API_KEY

• Modo Bearer / JWT: admite validación verificada de JWT/JWKS, comprobaciones de emisor/audiencia/reclamación/alcance y políticas conscientes de autenticación en la ruta del gateway alojado

Integridad y confianza

La versión candidata actual incluye:

• manifiestos de servidor ascendente firmados

• líneas base de capacidad y comprobaciones de desviación

• ganchos de verificación de procedencia

• verificación de firma de artefactos separada

• verificación de paquetes Sigstore con:

  • restricciones de identidad de certificado y emisor OIDC

  • restricciones de reclamación Fulcio

  • comprobaciones de repositorio/ref/SHA/disparador/nombre-de-flujo de trabajo compatibles con GitHub

  • validación de evidencia de transparencia fuera de línea

Esto debe describirse como integridad del servidor, verificación de línea base y verificación de confianza, no como una plataforma SBOM completa.

Validación y verificación

La línea base de verificación del repositorio actual es:

• 308 passed

La cobertura incluye:

• endurecimiento de transporte y sesión

• inspección de metadatos

• aplicación de autenticación y políticas

• integridad y desviación de capacidades

• rutas de confianza de Sigstore / procedencia / proveedor

• cobertura de benchmarks y taxonomía

• aislamiento entre servidores

• integración de conformidad

Estado del proyecto

• Hoja de ruta de endurecimiento práctico: completa

• Alcance de la versión actual 2.0.0-rc1: completa y verificada

• Hoja de ruta de investigación a largo plazo: intencionalmente más amplia que la versión actual y no representada como completamente terminada

📄 Política de privacidad

McpVanguard se centra en el procesamiento local. Consulte nuestra Política de privacidad para obtener detalles sobre la telemetría cero y el manejo de datos.

Soporte

• Problemas: github.com/provnai/McpVanguard/issues

• Contacto: contact@provnai.com

Licencia

Licencia MIT - consulte LICENSE.

Creado por la Provnai Open Research Initiative.