mcpsnoop v0.22.0

Wireshark para MCP. mcpsnoop se sitúa entre tu cliente de IA y tu servidor MCP y registra cada trama JSON-RPC que intercambian, sin cambiar ninguno de los dos lados. Obsérvalo en vivo en tu terminal, haz fallar CI según lo que encuentre, o envíalo a tu backend de trazabilidad como spans de OpenTelemetry.

El problema

El MCP Inspector oficial se conecta como su propio cliente, por lo que nunca ve lo que tu cliente (Cursor, Claude Code, Codex) envía realmente a tu servidor. Y cualquier cosa que espere a que llegue una petición no puede mostrar la llamada que el modelo nunca hizo, o que hizo con los argumentos equivocados. Cuando una herramienta silenciosamente no se llama, las capacidades no coinciden, o una llamada simplemente se cuelga, te quedas rebuscando entre logs y adivinando.

mcpsnoop se sitúa en la ruta de datos real en su lugar. Envuelve el comando de tu servidor con él y observa cada trama JSON-RPC en vivo, mientras tu cliente y servidor reales conversan.

En CI

Esta página es también el listado de la mcpsnoop GitHub Action, así que aquí está completa. Comprueba una sesión capturada, registra cada hallazgo como una alerta de escaneo de código, y hace fallar el trabajo según lo que hayas condicionado.

permissions:
  security-events: write
  contents: read

steps:
  - uses: kerlenton/[email protected]
    with:
      session: artifacts/session.jsonl

¿No tienes una captura a mano? Graba una sesión con tu propio cliente una vez, haz commit de ella y deja que la acción la reproduzca contra cada compilación. En CI no se ejecuta ningún modelo ni clave de API. La reproducción se verifica como cualquier captura, y el job también falla cuando el servidor empeora respecto a la grabación. Un servidor accedido mediante Streamable HTTP recibe target con su endpoint, y una grabación se reproduce sobre cualquiera de los dos transportes.

steps:
  - uses: kerlenton/[email protected]
    with:
      replay: tests/mcp/claude-code-session.jsonl
      server: node dist/index.js

Fija la versión que quieras. La más reciente está en la página de releases. Cada entrada y salida está en The GitHub Action más abajo, y cada señal por la que la comprobación puede fallar está en docs/CI.md.

OpenTelemetry

La revisión 2026-07-28 de MCP deprecia el Logging a nivel de protocolo e indica a las implementaciones que migren a stderr en stdio, o a OpenTelemetry para observabilidad estructurada. mcpsnoop cubre ambos sin tocar el cliente ni el servidor. Las líneas de stderr de un servidor stdio aparecen en el flujo junto a sus frames, y cada solicitud se convierte en un span que sigue las convenciones semánticas de OpenTelemetry para MCP.

mcpsnoop export -T otlp -o trace.json   # spans from a capture
mcpsnoop --otlp-endpoint http://localhost:4318/v1/traces -- node build/index.js   # spans as calls complete

Una llamada de herramienta llega como un span llamado tools/call search, que lleva mcp.method.name, gen_ai.tool.name y error.type, por lo que aparece en un dashboard creado para MCP en lugar de uno creado para mcpsnoop. Las métricas de herramientas en vivo para Prometheus están a una bandera de distancia. Ambas están en docs/OPENTELEMETRY.md.

Inicio rápido

Véalo de inmediato, sin nada que configurar.

mcpsnoop demo

Para usarlo de verdad, envuelve tu servidor en la configuración MCP de tu cliente.

{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

Todo lo que va después de -- es el comando que normalmente inicia tu servidor. Sustitúyelo por lo que ya uses, como python server.py, npx -y @scope/server, o un binario compilado.

En Claude Desktop no tienes que hacer esa edición a mano.

mcpsnoop wrap my-server     # route my-server through mcpsnoop
mcpsnoop unwrap my-server   # put it back

wrap encuentra claude_desktop_config.json, lo copia a claude_desktop_config.json.mcpsnoop.bak la primera vez, y reescribe únicamente la entrada de ese servidor, por lo que tu formato y todos los demás servidores quedan intactos. Dentro de la entrada reescrita, las claves vuelven en orden alfabético. unwrap restaura el archivo y elimina la copia de seguridad una vez que ningún servidor está envuelto. Reinicia Claude Desktop después de cualquiera de las dos operaciones, ya que los servidores MCP se inician una sola vez al arrancar.

Luego usa tu cliente como de costumbre y abre la interfaz de usuario.

mcpsnoop

Sin flags, sin rutas de socket, sin orden de arranque que recordar. El shim y la UI se encuentran por sí solos, y la UI rellena las sesiones pasadas desde el disco.

Para un servidor HTTP con streaming, ejecuta mcpsnoop como proxy inverso.

mcpsnoop http --target http://localhost:3000/mcp --listen :7000

El estado HTTP de cada respuesta aparece en el flujo, de modo que una respuesta que no lleva ningún mensaje JSON-RPC propio sigue siendo una trama visible en lugar de nada. Eso cubre el desafío 401, el 403 ante un Origin rechazado, el 202 que confirma una notificación y el 502 cuando el destino no se puede alcanzar en absoluto. El encabezado WWW-Authenticate de un 401 se conserva literalmente y se muestra en el inspector, ya que indica el esquema de autenticación y los metadatos del recurso a los que acudir a continuación. Filtra por estado con status:401 en la TUI, o por cualquier fallo con status:err. Un 4xx o 5xx cuenta como error, por lo que una ejecución predeterminada de mcpsnoop check falla ante él, y la llamada que respondió se lee como fallida en lugar de como una que sigue esperando.

¿No tienes un servidor propio? Pruébalo de verdad contra un servidor de pruebas publicado, impulsado por tu propio cliente. Para inspeccionar una sesión después de que ocurriera, consulta revisar sesiones pasadas desde los registros.

Instalación

npm

No se necesita una cadena de herramientas de Go. La mayoría de los servidores MCP están escritos en Node o Python, así que esta es la vía más corta.

npx mcpsnoop -- node build/index.js

El paquete npm no incluye código propio. Seis paquetes de plataforma contienen cada uno una compilación, y npm instala únicamente el que coincide con tu máquina, por lo que no hay nada que descargar durante la instalación ni nada que desbloquear en un proxy. Para conservarlo en lugar de descargarlo en cada ejecución, npm i -g mcpsnoop.

Homebrew

brew install mcpsnoop

Go