mcp-audit

Tu agente de IA hizo 847 llamadas a herramientas ayer. ¿Puedes verificar lo que hizo?

Registro de auditoría a prueba de manipulaciones para llamadas a herramientas de agentes de IA.

Configuración (10 segundos)

Antes:

{
  "command": "npx",
  "args": ["@modelcontextprotocol/server-github"]
}

Después:

{
  "command": "npx",
  "args": ["mcp-audit", "wrap", "--", "npx", "@modelcontextprotocol/server-github"]
}

Cada llamada a herramienta ahora está firmada criptográficamente y encadenada por hash. Nada más cambia. El servidor MCP funciona exactamente igual que antes.

Related MCP server: DCL Evaluator

Qué hace

$ mcp-audit tail

✓ 14:32:01 github/create_pr                 234ms  bf7a2f62
✓ 14:32:03 github/list_issues                89ms  a1c4e890
✗ 14:32:05 fs/delete_file                    12ms  c3d9f012
✓ 14:32:08 github/merge_pr                  456ms  e5f6a7b8

Cada entrada está firmada con HMAC-SHA256 y encadenada al registro anterior. Si manipulas cualquier entrada, la verificación falla. Si eliminas una entrada, la cadena se rompe.

Verificar integridad

$ mcp-audit verify ~/.mcp-audit/audit.jsonl

Results:
  Total records: 847
  Valid: 847
  Invalid: 0

All records verified successfully.

Cómo funciona

┌────────────┐       ┌───────────┐       ┌────────────┐
│ MCP Client │──────▶│ mcp-audit │──────▶│ MCP Server │
│ (Claude,   │◀──────│   wrap    │◀──────│ (any)      │
│  Cursor)   │       └─────┬─────┘       └────────────┘
└────────────┘             │
                           ▼
                    ~/.mcp-audit/
                    audit.jsonl

El comando wrap inicia tu servidor MCP como un proceso hijo y se sitúa entre el cliente y el servidor en stdio. Reenvía TODOS los mensajes de forma transparente. Solo las respuestas de tools/call se firman y registran. Todo lo demás pasa sin cambios.

En la primera ejecución, se genera automáticamente una clave de firma en ~/.mcp-audit/key.hex. No se necesita configuración.

Formato de registro de auditoría

{
  "id": "bf7a2f62-4d0f-4cce-afd2-cbfbf7bca2a5",
  "timestamp": "2026-08-16T14:32:01.000Z",
  "method": "tools/call",
  "toolName": "github/create_pr",
  "args": {"title": "Fix bug", "body": "..."},
  "durationMs": 234,
  "success": true,
  "previousHash": "8a3f2b...",
  "attestation": "7c4d9e..."
}

La attestation es una firma HMAC-SHA256 sobre los campos canónicos del registro. El previousHash es el SHA-256 del registro anterior. Juntos detectan manipulación, orden y completitud.

Uso con Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["mcp-audit", "wrap", "--", "npx", "@modelcontextprotocol/server-github"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["mcp-audit", "wrap", "--", "npx", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

Uso con Claude Code

.claude/hooks/mcp-servers.json o directamente en el comando de tu servidor MCP — prefija con mcp-audit wrap --.

CLI

mcp-audit wrap -- <cmd> [args]    # Wrap any MCP server
mcp-audit tail                    # Live stream of tool calls
mcp-audit verify <log>            # Verify chain integrity
mcp-audit serve [config]          # Full gateway (policy + OTel)
mcp-audit keygen [dir]            # Generate Ed25519 key pair

Modo gateway completo

Para equipos que también necesitan control de acceso, limitación de velocidad y enrutamiento multi-servidor:

mcp-audit serve gateway.config.json

El gateway completo añade:

• Motor de políticas (ACL basadas en glob, límites de velocidad por principal)

• Espaciado de nombres de herramientas entre múltiples servidores MCP ascendentes

• Exportación de trazas y métricas OpenTelemetry

• Gestión de salud de servidores ascendentes con reconexión automática

• Firmas Ed25519 (más fuertes que HMAC, verificación portátil)

Consulta configuración del gateway para el esquema completo.

Instalación

npm install -g @mcp-audit-gateway/core

Esto instala el CLI mcp-audit globalmente. O úsalo sin instalar:

npx @mcp-audit-gateway/core wrap -- <your mcp server command>

Capa de atestación

El subsistema de firma y verificación va más allá del HMAC por registro. Proporciona evidencia de manipulación a través de rotación de registros, recuperación de fallos y cadenas de múltiples archivos.

Los registros de punto de control permiten que un consumidor detecte truncamiento de cola guardando un solo hash externamente. La cadena continúa a través de rotaciones de archivo (sin reinicios silenciosos). Los reinicios forzados emiten registros chain_break firmados en lugar de comenzar de nuevo silenciosamente.

La forma canónica está etiquetada por tipo y es inyectiva, evita el problema de formato de flotantes de JCS al rechazar números no seguros por completo, y ha demostrado paridad entre lenguajes mediante 46 vectores de conformidad (JS + Python). Consulta SECURITY-DESIGN.md para la especificación completa y el modelo de amenazas.

Pruebas diferenciales entre SDK

MCP tiene 10 SDK oficiales y no hay pruebas de conformidad entre SDK. Construimos un arnés diferencial estilo Wycheproof que ejecuta 40 pruebas de casos límite de serialización en los 10 SDK e informa dónde discrepan.

Resultados: 26 divergencias a nivel de cable en 8 serializadores distintos. Seis representaciones diferentes de 1e20. Tres algoritmos de ordenación de claves incompatibles. TypeScript pierde silenciosamente precisión de enteros en 2^53+1. C# escapa caracteres HTML que ningún otro SDK escapa. El SDK de Python produce bytes diferentes entre versiones de pydantic-core para la misma ruta de código.

./test/vectors/cross-sdk-diff.sh              # full matrix (stdlib + SDK)
./test/vectors/cross-sdk-diff.sh --layer sdk  # SDK-wire-level only
./test/vectors/cross-sdk-diff.sh --json       # structured output

La canonicalización del gateway de auditoría fue diseñada para ser inmune a las 26 clases de divergencia: solo enteros seguros, orden de campos explícito, rechazo de sustitutos. Consulta SDK-AUDIT.md para la tabla completa de divergencias y la metodología.

Conformidad

Esta implementación satisface las siguientes propiedades (verificadas mediante vectores de conformidad entre lenguajes y pruebas unitarias):

• Forma canónica inyectiva (sin colisiones de resumen entre tipos)

• Equivalencia de ordenación entre lenguajes (orden de unidades de código UTF-16)

• Rechazo de sustitutos no emparejados

• Continuidad de la cadena de hash a través de rotación de registros

• Detección de estado plantado al inicio

• Sin falsos positivos después de una ruptura de cadena legítima

• Cierre seguro ante entrada corrupta o demasiado grande

• Monotonicidad segmentada en los límites de chain_break

• Completitud anclada al consumidor mediante registros de punto de control

• Inicialización con memoria limitada (tope de 1MB)

Conformidad APS action-ref-v1: 51/51 vectores aprobados (recomputación JCS + comparación de resumen con cierre seguro).

Pruebas

npm test                                    # unit tests
node test/vectors/verify-checkpoint.mjs     # JS conformance vectors
python3 test/vectors/verify-checkpoint.py   # Python conformance vectors
node test/vectors/aps-action-ref-v1.mjs     # 51 APS vectors
./test/vectors/cross-sdk-diff.sh            # 10-SDK differential test

Licencia

MIT

Los fixtures de conformidad APS (test/vectors/aps-action-ref-v1-vectors.json) están adaptados de fuentes upstream con licencia Apache-2.0. Consulta test/vectors/SOURCE.md para la procedencia y los términos.