protect-mcp

Puerta de enlace de seguridad empresarial para servidores MCP y hooks de Claude Code. Recibos firmados, políticas Cedar y pistas de auditoría conscientes de enjambres.

Integrado en Microsoft Agent Governance Toolkit | IETF Internet-Draft | Demostración en vivo: acta.today/wiki

Inicio rápido — Claude Code

Dos comandos. Cada llamada a herramienta recibe un recibo.

# 1. Generate hooks, keys, Cedar policy, and /verify-receipt skill
npx protect-mcp init-hooks

# 2. Start the hook server
npx protect-mcp serve

Abra Claude Code en el mismo proyecto. Cada llamada a herramienta ahora es interceptada, evaluada y firmada.

Lo que crea init-hooks

Arquitectura

Claude Code  →  POST /hook  →  protect-mcp (Cedar + sign)  →  response
                                    ↓
                            .protect-mcp-log.jsonl
                            .protect-mcp-receipts.jsonl

• PreToolUse: verificación de política Cedar síncrona → denegar bloquea la herramienta

• PostToolUse: firma de recibo asíncrona → impacto de latencia cero

• denegar es arquitectónicamente definitivo — no puede ser anulado por el modelo u otros hooks

Endpoints

Verificar recibos

# Inside Claude Code:
/verify-receipt

# From terminal:
curl http://127.0.0.1:9377/receipts/latest | jq .
npx protect-mcp receipts

# Check policy suggestions:
curl http://127.0.0.1:9377/suggestions | jq .

Related MCP server: verify-mcp

Inicio rápido — Wrapper de servidor MCP

Envuelva cualquier servidor MCP stdio como un proxy transparente:

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

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

# Generate keys + config template
npx protect-mcp init

Cómo funciona

protect-mcp evalúa cada llamada a herramienta contra una política (JSON, Cedar o PDP externo), firma la decisión como un recibo Ed25519 y registra el resultado.

Dos modos de integración:

Tres motores de políticas:

Seguimiento de enjambres

En sesiones multi-agente, protect-mcp rastrea automáticamente la topología del enjambre.

11 eventos de hook manejados:

Cada recibo incluye:

• swarm.agent_id, swarm.agent_type, swarm.team_name

• timing.tool_duration_ms, timing.hook_latency_ms

• payload_digest (hash SHA-256 para cargas útiles >1KB)

• deny_iteration (conteo de reintentos tras denegación)

• sandbox_state (habilitado/deshabilitado/no disponible)

• otel_trace_id y otel_span_id de OpenTelemetry

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
  }
}

Políticas Cedar

Las decisiones de denegación de Cedar son autoritativas — no pueden ser anuladas.

// Allow read-only tools
permit(
  principal,
  action == Action::"MCP::Tool::call",
  resource == Tool::"Read"
);

// Block destructive tools
forbid(
  principal,
  action == Action::"MCP::Tool::call",
  resource == Tool::"delete_file"
);

Cuando se deniega una herramienta, protect-mcp sugiere automáticamente la regla permit() mínima de Cedar vía GET /suggestions.

Paquetes de políticas anclados a CVE

Cada uno previene un ataque real:

Equivalentes de Cedar disponibles en policies/cedar/.

Configuración del cliente MCP

Claude Desktop

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

Cursor / VS Code

El mismo patrón: reemplace el comando del servidor con protect-mcp envolviéndolo.

Comandos CLI

Commands:
  serve             Start HTTP hook server for Claude Code (port 9377)
  init-hooks        Generate Claude Code hook config + skill + sample Cedar policy
  quickstart        Zero-config onboarding: init + demo + show receipts
  init              Generate Ed25519 keypair + config template
  demo              Start a demo server wrapped with protect-mcp
  doctor            Check your setup: keys, policies, verifier, connectivity
  trace <id>        Visualize the receipt DAG from a given receipt_id
  status            Show tool call statistics from the decision log
  digest            Generate a human-readable summary of agent activity
  receipts          Show recent persisted signed receipts
  bundle            Export an offline-verifiable audit bundle
  simulate          Dry-run a policy against recorded tool calls
  report            Generate a compliance report from an audit bundle

Options:
  --policy <path>   Policy/config JSON file
  --cedar <dir>     Cedar policy directory
  --enforce         Enable enforcement mode (default: shadow)
  --port <port>     HTTP server port (default: 9377 for serve)
  --verbose         Enable debug logging

Registros de decisiones

Cada llamada a herramienta emite JSON estructurado a stderr:

[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","reason_code":"cedar_allow","policy_digest":"a1b2c3...","mode":"enforce","hook_event":"PreToolUse","timing":{"hook_latency_ms":1},"otel_trace_id":"..."}

Cuando la firma está configurada, se guarda un recibo firmado en .protect-mcp-receipts.jsonl.

Paquetes de auditoría

npx protect-mcp bundle --output audit.json

Paquete autónomo verificable sin conexión con recibos + claves de firma. Verifique con npx @veritasacta/verify.

Base de conocimientos verificada (acta.today/wiki)

La firma de recibos de protect-mcp impulsa la primera base de conocimientos multi-modelo verificada del mundo en acta.today/wiki.

Cada Unidad de Conocimiento es producida por 4 modelos de frontera deliberando en 3 rondas adversarias, con recibos Ed25519 en cada respuesta del modelo. La lista actual:

Cada KU es verificable de forma independiente: npx @veritasacta/verify receipt.json

Integraciones del ecosistema

Estándares y PI

• IETF Internet-Drafts:

  • draft-farley-acta-signed-receipts-01 — Recibos de decisión firmados para control de acceso máquina a máquina

  • draft-farley-acta-knowledge-units-00 — Unidades de conocimiento para deliberación multi-modelo

  • Fuente: VeritasActa/drafts

• 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 agentes e identidad portátil

• Verificación: Apache-2.0 — npx @veritasacta/verify --self-test

• Integración con Microsoft AGT: PR #667 — Puente de política Cedar para Agent Governance Toolkit

Repositorios relacionados

Contribución

Las issues y pull requests son bienvenidos. Por favor, abra una issue primero para cambios significativos.

• Informes de errores: Incluya la versión de protect-mcp, la versión de Node.js y los pasos para reproducir

• Políticas Cedar: Comparta políticas reutilizables vía PR al directorio policies/cedar/

• Ejemplos de integración: Añada a ScopeBlind/examples

Licencia

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

scopeblind.com · npm · veritasacta.com · IETF Drafts