⚠️ Este repositorio se ha movido. El desarrollo activo continúa en ScopeBlind/scopeblind-gateway.

Este fork personal podría estar detrás del repositorio canónico. Por favor, usa el repo de la organización para issues, pull requests y el código más reciente.

protect-mcp

Puerta de enlace de seguridad para servidores MCP. Registro en modo sombra por defecto, políticas por herramienta, recibos Ed25519 locales opcionales y salida de auditoría amigable para verificación.

Ruta actual de CLI: envuelve cualquier servidor MCP stdio como un proxy transparente. En modo sombra registra cada solicitud tools/call y permite todo. Añade un archivo de política para aplicar reglas por herramienta. Ejecuta protect-mcp init para generar claves de firma locales y configuración para que la puerta de enlace también pueda emitir recibos firmados.

Quick Start

# Wrap an existing OpenClaw / MCP config into a usable pack
npx @scopeblind/passport wrap --runtime openclaw --config ./openclaw.json --policy email-safe

# Shadow mode — log every tool call, enforce nothing
npx protect-mcp -- node my-server.js

# Generate keys + config template for local signing
npx protect-mcp init

# Shadow mode with local signing enabled
npx protect-mcp --policy protect-mcp.json -- node my-server.js

# Enforce mode
npx protect-mcp --policy protect-mcp.json --enforce -- node my-server.js

# Export an offline-verifiable audit bundle
npx protect-mcp bundle --output audit.json

Qué Hace

protect-mcp se sitúa entre tu cliente MCP y el servidor como un proxy stdio:

MCP Client ←stdin/stdout→ protect-mcp ←stdin/stdout→ your MCP server

Intercepta las solicitudes JSON-RPC tools/call y:

• Modo sombra (por defecto): registra cada llamada a herramienta y permite todo
• Modo de aplicación: aplica reglas de política por herramienta como block, rate_limit y min_tier
• Firma local opcional: cuando la firma está configurada, emite un recibo firmado con Ed25519 junto con el registro estructurado

Todos los demás mensajes MCP (initialize, tools/list, notificaciones) pasan de forma transparente.

Lo Que Incluye Hoy

• Políticas por herramienta — bloquear herramientas destructivas, limitar la tasa de las costosas y adjuntar requisitos de nivel mínimo
• Registros de decisión estructurados — cada decisión se emite a stderr con [PROTECT_MCP]
• Recibos firmados locales opcionales — generados cuando ejecutas con una política que contiene signing.key_path, persistidos en .protect-mcp-receipts.jsonl, y expuestos en http://127.0.0.1:9876/receipts
• Verificación offline — verifica recibos o paquetes con npx @veritasacta/verify
• Sin necesidad de cuenta — claves locales, política local, proceso local

Límites Actuales de Capacidad

Estos son importantes antes de implementar esto o hablar con usuarios:

• La firma no es automática en la ruta simple npx protect-mcp -- .... Esa ruta registra decisiones en modo sombra. Para firma local, ejecuta npx protect-mcp init y luego inicia la puerta de enlace con el archivo de política generado.
• Las comprobaciones de política conscientes de nivel están activas, pero la admisión de manifiestos no está integrada en la ruta CLI/stdio por defecto. La CLI establece las sesiones como unknown por defecto a menos que una integración host llame a la API de admisión programáticamente.
• La configuración de credenciales actualmente valida referencias de credenciales respaldadas por variables de entorno y registra etiquetas de credenciales en registros/recibos. La inyección genérica por llamada en herramientas stdio arbitrarias es específica del adaptador y no la realiza la ruta proxy por defecto.
• Los adaptadores PDP externos y las herramientas de paquetes de auditoría existen como utilidades exportadas. Aún no están completamente integrados en la ruta CLI por defecto.

Archivo de Política

{
  "default_tier": "unknown",
  "tools": {
    "dangerous_tool": { "block": true },
    "admin_tool": { "min_tier": "signed-known", "rate_limit": "5/hour" },
    "read_tool": { "require": "any", "rate_limit": "100/hour" },
    "*": { "rate_limit": "500/hour" }
  },
  "signing": {
    "key_path": "./keys/gateway.json",
    "issuer": "protect-mcp",
    "enabled": true
  },
  "credentials": {
    "internal_api": {
      "inject": "env",
      "name": "INTERNAL_API_KEY",
      "value_env": "INTERNAL_API_KEY"
    }
  }
}

Reglas de Política

Los nombres de herramientas coinciden exactamente, con "*" como comodín de respaldo.

Configuración del Cliente MCP

Claude Desktop

Añadir a claude_desktop_config.json:

{
  "mcpServers": {
    "my-protected-server": {
      "command": "npx",
      "args": [
        "-y", "protect-mcp",
        "--policy", "/path/to/protect-mcp.json",
        "--enforce",
        "--", "node", "my-server.js"
      ]
    }
  }
}

Cursor / VS Code

Mismo patrón — reemplaza el comando del servidor con protect-mcp envolviéndolo.

Opciones de CLI

protect-mcp [options] -- <command> [args...]
protect-mcp init

Commands:
  init              Generar par de claves Ed25519 + plantilla de configuración
  status            Muestra estadísticas de decisiones y identidad local de passport
  digest            Generar un resumen local legible por humanos
  receipts          Mostrar recibos firmados persistidos recientemente
  bundle            Exportar un paquete de auditoría verificable offline

Options:
  --policy <path>   Archivo JSON de política/configuración
  --slug <slug>     Identificador de servicio para registros/recibos
  --enforce         Habilitar modo de aplicación (por defecto: sombra)
  --verbose         Habilitar registro de depuración
  --help            Mostrar ayuda

Hooks Programáticos

La librería también expone las primitivas que aún no están integradas en la ruta CLI por defecto:

import {
  ProtectGateway,
  loadPolicy,
  evaluateTier,
  meetsMinTier,
  resolveCredential,
  initSigning,
  signDecision,
  queryExternalPDP,
  buildDecisionContext,
  createAuditBundle,
} from 'protect-mcp';

Úsalas si quieres añadir:

• admisión de manifiesto antes de que comience una sesión
• un PDP externo (OPA, Cerbos, o un webhook HTTP genérico)
• integraciones personalizadas con credenciales intermediadas
• exportación de paquetes de auditoría alrededor de tu propio almacén de recibos

Registros de Decisión y Recibos

Cada llamada a herramienta emite JSON estructurado a stderr:

[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","reason_code":"observe_mode","policy_digest":"none","mode":"shadow","timestamp":1710000000}

Cuando la firma está configurada, le sigue un recibo firmado:

[PROTECT_MCP_RECEIPT] {"v":2,"type":"decision_receipt","algorithm":"ed25519","kid":"...","issuer":"protect-mcp","issued_at":"2026-03-22T00:00:00Z","payload":{"tool":"read_file","decision":"allow","policy_digest":"...","mode":"shadow","request_id":"..."},"signature":"..."}

Verificar con la CLI: npx @veritasacta/verify receipt.json Verificar en el navegador: scopeblind.com/verify

Paquetes de Auditoría

El paquete exporta un helper para paquetes de auditoría autocontenidos:

{
  "format": "scopeblind:audit-bundle",
  "version": 1,
  "tenant": "my-service",
  "receipts": ["..."],
  "verification": {
    "algorithm": "ed25519",
    "signing_keys": ["..."]
  }
}

Usa createAuditBundle() alrededor de tus propios recibos firmados recolectados.

Filosofía

• Sombra primero. Ve lo que los agentes están haciendo antes de aplicar nada.
• Los recibos superan a los registros solo de dashboard. Los artefactos firmados deben ser verificables de forma independiente.
• Mantén las afirmaciones ajustadas. La ruta CLI por defecto aún no hace todo lo que la arquitectura a largo plazo soportará.
• Superpón sobre la autenticación existente. No desarmes tu stack solo para añadir control y evidencia.

Paquetes de Políticas Ancladas a Incidentes

Incluidos con protect-mcp — cada uno previene un ataque real:

npx protect-mcp --policy node_modules/protect-mcp/policies/clinejection.json -- node server.js

Mapeo completo del OWASP Agentic Top 10: scopeblind.com/docs/owasp

BYOPE: Motores de Política Externos

Soporta OPA, Cerbos, Cedar (AWS AgentCore) y endpoints HTTP genéricos:

{
  "policy_engine": "hybrid",
  "external": {
    "endpoint": "http://localhost:8181/v1/data/mcp/allow",
    "format": "cedar",
    "timeout_ms": 200,
    "fallback": "deny"
  }
}

Estándares y PI

• Borrador de Internet de la IETF: draft-farley-acta-signed-receipts-00 — Recibos de Decisión Firmados para Control de Acceso Máquina a Máquina
• Estado de Patentes: 4 patentes provisionales australianas pendientes (2025-2026) que cubren recibos de decisión con divulgación configurable, puerta de enlace de llamadas a herramientas, manifiestos de agente e identidad portátil
• Verificación: Licencia MIT — npx @veritasacta/verify --self-test

Licencia

MIT — libre de usar, modificar, distribuir y construir sobre ello sin restricciones.

scopeblind.com · npm · GitHub · IETF Draft