kerlenton/mcpsnoopWireshark para MCP. Un proxy transparente entre tu cliente de IA y el servidor MCP. Observa cada llamada en vivo en tu terminal, haz fallar CI según lo que encuentre, exporta spans de OpenTelemetry.
<p align="center"> <img src="https://assets.kitploit.com/production/public/readmes/9109/91d664ea266713affb29238906792777021b43fa6627b13f46382f48ad340a61.png" alt="mcpsnoop" width="440"> </p> **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. [](https://github.com/kerlenton/mcpsnoop/actions/workflows/ci.yml) [](https://pkg.go.dev/github.com/kerlenton/mcpsnoop) [](LICENSE) [](https://github.com/marketplace/actions/mcpsnoop) <p align="center"> <img src="https://assets.kitploit.com/production/public/readmes/9109/30466d77be15250e4bab6639e48a4cd5b0d44cd96e48606b60c6bacb67c15c3d.gif" alt="mcpsnoop demo"> </p> ## El problema El [MCP Inspector](https://github.com/modelcontextprotocol/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](https://github.com/marketplace/actions/mcpsnoop), 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. ```yaml 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. ```yaml 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](https://github.com/kerlenton/mcpsnoop/releases). Cada entrada y salida está en [The GitHub Action](#the-github-action) más abajo, y cada señal por la que la comprobación puede fallar está en [docs/CI.md](https://github.com/kerlenton/mcpsnoop/blob/main/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](https://github.com/open-telemetry/semantic-conventions-genai/tree/main/model/mcp). ```bash 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](https://github.com/kerlenton/mcpsnoop/blob/main/docs/OPENTELEMETRY.md). ## Inicio rápido Véalo de inmediato, sin nada que configurar. ```bash mcpsnoop demo ``` Para usarlo de verdad, envuelve tu servidor en la configuración MCP de tu cliente. ```json { "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. ```bash 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. ```bash 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. ```bash 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](https://github.com/kerlenton/mcpsnoop/blob/main/docs/TRY_IT.md) 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](https://github.com/kerlenton/mcpsnoop/blob/main/docs/POST_MORTEM.md). ## 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. ```bash 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 ```bash brew install mcpsnoop ``` ### Go ```bash go install github.com/kerlenton/mcpsnoop/cmd/mcpsnoop@latest ``` Los binarios precompilados para cada plataforma están en la página de [Releases](https://github.com/kerlenton/mcpsnoop/releases). mcpsnoop incluye completions para bash, zsh, fish y PowerShell. Ejecuta `mcpsnoop completion <shell> --help` para ver los pasos de configuración, que cubren la habilitación de completion y la ruta de instalación para tu sistema operativo. ## Comandos | Comando | Qué hace | |---|---| | `mcpsnoop -- <server>` | envuelve un servidor stdio como un shim transparente | | `mcpsnoop` | abre la TUI en vivo | | `mcpsnoop --metrics-listen <addr>` | ejecuta un hub sin interfaz y expone métricas de Prometheus en vivo | | `mcpsnoop http --target <url>` | actúa como proxy de un servidor streamable-HTTP | | `mcpsnoop export` | renderiza una sesión a json, html, text, har u otlp | | `mcpsnoop check` | hace fallar la CI ante errores, frames inválidos, advertencias como un resultado de herramienta que incumple su propio outputSchema, desajustes de enrutamiento, llamadas colgadas, resultados tardíos, llamadas que pueden haberse ejecutado dos veces, deriva de herramientas, anotaciones que se relajaron o no dicen nada, o un presupuesto de latencia | | `mcpsnoop baseline` | inspecciona, acepta o restablece definiciones de herramientas de confianza | | `mcpsnoop diff` | compara herramientas y llamadas entre dos sesiones capturadas | | `mcpsnoop open` | abre una sesión guardada en la TUI | | `mcpsnoop mock <session>` | sirve una sesión capturada de vuelta como un servidor MCP stdio | | `mcpsnoop replay <session> -- <server>` | impulsa un servidor, por stdio o Streamable HTTP, con el lado cliente de una sesión grabada, y compara el resultado con la grabación | | `mcpsnoop inventory` | lista cada servidor que se ha ejecutado a través de mcpsnoop en esta máquina | | `mcpsnoop stats` | consolida cada captura almacenada en una fila por servidor y herramienta | | `mcpsnoop clients` | muestra qué hizo realmente cada cliente MCP en la conexión, por nombre y versión | | `mcpsnoop prune` | elimina los registros de sesión guardados anteriores a una fecha de corte | | `mcpsnoop wrap <server>` | enruta uno de los servidores de Claude Desktop a través de mcpsnoop | | `mcpsnoop unwrap <server>` | restaura la entrada de ese servidor a como estaba | | `mcpsnoop remote <user@host>` | imprime el comando del túnel SSH | | `mcpsnoop demo` | reproduce una sesión guionizada | Ejecuta `mcpsnoop help` para ver la lista completa, o `mcpsnoop help <command>` para ver las opciones de un comando. ## Cómo se compara Cada una de estas herramientas responde a una pregunta distinta, y el lugar donde se sitúa una herramienta determina qué preguntas puede responder. | Herramienta | Dónde se sitúa | Para qué sirve | |---|---|---| | [MCP Inspector](https://github.com/modelcontextprotocol/inspector) | su propio cliente, conectado a tu servidor | probar un servidor a mano, en un navegador o desde una CLI scriptable | | [Snyk Agent Scan](https://github.com/snyk/agent-scan) | su propio cliente, que lanza o se conecta a los servidores de tus configuraciones para leer sus herramientas | escanear agentes, servidores MCP y skills en tu máquina en busca de prompt injection y vulnerabilidades | | [MCP Observatory](https://github.com/KryptosAI/mcp-observatory) | su propio cliente, que lanza tu servidor para probarlo, grabarlo y verificarlo | pruebas de seguridad y de regresión en CI, con simulación de ataques, deriva de esquemas, y grabación, reproducción y verificación | | [mcprec](https://github.com/erphq/mcprec) | en la conexión, entre cliente y servidor | grabar una sesión una vez y reproducirla como fixture de prueba sin la red | | mcpsnoop | en la conexión, entre cliente y servidor | observar lo que dicen realmente tu cliente y tu servidor, reproducir la sesión de un cliente real contra cada build, hacer fallar la CI por ello y exportarlo como OpenTelemetry | Una herramienta que es su propio cliente ve las llamadas que hace ella, no las que hace tu cliente, así que no puede mostrar la llamada que tu modelo nunca hizo o que hizo con los argumentos equivocados. Un escáner lee una definición antes de que confíes en ella. mcpsnoop observa lo que ocurre una vez que ya confías, incluido si la definición cambia después. ## Cómo funciona <p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/architecture-dark.svg"> <img alt="mcpsnoop se sitúa en la tubería entre tu cliente de IA y tus servidores MCP, copiando cada frame JSON-RPC a una interfaz de terminal en vivo" src="https://raw.githubusercontent.com/kerlenton/mcpsnoop/HEAD/assets/architecture-light.svg" width="760"> </picture> </p> mcpsnoop es dos roles en un solo binario. `mcpsnoop -- <server>` es el shim transparente que tu cliente lanza, reenviando bytes literalmente mientras envía una copia de cada trama al hub. `mcpsnoop` sin argumentos es ese hub y su TUI en vivo. Se emparejan a través de un socket conocido y registros en disco, por lo que ninguno tiene que iniciarse primero. Debido a que se sitúa en la tubería real, no apartado como el Inspector, ve exactamente lo que tu cliente y servidor reales se dicen entre sí, sin importar en qué esté escrito el servidor. Lo que limita su memoria y su disco está en [docs/HOW_IT_WORKS.md](https://github.com/kerlenton/mcpsnoop/blob/main/docs/HOW_IT_WORKS.md). ## La GitHub Action Todo lo siguiente es lo que la action hace por ti. Instala mcpsnoop, verifica la captura, registra los hallazgos en la pestaña Security y hace fallar el job según lo que hayas configurado como condición. ```yaml permissions: security-events: write contents: read steps: - uses: kerlenton/[email protected] with: session: artifacts/session.jsonl ``` Fija una release, la que quieras. La más reciente está en la [página de releases](https://github.com/kerlenton/mcpsnoop/releases). No hay una `v1` flotante, deliberadamente. La release fijada es también el binario que instala la action, así que ambas nunca pueden discrepar y no hay una versión por defecto que quede obsoleta. | Entrada | | |---|---| | `session` | la captura `.jsonl` que se va a comprobar, o un directorio de ellas, relativo a la raíz del repositorio. Indica esto o `replay` | | `replay` | una grabación confirmada en el repositorio para reproducir contra `server` o `target`, cuya captura se comprueba después y que también hace fallar el job ante una regresión | | `server` | el comando que inicia el servidor bajo prueba, entrecomillado como en una línea de comandos. Obligatorio con `replay` para un servidor stdio. Con `target` inicia primero un servidor HTTP, y puede omitirse cuando ya hay uno en ejecución | | `target` | el endpoint Streamable HTTP contra el que reproducir, como `http://localhost:3000/mcp`. Una credencial va en `replay-args` como `--header`, y el log del paso muestra su valor oculto | | `replay-args` | cualquier otro flag de `replay`, como `--read-only`. Se rechaza `--out`, ya que la action decide dónde va la captura | | `fail-on` | igual que `--fail-on`, con el valor por defecto del CLI | | `args` | cualquier otro flag de `check`, entrecomillado como en una línea de comandos. Se rechaza `--format`, ya que la action lee el informe | | `upload-sarif` | envía el informe al code scanning. `true` | | `category` | el espacio de nombres del code scanning. `mcpsnoop`. Varíalo por cada rama de una matriz, o las ramas se sobrescribirán entre sí | | `fail-on-findings` | hace fallar el job ante un hallazgo. `true`. Ponlo en `false` para registrar las alertas y dejar que decida la comprobación requerida del code scanning | | `version` | qué mcpsnoop instalar. Por defecto, la release que fijaste | | `install` | `false` cuando mcpsnoop ya está en PATH, que es la forma de entrar en una plataforma para la que no se compila ninguna release | Las salidas son `outcome`, `sarif`, `exit-code` y `capture`, la ruta de la captura que se comprobó, que con `replay` es la que escribió la reproducción y merece la pena conservar como artefacto. `outcome` es `passed`, `findings` o `error`, y el tercero merece tratarse por separado. Significa que no se comprobó nada, lo cual no es lo mismo que no encontrar nada. **Una ejecución que no pudo comprobar hace fallar el job diga lo que diga `fail-on-findings`**, porque un pipeline que se pone en verde sin haber verificado nada es peor que uno que falla. El job necesita `security-events: write`, o la subida responde 403. Pon `upload-sarif: false` en un repositorio sin code scanning. Ejecutar la misma comprobación sin la action, las señales por las que puede fallar y los códigos de salida están en [docs/CI.md](https://github.com/kerlenton/mcpsnoop/blob/main/docs/CI.md). ## Documentación | Página | Qué contiene | |---|---| | [Checking sessions in CI](https://github.com/kerlenton/mcpsnoop/blob/main/docs/CI.md) | reproducir una grabación contra cada build, cada señal por la que `check` puede fallar, códigos de salida, aserciones, informes JUnit y SARIF, comparar dos sesiones y configurarlo sin la action | | [OpenTelemetry and Prometheus](https://github.com/kerlenton/mcpsnoop/blob/main/docs/OPENTELEMETRY.md) | los spans y lo que transportan, transmitirlos en streaming a un collector y métricas de herramientas en vivo | | [Using mcpsnoop](https://github.com/kerlenton/mcpsnoop/blob/main/docs/USING.md) | claves, filtrado, formatos de exportación, replay, qué pidió un servidor a tu usuario, coste en contexto, estadísticas entre capturas, qué envía realmente cada cliente, el inventario de servidores, máquinas remotas y el archivo de configuración | | [Redaction](https://github.com/kerlenton/mcpsnoop/blob/main/docs/REDACTION.md) | limpiar secretos, durante la captura o de una captura que ya tienes | | [How it works](https://github.com/kerlenton/mcpsnoop/blob/main/docs/HOW_IT_WORKS.md) | límites de memoria, el límite del historial y la poda de logs antiguos | | [Try it for real](https://github.com/kerlenton/mcpsnoop/blob/main/docs/TRY_IT.md) | un servidor de pruebas publicado, manejado por tu propio cliente | | [Review past sessions](https://github.com/kerlenton/mcpsnoop/blob/main/docs/POST_MORTEM.md) | dónde viven los logs de sesión y cómo abrir uno a posteriori | | [The capture format](https://github.com/kerlenton/mcpsnoop/blob/main/docs/CAPTURE_FORMAT.md) | qué contiene cada línea de un log de sesión y qué nunca cambiará al respecto, con un JSON Schema para herramientas que leen capturas | ## Seguridad mcpsnoop ejecuta el comando de servidor que envuelves, así que envuelve solo servidores en los que confíes, y ejecuta los no confiables en un contenedor. Nunca ejecuta nada que no hayas puesto en la configuración de tu cliente. Para flujos de trabajo remotos, utilice túnel SSH o transferencia de archivos SSH para que la autenticación de transporte, el cifrado, la verificación de host, la rotación de claves y la política de auditoría permanezcan en su configuración SSH existente. ### Qué puede hacer una captura a tu terminal Una captura son datos que eligió la otra parte. Las tramas y las líneas de stderr pueden contener secuencias de escape de terminal, y una terminal actúa sobre lo que se le entrega, lo que abarca desde una pantalla distorsionada hasta OSC 52 escribiendo en el portapapeles de tu sistema. mcpsnoop conserva solo las secuencias de color que genera él mismo y descarta cualquier otro escape antes de que una trama llegue a tu terminal. Las celdas de la tabla citan los caracteres de control para que puedas ver que estaban ahí, el inspector los muestra con todo detalle, y la copia al portapapeles lleva la forma escapada, de modo que nada se te oculta y nada se ejecuta. ### Qué contiene una captura Las tramas capturadas pueden incluir prompts, argumentos de herramientas, credenciales y resultados de herramientas. [docs/REDACTION.md](https://github.com/kerlenton/mcpsnoop/blob/main/docs/REDACTION.md) cubre cómo depurarlos, ya sea durante la captura o después. Para reportar una vulnerabilidad, consulte [SECURITY.md](https://github.com/kerlenton/mcpsnoop/blob/main/SECURITY.md). ## Contribuir Las issues y pull requests son bienvenidas. Consulte [CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/main/CONTRIBUTING.md) para más detalles. ## Licencia [MIT](https://github.com/kerlenton/mcpsnoop/blob/main/LICENSE)
