McpVanguard

McpVanguard

Puerta de enlace de seguridad para agentes MCP y servidores de herramientas.

McpVanguard se sitúa entre un agente de IA y un servidor MCP, normaliza e inspecciona el tráfico de herramientas en tiempo real, y aplica una política en capas antes de que las llamadas sensibles lleguen a la herramienta subyacente. Se ejecuta localmente frente a servidores stdio o como puerta de enlace alojada sobre SSE y Streamable HTTP.

Perfiles de producto — monitor, balanced, strict — le permiten adoptar de forma incremental: comience con descubrimiento solo de auditoría, avance a aplicación equilibrada y luego habilite el endurecimiento estricto para sistemas sensibles en producción.

Los servidores MCP existentes no necesitan ser reescritos.

Por Qué Lo Usan Los Desarrolladores

Los flujos de trabajo MCP son potentes, pero una vez que las herramientas tocan archivos, shells o redes, las salvaguardas importan.

McpVanguard añade un límite de aplicación en tiempo de ejecución para que pueda:

• mantener fluyendo el tráfico normal de herramientas
• bloquear llamadas inseguras antes de la ejecución
• inspeccionar y depurar decisiones de política con registros de auditoría
• adoptar de forma incremental sin reescribir servidores MCP existentes

Qué Hace

McpVanguard está dirigido a desarrolladores y equipos de plataforma que desean aplicación explícita de políticas en torno a flujos de trabajo MCP.

• inspeccionar llamadas a herramientas MCP antes de la ejecución
• bloquear patrones inseguros de sistema de archivos, comandos y red
• aplicar requisitos de autenticación, rol y alcance para herramientas sensibles
• inspeccionar metadatos del servidor antes de que lleguen a modelos posteriores
• rastrear comportamiento sospechoso repetido a lo largo del tiempo
• emitir señales de auditoría y telemetría para tráfico bloqueado, advertido y permitido

Escenario Rápido de Verificación

Use una ruta sin protección y una ruta protegida contra el mismo servidor MCP.

• la lectura segura de archivos pasa en ambas rutas
• el intento de traversal de rutas se bloquea en la ruta protegida
• la solicitud de red riesgosa se bloquea en la ruta protegida
• los intentos de envenenamiento de metadatos se filtran o bloquean antes de la exposición al modelo

Esto le da una señal rápida de que la política está activa y la aplicación se comporta como se espera.

Casos de Uso

• proteger servidores MCP locales de escritorio o máquinas de desarrollo sin reescribirlos
• añadir una puerta de enlace alojada frente a servidores MCP compartidos
• comparar comportamiento sin protección versus protegido para flujos de trabajo de herramientas riesgosas
• añadir aplicación de políticas a herramientas de alto riesgo de archivos, shell y acceso a red

Inicio Rápido

Instale el paquete:

pip install mcp-vanguard

Extras opcionales de despliegue:

# Multi-instance L3 behavioral state
pip install "mcp-vanguard[redis]"

# RE2-backed deterministic regex matching where the wheel is available
pip install "mcp-vanguard[re2]"

# Hosted/full deployment extras
pip install "mcp-vanguard[full]"

Envuelva un servidor MCP stdio local:

# Balanced profile (default OSS/developer behavior)
vanguard start --profile balanced --server "npx @modelcontextprotocol/server-filesystem ."

# Strict profile (production hardening)
vanguard start --profile strict --server "npx @modelcontextprotocol/server-filesystem ."

Ejecute como puerta de enlace alojada:

export VANGUARD_API_KEY="replace-with-a-long-random-secret"
vanguard sse --profile balanced --server "npx @modelcontextprotocol/server-filesystem ."

Para despliegues alojados públicos/no-loopback, el perfil strict se niega a iniciar a menos que la autenticación de transporte esté configurada con un VANGUARD_API_KEY aleatorio largo o ajustes OAuth/JWKS. balanced sigue siendo adecuado para demostraciones y despliegues por etapas, pero advertirá en voz alta cuando se exponga sin autenticación.

Los despliegues alojados también pueden habilitar presupuestos opcionales por sesión para la tasa de llamadas a herramientas, decisiones riesgosas e intentos bloqueados repetidos. Estos actúan como interruptores automáticos alrededor de la ruta de política en capas sin cambiar los valores predeterminados para uso OSS local.

Si opera una plantilla alojada o una puerta de enlace compartida, establezca VANGUARD_ALLOWED_SERVER_COMMANDS para restringir qué ejecutables de servidor MCP ascendentes puede generar McpVanguard.

Para servidores MCP de red privada alcanzados a través de túneles MCP de Anthropic, la ubicación recomendada es túnel -> McpVanguard -> servidor MCP privado. Los túneles reducen la exposición de red. McpVanguard aplica el límite de ejecución.

McpVanguard proporciona una línea base de compatibilidad MCP 2026-07-28 documentada en la línea 2.2.x. La línea base incluye un perfil de transporte sin estado opt-in, comprobaciones de consistencia aditivas Mcp-Method / Mcp-Name y cobertura de inspección explícita de _meta. No es una afirmación de conformidad completa con Tasks, MCP Apps, suscripciones, MRTR o la especificación final. Consulte docs/MCP_2026_07_28_RC_COMPATIBILITY.md.

Despliegue en Railway:

¿Necesita un recorrido completo de despliegue? Consulte docs/DEPLOYMENT.md, docs/railway-deployment-guide.md y docs/ANTHROPIC_MCP_TUNNELS.md.

Primeros Pasos

Inicie un espacio de trabajo local:

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

# 2. Optionally update Claude Desktop server entries
vanguard configure-claude

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

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

Cómo Funciona

McpVanguard utiliza cinco capas de inspección principales, L0 a través de L3 más L1.5, con política de autenticación y un compositor de políticas final a su alrededor. Cada llamada a herramienta se inspecciona antes de llegar al servidor MCP ascendente.

Capa	Propósito	Notas
L0 - Preflight	Normalizar y anotar (URL decode, NFKC, eliminar ancho cero, límites de tamaño/profundidad)	Siempre activa
Auth	Aplicación de alcance OAuth y política de herramientas destructivas	Consciente del rol
L1 - Reglas	Bloqueo determinista usando firmas, inspección recursiva de argumentos y límites seguros	Ruta rápida
L1.5 - Camuflaje	Detectar camuflaje de señales de confianza y manipulación de puntuadores	Sensible al perfil
L2 - Semántica	Puntuación de intención opcional (puede escalar/bloquear, no puede degradar bloqueos deterministas)	Asíncrona
L3 - Conductual	Comprobaciones de anomalías conscientes de sesión y secuencia	Con estado
Compositor de Políticas	Veredicto final: ALLOW / WARN / REVIEW / SHADOW-BLOCK / BLOCK	Explicable

Las cinco capas de inspección principales son L0, L1, L1.5, L2 y L3. La política de autenticación y el compositor de políticas final se sitúan alrededor de esa ruta principal.

Si una solicitud se bloquea, el agente recibe un error JSON-RPC estándar y el servidor ascendente nunca ve la llamada. El registro de auditoría registra la razón principal y todos los hallazgos de apoyo.

Las zonas seguras son comprobaciones deterministas de límites de ruta, no un sustituto del sandboxing del SO o el aislamiento de contenedores. Inspeccionan recursivamente nombres de argumentos estándar y comunes personalizados similares a rutas, pero los despliegues de producción aún deben ajustar rules/safe_zones.yaml para los esquemas y directorios reales que sus herramientas MCP pueden tocar. Consulte docs/SAFE_ZONES.md.

Para el triaje del operador, los registros de auditoría JSON incluyen campos de decisión compatibles con SIEM y datos estructurados de policy_explanation con la capa principal, familia de reglas, efecto del perfil, estado de llamada ascendente y sugerencia de ajuste. Consulte docs/BLOCK_DECISIONS.md.

Modelo de Despliegue

McpVanguard se entiende mejor como una puerta de enlace de seguridad para flujos de trabajo MCP.

• Modo local primero: envuelve servidores MCP stdio en una máquina de desarrollador
• Modo puerta de enlace: expone endpoints SSE y Streamable HTTP endurecidos para despliegues alojados o compartidos

Ruta típica:

AI Agent -> McpVanguard -> MCP Server -> Tools / Files / External Systems

Capacidades Actuales

• rutas de transporte SSE y Streamable HTTP endurecidas con controles de tasa de solicitudes, concurrencia, vinculación de sesión y conteo de sesiones
• inspección de envenenamiento de metadatos en initialize y tools/list
• comprobaciones JWT, JWKS, emisor, audiencia, reclamo y alcance para despliegues con autenticación bearer
• verificación de integridad del servidor y deriva de capacidades
• aislamiento entre servidores y trazabilidad server_id
• verificación de confianza respaldada por manifiestos firmados, procedencia, firmas separadas y Sigstore
• herramientas de referencia y taxonomía para cobertura medible
• emisión opcional de JSONL receipt_v1 para evidencia de ejecución verificable sin conexión con mcp-receipt después de exportar/firmar

Referencias

McpVanguard incluye corpus de referencia empaquetados para tráfico MCP adversarial y benigno. Úselos para comparar perfiles antes del despliegue:

vanguard benchmark-run --profile monitor
vanguard benchmark-run --profile balanced
vanguard benchmark-run --profile strict
vanguard benchmark-profiles
vanguard benchmark-baselines

Los resultados de referencia son una señal de lanzamiento y ajuste, no una promesa de detección universal o cero falsos positivos. Consulte docs/BENCHMARKS.md para orientación de interpretación y la puerta de lanzamiento recomendada.

Para la nota de investigación pública detrás del diseño en capas, consulte Por Qué la Seguridad MCP Necesita Aplicación en Capas en Tiempo de Ejecución.

Modos de Autenticación

McpVanguard es local primero y admite controles más fuertes de puerta de enlace alojada cuando sea necesario.

• modo stdio: no requiere autenticación de red
• modo SSE / Streamable HTTP: admite VANGUARD_API_KEY
• modo Bearer / JWT: admite validación JWT/JWKS verificada, comprobaciones de emisor/audiencia/reclamo/alcance y política consciente de autenticación en la ruta de puerta de enlace alojada
• modo alojado estricto: se niega a enlazar públicamente sin autenticación de transporte, establece el manejo de discrepancia de reclamos bearer a block y requiere Origin cuando se configura una lista de permitidos

Plano de Gestión

Las herramientas de gestión nativas de vanguard_* están deshabilitadas por defecto. Si las habilita, también elija un modo explícito de plano de gestión:

• disabled: no se exponen herramientas de gestión nativas
• same_session_dev: solo local/dev; las herramientas de lectura y mutación comparten la sesión MCP gobernada y el inicio imprime una advertencia
• operator_only: las herramientas de solo lectura pueden ser visibles, pero las herramientas de mutación requieren un rol de administrador o alcance vanguard:admin / scope:admin

Para producción, mantenga la gestión de mutación fuera de las sesiones normales de agentes gobernados a menos que el llamador sea un operador autenticado. Las acciones de gestión se auditan y los intentos denegados/de mutación son visibles para el riesgo.

Opciones de Backend Semántico

El puntuador semántico opcional de la Capa 2 admite múltiples backends. El primer backend configurado gana.

Backend	Variables de Entorno	Notas
Universal Personalizado	VANGUARD_SEMANTIC_CUSTOM_KEY, variables personalizadas relacionadas	Proveedores de inferencia rápidos como Groq o DeepSeek
OpenAI	VANGUARD_OPENAI_API_KEY	Modelo predeterminado: gpt-4o-mini
Ollama	VANGUARD_OLLAMA_URL	Ejecución local, sin clave API requerida

Para una guía más detallada de configuración local/sin conexión, consulte docs/LOCAL_SEMANTIC_MODE.md.

Integridad y Confianza

McpVanguard incluye:

• manifiestos firmados de servidores ascendentes
• líneas base de capacidades y comprobaciones de deriva
• enlaces de verificación de procedencia
• verificación de firmas de artefactos separadas
• verificación de paquetes Sigstore con restricciones de identidad y emisor

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

Estado del Proyecto

• 2.2.x es la línea actual de endurecimiento en tiempo de ejecución y línea base de compatibilidad MCP 2026-07-28
• la ruta de aplicación en capas (L0 -> L1 -> L1.5 -> L2 -> L3 -> Policy Composer) está implementada y cubierta por verificación local y CI
• los perfiles de producto (monitor / balanced / strict) son los modos de despliegue admitidos para esta línea de lanzamiento
• características más amplias solo de investigación (atestación GPU, procedencia con raíz de hardware, afirmaciones de cero falsos positivos) están intencionalmente fuera del alcance principal del lanzamiento OSS

Consulte CHANGELOG.md para el historial de lanzamientos y docs/DEPLOYMENT.md para detalles de despliegue.

Privacidad

McpVanguard se centra en la inspección local y la aplicación de puerta de enlace. Consulte PRIVACY.md para detalles actuales de privacidad y manejo de datos.

Soporte

• Problemas: github.com/provnai/McpVanguard/issues
• Contacto: contact@provnai.com
• Seguridad: consulte SECURITY.md

Preguntas Frecuentes

¿Esto reemplaza mi servidor MCP?
No. McpVanguard se sitúa frente a su servidor MCP existente y aplica políticas antes de que las llamadas lleguen a él.

¿Necesito reescribir herramientas o código de agente?
Generalmente no. La mayoría de las configuraciones comienzan enrutando un flujo de trabajo a través de McpVanguard.

¿Es solo para configuraciones alojadas?
No. Admite envoltura stdio local primero y modos de puerta de enlace alojada.

Licencia

Licencia MIT - consulte LICENSE.

Construido por Provnai.