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

`wrap` encuentra `claude_desktop_config.json`, lo copia a
`claude_desktop_config.json.mcpsnoop.bak` la primera vez, y reescribe solo esa
entrada de un servidor, por lo que tu formato y todos los demás servidores se dejan intactos.
Dentro de la entrada reescrita, las claves vuelven a estar 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 lanzan una sola vez al
inicio.

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

El estado HTTP de cada respuesta aparece en el stream, de modo que una respuesta que no lleva ningún mensaje JSON-RPC propio sigue siendo un frame visible en lugar de nada: el desafío 401, el 403 en un Origin rechazado, el 202 que reconoce una notificación, y el 502 cuando el destino no se puede alcanzar en absoluto. La cabecera `WWW-Authenticate` de un 401 se conserva tal cual y se muestra en el inspector, ya que nombra el esquema de autenticación y los metadatos del recurso al 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 por defecto de `mcpsnoop check` falla en él.

¿No tienes servidor propio? [Pruébalo de verdad](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/TRY_IT.md) contra un servidor de pruebas publicado, impulsado por tu propio cliente. Para inspeccionar una sesión una vez ocurrida, consulta [revisar sesiones pasadas desde los logs](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/POST_MORTEM.md).

### Archivo de configuración

Si reutilizas las mismas opciones de shim en un proyecto, ponlas en un archivo `.mcpsnoop.toml` en el directorio de trabajo actual.```toml
label = "filesystem"
trace-file = "trace.jsonl"
redact-secrets = true
redact-key = "token,authorization"
redact-value = "sk-[A-Za-z0-9]+"
redact-path = "$.params.arguments.password"
no-trace = false

### Homebrew```bash
brew install mcpsnoop

`--older-than` es obligatorio (no hay un valor predeterminado que elimine nada) y
acepta un recuento de días como `30d` o una duración de Go como `72h`. Las líneas base de herramientas se
dejan intactas, ya que una línea base está asociada a la etiqueta del servidor y no a la sesión.

Debido a que se encuentra en la tubería real, no a un lado como el Inspector, ve
exactamente lo que tu cliente y servidor reales se dicen entre sí, sin importar en qué
esté escrito el servidor.

## Atajos de teclado

| Key | Action | | Key | Action |
|---|---|---|---|---|
| `enter` | inspeccionar / profundizar | | `/` | filtrar |
| `esc` | atrás | | `:` | comando |
| `j` / `k` | mover | | `r` | reproducir una llamada |
| `g` / `G` | inicio / fin | | `c` | capacidades |
| `ctrl-f` / `ctrl-b` | página | | `s` | resumen de herramientas |
| `p` | pausa | | `y` | copiar |
| `shift`+`<key>` | ordenar por columna | | `e` | exportar |
| `ctrl-d` | eliminar sesión | | `f` | seguir |
| `?` | ayuda | | | |

Pulsa `?` en la aplicación para ver la lista completa.

## Filtrado del flujo

Pulsa `/` en una sesión y combina tokens separados por espacios, aplicando AND. El texto plano coincide con el método, la herramienta, el id y el payload.

| Token | Filtra por | Ejemplo |
|---|---|---|
| `tool:` | nombre de la herramienta | `tool:search` |
| `method:` | método JSON-RPC | `method:tools/call` |
| `id:` | id de solicitud, y cualquier reintento que continúe con él | `id:7` |
| `task:` | id de tarea | `task:01J...` |
| `dir:` | dirección (`c2s`, `s2c`) | `dir:s2c` |
| `kind:` | tipo de trama (`req`, `resp`, `notify`, `stderr`, `invalid`) | `kind:invalid` |
| `status:` | resultado de la llamada (`ok`, `error`, `cancel`, `late`, `cancelled`, `pending`, `bad`, `warn`, `mismatch`, o un estado HTTP como `401`) | `status:error` |

Apila tokens para obtener algo más específico.```text
tool:search status:pending        # in-flight calls to one search tool
status:cancel                     # calls the client gave up on (status:cancelled is a cancelled task)
status:late                       # results that arrived after the cancellation
method:tools/call status:error    # tool calls that failed
dir:s2c kind:req                  # server-initiated requests (servers before 2026-07-28)

| Formato | Lo que obtienes |
|---|---|
| `json` | llamadas correlacionadas, recuentos por herramienta y latencia p50/p95/p99, llamadas más lentas, capacidades y tramas sin procesar |
| `html` | un archivo de navegador autónomo con búsqueda y JSON plegable |
| `text` | un volcado de texto plano legible |
| `har` | una entrada por llamada correlacionada, abrible en las herramientas de desarrollo del navegador y en cualquier otra cosa que lea HAR |
| `otlp` | JSON OTLP con un span por llamada correlacionada; el contexto de traza W3C une las trazas del llamador; de lo contrario, se usa una traza por sesión |

MCP no es HTTP, por lo que la URL, el código de estado y los tiempos de una entrada HAR son un
mapeo deliberado de cada llamada en lugar de una transcripción de la red.

Para OTLP, el `_meta.traceparent` de una solicitud proporciona el ID de traza y de span padre de esa llamada, y `_meta.tracestate` viaja junto con el span. Cuando el traceparent está ausente o no es válido, mcpsnoop mantiene la traza derivada de la sesión y no lleva ningún estado. mcpsnoop observa en lugar de participar, por lo que no añade una entrada de proveedor propia y pasa el estado del llamador sin cambios.```bash
mcpsnoop export -T html -o out.html                    # an HTML file to open in a browser
mcpsnoop export -T text server.py-48213-7f3a1c9e2b04   # a specific session, as text
mcpsnoop export -T json | jq                           # the newest session, piped to jq
mcpsnoop export -T har -o session.har                  # a HAR file to open in browser devtools
mcpsnoop export -T otlp -o trace.json                  # import into an OTLP-compatible tracing backend

Estas opciones reescriben el archivo exportado o la vista TUI en memoria, nunca el JSONL de origen. `export` rechaza una salida que nombre el mismo archivo que su entrada y escribe mediante un archivo temporal que se renombra en su lugar, de modo que una ejecución que falla deja el archivo anterior intacto.

Los `inputSchema` y `outputSchema` de una herramienta, tal como se anuncian en un resultado de `tools/list`, no se ven afectados por `--redact-key` ni `--redact-secrets`. Un nombre dentro de un esquema es una declaración de tipo más que un valor; el nombre en sí permanece en el registro en cualquier caso, y depurar el subesquema bajo una propiedad llamada `token` se llevaría consigo las comprobaciones propias de la herramienta. La exención se aplica solo a esa posición, así que un argumento que resulte llamarse `inputSchema` se depura como cualquier otro, y se detiene en `default`, `const`, `examples` y `enum`, que contienen datos en lugar de estructura. Use `--redact-path` para nombrar algo dentro de un esquema, o `--redact-value`, que coincide con texto esté donde esté, excepto en las dos palabras clave que mcpsnoop analiza, `type` y `x-mcp-header`.

El alcance de cada opción difiere, así que compruebe el resultado en lugar de asumir. Las cuatro opciones depuran cargas útiles JSON-RPC, y `--redact-key`, `--redact-path` y `--redact-secrets` solo llegan a esas. Solo `--redact-value` depura también stderr, otro texto que no sea JSON y el interior de una cadena. Un encabezado `Mcp-Param-*` se depura junto con el valor del cuerpo al que refleja; el resto de los metadatos del sobre, las etiquetas de servidor, `Mcp-Name`, `Mcp-Method` y el estado HTTP se dejan tal como se capturaron. El redactado es de mejor esfuerzo, así que use una ruta de salida separada y lea el resultado antes de compartirlo.

### Transmitir llamadas completadas a un collector OTLP

Envíe spans mientras el proxy está en ejecución apuntándolo a un endpoint OTLP/HTTP JSON de trazas. Repita `--otlp-header` para la autenticación del collector o los encabezados de tenant.```bash
mcpsnoop \
  --otlp-endpoint http://localhost:4318/v1/traces \
  --otlp-header "Authorization=Bearer $OTLP_TOKEN" \
  -- node build/index.js

mcpsnoop http \
  --target http://localhost:3000/mcp \
  --otlp-endpoint http://localhost:4318/v1/traces

El informe muestra las herramientas añadidas o eliminadas, los cambios en la descripción y en `inputSchema`, las llamadas a herramientas coincidentes cuyo estado cambió y los cambios notables de duración. Las llamadas se comparan por nombre de herramienta y argumentos, por lo que las llamadas reordenadas siguen comparándose correctamente. De forma predeterminada, los cambios de duración deben diferir al menos 100 ms y 2x; usa `--duration-threshold` y `--duration-ratio` para ajustar esos límites.

Pasa `--exit-code` para condicionar el CI a las regresiones: sale con código distinto de cero cuando la sesión posterior elimina una herramienta, cambia la descripción, el título, el esquema de entrada, el esquema de salida o las anotaciones de una herramienta, tiene una llamada cuyo estado empeoró o se ralentiza. Las mejoras (herramientas añadidas, llamadas corregidas, aceleraciones) siguen saliendo con cero, y también lo hace un cambio de icono, que altera el aspecto de una herramienta sin cambiar lo que hace.

## Comprobación de sesiones en CI

Condiciona una ejecución de agente grabada a errores, corrupción del flujo, advertencias de protocolo, discrepancias en el encabezado de enrutamiento, llamadas que nunca recibieron respuesta, tramas descartadas que dejan la captura incompleta, deriva en la definición de herramientas o el uso de características de protocolo obsoletas.```bash
mcpsnoop check [--format text|junit|sarif] [--fail-on error,invalid,warn,mismatch,pending,late-result,drift,deprecated,incomplete,schema] [session-id|log.jsonl|-]

El recuento de fotogramas perdidos también viaja con los artefactos, por lo que una captura que
se subestima a sí misma lo indica dondequiera que se abra: `missing_frames` en la exportación
JSON, `log.comment` en HAR, y el atributo de recurso `mcpsnoop.session.missing_frames`
en OTLP.```bash
mcpsnoop check build-agent
mcpsnoop check --fail-on error,invalid artifacts/session.jsonl
mcpsnoop check --fail-on mismatch gateway-run.jsonl

### Repórtalo donde la CI ya busca

`--format junit` escribe un `<testcase>` por señal y sesión, y sus fallos
siguen la misma selección de `--fail-on` que la salida de texto.```yaml
- name: Check captured MCP session
  run: |
    mkdir -p test-results
    mcpsnoop check --format junit artifacts/session.jsonl > test-results/mcpsnoop.xml
- name: Upload mcpsnoop JUnit report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: mcpsnoop-junit
    path: test-results/mcpsnoop.xml

### Detectar un encabezado de enrutamiento que discrepa con el cuerpo

En el transporte streamable-HTTP, una puerta de enlace enruta según `Mcp-Method` y `Mcp-Name`
mientras el servidor lee el cuerpo, por lo que un encabezado que discrepa del cuerpo significa
que ambos están viendo dos solicitudes distintas. La señal `mismatch` cubre ese caso,
un encabezado que viaja en un lote al que no puede dirigirse, y un encabezado obligatorio ausente
por completo.

En la revisión 2026-07-28, un encabezado de enrutamiento faltante es un fallo de validación, y un servidor
conforme rechaza la solicitud con `400` y `-32020`. mcpsnoop solo lo señala una vez
que se sabe que la sesión habla esa revisión o una posterior, ya que las revisiones anteriores
no definen estos encabezados en absoluto y omitirlos allí es correcto. El propio rechazo
`-32020` de un servidor cuenta como la misma señal.

Un nombre o URI de recurso que no quepa en un valor de campo HTTP viaja en Base64 dentro
de un centinela `=?base64?…?=`, que se decodifica antes de la comparación, por lo que un cliente
que codifica correctamente nunca se marca.

En las solicitudes HTTP `tools/call`, mcpsnoop también muestra cada cabecera `Mcp-Param-{Name}`
y, cuando se conoce la definición de herramienta anunciada coincidente, la compara con la
ruta de argumento anotada. Las propiedades anidadas, el centinela Base64, los booleanos y los
enteros seguros numéricamente equivalentes se manejan sin falsos positivos de comparación de
cadenas. Las cabeceras de parámetros desconocidas y las sesiones sin una definición de herramienta
coincidente permanecen solo como observación. La redacción basada en claves y valores se aplica a los
valores de cabecera de parámetros capturados antes de que lleguen a un sumidero, y un valor que mcpsnoop
haya depurado por sí mismo nunca se notifica como discrepancia.

### Detectar deriva en la definición de herramientas

La primera `tools/list` completa observada para una etiqueta de servidor se convierte en su línea base
de confianza. Las sesiones posteriores comparan esa línea base campo por campo: la descripción,
el título, los esquemas de entrada y salida, las anotaciones y los iconos, además de las herramientas
añadidas o eliminadas. Las anotaciones son lo que más importa, ya que una herramienta aprobada
con `readOnlyHint` que luego se declara destructiva es el tirón de alfombra para el que existe esta
comprobación, y la especificación indica a los clientes que traten las anotaciones como no confiables.
El título y los iconos se rastrean porque son lo que ve el usuario, y la especificación coloca el
`title` de una herramienta por encima de `annotations.title` y de su nombre. La tabla de sesiones
y el resumen de herramientas marcan la deriva sin bloquear ni modificar el tráfico MCP.

Las anotaciones se comparan mediante sus valores predeterminados en la especificación, por lo que un servidor que empieza
a explicitar una pista en la que ya se apoyaba no se notifica. Una línea base
registrada antes de que mcpsnoop rastreara un campo sigue funcionando para los campos que sí
registra e indica cuáles no puede responder; vuelve a registrarla con
`mcpsnoop baseline --accept` una vez que confíes en las definiciones actuales.

Cambiar lo que registra la redacción cambia lo que compara la deriva. Una línea base tomada
sin `--redact-value` y luego verificada contra una captura tomada con esa opción
notifica los campos depurados como cambiados, lo cual es correcto, ya que la definición registrada
realmente cambió. Vuelve a registrarla con `--accept` después de cambiar la configuración de redacción.

Usa una `--label` estable y única para cada servidor cuyo nombre de comando u host de destino
colisionaría de otro modo. Las líneas base se almacenan en el directorio de estado normal de mcpsnoop,
por lo que se aplican `MCPSNOOP_HOME` y `XDG_STATE_HOME`.```bash
mcpsnoop check --fail-on drift session.jsonl
mcpsnoop baseline session.jsonl
mcpsnoop baseline --accept session.jsonl  # trust a legitimate definition change
mcpsnoop baseline --reset session.jsonl   # trust the next complete tools/list

`drift` es opt-in para `check`; el filtro predeterminado `error,invalid,warn` no cambia.

### Marcar características de protocolo obsoletas

La revisión del 2026-07-28 marca como obsoletos Roots, Sampling y Logging. Siguen funcionando
durante al menos un año, por lo que mcpsnoop los marca en lugar de tratarlos como errores.
El stream, el inspector de capacidades y la exportación los marcan todos, y cada marcador
nombra el reemplazo.

Dos de los tres ahora solo son accesibles mediante una solicitud multi round-trip, donde
el nombre del método se encuentra dentro del mapa `inputRequests` del servidor en lugar de en la
trama misma. Esos también se marcan, de modo que un servidor que haya migrado al nuevo patrón
no deje de informar en silencio.```bash
mcpsnoop check --fail-on deprecated session.jsonl

La columna lleva el color de advertencia y nunca el rojo de la columna ERR, y
mcpsnoop sigue sin cambiar nada del tráfico que reenvía.

No se resuelve ni se obtiene nada. Un `$ref` externo se reconoce solo por su
forma, y el esquema al que apunta nunca se lee.

### Comprueba cuánto te cuesta el servidor en contexto

Las definiciones de herramientas entran en el contexto del modelo en cada
conversación, y los resultados de las herramientas en cada llamada. El resumen
de herramientas (`s`) mide ambos a partir de la sesión que realmente
capturaste.

La línea `definitions` es el coste fijo: lo que pesa el `tools/list` de este
servidor antes de que se haga una sola llamada. La columna `DEF` lo desglosa
por herramienta y `RESULT` es lo que han costado las respuestas de cada
herramienta hasta ahora. La tabla se mantiene ordenada por errores y latencia,
así que revisa `DEF` para encontrar las definiciones caras; la exportación las
lista de mayor a menor peso. Una línea bajo la tabla indica el resultado más
pesado, que un total oculta.

Las cifras de definiciones son el JSON sin los espacios en blanco
insignificantes, de modo que un servidor que formatea su `tools/list` de forma
legible no se considera más caro que uno que no lo hace, y el mismo servidor
mide lo mismo entre capturas. `RESULT` son los bytes tal y como llegaron: un
resultado es una carga de una sola vez, no un contrato que merezca la pena
normalizar.```bash
mcpsnoop export -T json | jq '.summary.definitions'

El socket reside en el directorio de estado del remoto, resuelto como `MCPSNOOP_HOME`,
de lo contrario `XDG_STATE_HOME/mcpsnoop`, de lo contrario `~/.local/state/mcpsnoop`. Por defecto, mcpsnoop
asume el home de Linux `/home/<user>` a partir de tu `user@host` e imprime un recordatorio
en stderr cada vez que recurre a esa suposición. Si el remoto se resuelve en otra ubicación,
indica la única pieza no predeterminada.```bash
# a non-Linux or custom home, macOS is /Users/<user> and root is /root
mcpsnoop remote --remote-home /Users/remote-user remote-user@remote-host

# an explicit MCPSNOOP_HOME on the remote
mcpsnoop remote --remote-mcpsnoop-home /srv/mcpsnoop remote-user@remote-host

# an explicit XDG_STATE_HOME on the remote
mcpsnoop remote --remote-xdg-state-home /var/lib/state remote-user@remote-host

Para tener una copia local, copia los logs a tu directorio sessions con scp y ejecuta la TUI como de costumbre.```bash
# copy the remote logs into your local sessions directory
mkdir -p ~/.local/state/mcpsnoop/sessions
scp remote-user@remote-host:'~/.local/state/mcpsnoop/sessions/*.jsonl' \
  ~/.local/state/mcpsnoop/sessions/

# open the TUI, it backfills the copied sessions
mcpsnoop

Para flujos de trabajo remotos, use túneles SSH o transferencia de archivos por SSH para que la autenticación de transporte, el cifrado, la verificación del host, la rotación de claves y la política de auditoría permanezcan en su configuración SSH existente.

## Contribuciones

Las incidencias y las solicitudes de extracción son bienvenidas. Consulte [CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/HEAD/CONTRIBUTING.md) para
obtener los detalles.

## Licencia

[MIT](https://github.com/kerlenton/mcpsnoop/blob/HEAD/LICENSE)