Para usar de verdade, envolva o seu servidor na configuração MCP do seu cliente.```json
{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

`wrap` localiza o `claude_desktop_config.json`, copia-o para
`claude_desktop_config.json.mcpsnoop.bak` na primeira vez e reescreve apenas
a entrada desse único servidor, para que a sua formatação e todos os outros
servidores sejam mantidos intactos. Dentro da entrada reescrita, as chaves
voltam à ordem alfabética. `unwrap` restaura o arquivo e remove o backup
assim que nenhum servidor estiver mais envolvido. Reinicie o Claude Desktop
após qualquer um dos dois, pois os servidores MCP são iniciados apenas uma
vez, na inicialização.

Em seguida, use o seu cliente como de costume e abra a interface.```bash
mcpsnoop

O status HTTP de cada resposta aparece no fluxo, então uma resposta que não traz
nenhuma mensagem JSON-RPC própria ainda é um frame visível em vez de nada: o
desafio 401, o 403 em uma Origin rejeitada, o 202 que confirma uma notificação
e o 502 quando o destino não pode ser alcançado de forma alguma. O cabeçalho
`WWW-Authenticate` de um 401 é mantido na íntegra e exibido no inspetor, pois
nomeia o esquema de autenticação e os metadados do recurso para onde ir em
seguida. Filtre por status com `status:401` no TUI, ou por qualquer falha com
`status:err`. Um 4xx ou 5xx conta como erro, então uma execução padrão de
`mcpsnoop check` falha nele.

Sem servidor próprio? [Experimente de verdade](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/TRY_IT.md) contra um
servidor de teste publicado, usando seu próprio cliente. Para inspecionar uma
sessão depois que ela aconteceu, veja [revisar sessões passadas a partir dos
logs](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/POST_MORTEM.md).

### Arquivo de configuração

Se você reutilizar os mesmos flags de shim em um projeto, coloque-os em um
arquivo `.mcpsnoop.toml` no diretório de trabalho atual.```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` é obrigatório (não há padrão que excluiria qualquer coisa) e
aceita uma contagem de dias como `30d` ou uma duração Go como `72h`. As
linhas de base das ferramentas são deixadas intactas, pois uma linha de base é identificada pelo rótulo do servidor, e não pela sessão.

Como ele fica no pipe real, e não à margem como o Inspector, ele
vê exatamente o que o seu cliente e servidor reais dizem um ao outro, seja qual for a
linguagem em que o servidor foi escrito.

## Atalhos de teclado

| Tecla | Ação | | Tecla | Ação |
|---|---|---|---|---|
| `enter` | inspecionar / aprofundar | | `/` | filtrar |
| `esc` | voltar | | `:` | comando |
| `j` / `k` | mover | | `r` | repetir chamada |
| `g` / `G` | topo / fundo | | `c` | capacidades |
| `ctrl-f` / `ctrl-b` | página | | `s` | resumo da ferramenta |
| `p` | pausar | | `y` | copiar |
| `shift`+`<key>` | ordenar por coluna | | `e` | exportar |
| `ctrl-d` | excluir sessão | | `f` | seguir |
| `?` | ajuda | | | |

Pressione `?` no aplicativo para a lista completa.

## Filtrando o fluxo

Pressione `/` em uma sessão e combine tokens separados por espaços, com E lógico. Texto
simples corresponde ao método, à ferramenta, ao id e ao payload.

| Token | Filtra por | Exemplo |
|---|---|---|
| `tool:` | nome da ferramenta | `tool:search` |
| `method:` | método JSON-RPC | `method:tools/call` |
| `id:` | id da solicitação e qualquer nova tentativa que o continue | `id:7` |
| `task:` | id da tarefa | `task:01J...` |
| `dir:` | direção (`c2s`, `s2c`) | `dir:s2c` |
| `kind:` | tipo de frame (`req`, `resp`, `notify`, `stderr`, `invalid`) | `kind:invalid` |
| `status:` | resultado da chamada (`ok`, `error`, `cancel`, `late`, `cancelled`, `pending`, `bad`, `warn`, `mismatch` ou um status HTTP como `401`) | `status:error` |

Empilhe tokens para ser 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 | O que você obtém |
|---|---|
| `json` | chamadas correlacionadas, contagens por ferramenta e latência p50/p95/p99, chamadas mais lentas, capacidades e quadros brutos |
| `html` | um arquivo de navegador autocontido com pesquisa e JSON recolhível |
| `text` | um despejo de texto simples e organizado |
| `har` | uma entrada por chamada correlacionada, abrível nas ferramentas de desenvolvedor do navegador e em qualquer outra ferramenta que leia HAR |
| `otlp` | JSON OTLP com um span por chamada correlacionada; o contexto de rastreamento W3C une os rastreamentos do chamador; caso contrário, um rastreamento é usado por sessão |

MCP não é HTTP, portanto a URL, o código de status e os tempos de uma entrada HAR são um
mapeamento proposital de cada chamada, e não uma transcrição de rede.

Para OTLP, o `_meta.traceparent` de uma solicitação fornece o rastreamento e os IDs
de span pai daquela chamada, e `_meta.tracestate` acompanha o span. Quando o traceparent está
ausente ou inválido, o mcpsnoop mantém o rastreamento derivado da sessão e não carrega estado.
O mcpsnoop observa em vez de participar, portanto não adiciona uma entrada de fornecedor própria
e repassa o estado do chamador sem alterações.```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

Essas flags reescrevem o arquivo exportado ou a visualização TUI em memória, nunca o
JSONL de origem. `export` recusa uma saída que nomeie o mesmo arquivo que sua entrada,
e grava por meio de um arquivo temporário que é renomeado para o lugar, de modo que uma execução que
falha deixa o arquivo anterior intacto.

O `inputSchema` e o `outputSchema` de uma ferramenta, como anunciados em um resultado
de `tools/list`, não são alterados por `--redact-key` e `--redact-secrets`. Um nome dentro de um
esquema é uma declaração de tipo em vez de um valor; o nome em si permanece no
log de qualquer forma, e limpar o subesquema sob uma propriedade chamada `token`
levaria junto as próprias verificações da ferramenta. A exceção vale apenas para essa posição,
então um argumento que por acaso se chame `inputSchema` é limpo como qualquer
outro, e a limpeza para em `default`, `const`, `examples` e `enum`, que contêm
dados em vez de estrutura. Use `--redact-path` para nomear algo dentro de um
esquema, ou `--redact-value`, que corresponde ao texto onde quer que esteja, exceto nas
duas palavras-chave que o mcpsnoop analisa, `type` e `x-mcp-header`.

O que cada flag alcança difere, então confira o resultado em vez de presumir. Todas
as quatro limpam cargas úteis JSON-RPC, e `--redact-key`, `--redact-path` e
`--redact-secrets` alcançam apenas essas. Somente `--redact-value` também limpa o stderr,
outro texto não JSON e o interior de uma string. Um cabeçalho `Mcp-Param-*` é
limpo junto com o valor do corpo que ele espelha; os outros metadados do envelope,
rótulos do servidor, `Mcp-Name`, `Mcp-Method` e o status HTTP, são deixados como
capturados. A redação é de melhor esforço, então use um caminho de saída separado e leia o
resultado antes de compartilhá-lo.

### Transmita chamadas concluídas para um coletor OTLP

Envie spans enquanto o proxy está em execução apontando-o para um endpoint OTLP/HTTP JSON
de traces. Repita `--otlp-header` para autenticação do coletor ou cabeçalhos 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

O relatório mostra ferramentas que foram adicionadas ou removidas, alterações na descrição e no `inputSchema`, chamadas de ferramenta correspondentes cujo status mudou e mudanças notáveis de duração. As chamadas são correspondidas por nome e argumentos da ferramenta, portanto chamadas reordenadas ainda são comparadas corretamente. Por padrão, as mudanças de duração devem diferir em pelo menos 100 ms e 2x; use `--duration-threshold` e `--duration-ratio` para ajustar esses limites.

Passe `--exit-code` para condicionar a CI a regressões: ele sai com código não zero quando a sessão posterior remove uma ferramenta, altera a descrição, o título, o esquema de entrada, o esquema de saída ou as anotações de uma ferramenta, tem uma chamada cujo status piorou ou fica mais lenta. Melhorias (ferramentas adicionadas, chamadas corrigidas, acelerações) ainda saem com zero, assim como uma mudança de ícone, que altera a aparência de uma ferramenta sem mudar o que ela faz.

## Verificando sessões em CI

Condicione a execução de um agente gravado a erros, corrupção de fluxo, avisos de protocolo, incompatibilidades de cabeçalho de roteamento, chamadas que nunca receberam resposta, quadros descartados que deixam a captura incompleta, deriva de definição de ferramenta ou uso de recursos de protocolo obsoletos.```bash
mcpsnoop check [--format text|junit|sarif] [--fail-on error,invalid,warn,mismatch,pending,late-result,drift,deprecated,incomplete,schema] [session-id|log.jsonl|-]

A contagem de quadros perdidos também viaja junto com os artefatos, então uma captura que
subestima a si mesma diz isso onde quer que seja aberta: `missing_frames` na
exportação JSON, `log.comment` no HAR e o atributo de recurso `mcpsnoop.session.missing_frames`
no OTLP.```bash
mcpsnoop check build-agent
mcpsnoop check --fail-on error,invalid artifacts/session.jsonl
mcpsnoop check --fail-on mismatch gateway-run.jsonl

### Reporte onde a CI já procura

`--format junit` escreve um `<testcase>` por sinal e sessão, e suas falhas
seguem a mesma seleção de `--fail-on` que a saída 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 um cabeçalho de roteamento que discorda do corpo

No transporte streamable-HTTP, um gateway roteia com base em `Mcp-Method` e `Mcp-Name`
enquanto o servidor lê o corpo; portanto, um cabeçalho que discorda do corpo significa
que os dois estão vendo duas requisições diferentes. O sinal `mismatch` cobre esse caso,
um cabeçalho que viaja num lote que não consegue endereçar e um cabeçalho obrigatório
totalmente ausente.

Em 2026-07-28, um cabeçalho de roteamento ausente é uma falha de validação, e um servidor
em conformidade rejeita a requisição com `400` e `-32020`. O mcpsnoop só o emite quando se
sabe que a sessão usa essa revisão ou uma posterior, pois as revisões anteriores não
definem esses cabeçalhos de forma alguma e omiti-los nelas é o correto. A rejeição
`-32020` feita pelo próprio servidor conta como o mesmo sinal.

Um nome ou URI de recurso que não caiba no valor de um campo HTTP viaja em Base64 dentro
de um sentinela `=?base64?…?=`, que é decodificado antes da comparação; assim, um cliente
que codifica corretamente nunca é sinalizado.

Em requisições HTTP `tools/call`, o mcpsnoop também mostra cada cabeçalho `Mcp-Param-{Name}`
e, quando a definição de ferramenta anunciada correspondente é conhecida, compara-o com o
caminho de argumento anotado. Propriedades aninhadas, o sentinela Base64, booleanos e
inteiros seguros numericamente equivalentes são tratados sem falsos positivos de comparação
de strings. Cabeçalhos de parâmetro desconhecidos e sessões sem uma definição de ferramenta
correspondente permanecem apenas observacionais. A redação baseada em chave e em valor é
aplicada aos valores de cabeçalho de parâmetro capturados antes que cheguem a um sink, e um
valor que o próprio mcpsnoop sanitizou nunca é relatado como divergência.

### Detectar desvio na definição de ferramenta

A primeira listagem `tools/list` completa observada para um rótulo de servidor torna-se sua
linha de base confiável. Sessões posteriores comparam essa linha de base campo a campo: a
descrição, o título, os esquemas de entrada e saída, as anotações e os ícones, além das
ferramentas que foram adicionadas ou removidas. As anotações são o que mais importa, pois
uma ferramenta aprovada com `readOnlyHint` que depois se declara destrutiva é exatamente o
puxão de tapete para o qual essa verificação existe, e a especificação instrui os clientes a
tratar anotações como não confiáveis. O título e os ícones são monitorados porque são o que
o usuário vê, e a especificação classifica o `title` da ferramenta acima de `annotations.title`
e do seu nome. A tabela de sessões e o resumo de ferramentas sinalizam o desvio sem bloquear
ou alterar o tráfego MCP.

As anotações são comparadas por meio de seus padrões da especificação, de modo que um servidor
que passa a explicitar uma dica da qual já dependia não é relatado. Uma linha de base registrada
antes de o mcpsnoop monitorar um campo continua funcionando para os campos que registra e informa
quais não consegue responder; regrave com `mcpsnoop baseline --accept` quando confiar nas
definições atuais.

Alterar o que a redação registra muda o que o desvio compara. Uma linha de base obtida sem
`--redact-value` e depois verificada contra uma captura feita com ele relata os campos
sanitizados como alterados, o que é correto, já que a definição registrada de fato mudou.
Regrave com `--accept` após alterar as configurações de redação.

Use um `--label` estável e único para cada servidor cujo nome de comando ou host de destino
colidiria de outra forma. As linhas de base são armazenadas no diretório de estado normal do
mcpsnoop, portanto `MCPSNOOP_HOME` e `XDG_STATE_HOME` se aplicam.```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` é opt-in para `check`; o gate padrão `error,invalid,warn` permanece inalterado.

### Sinalizar recursos de protocolo obsoletos

A revisão de 2026-07-28 torna obsoletos Roots, Sampling e Logging. Eles continuam funcionando por pelo menos um ano, então o mcpsnoop os sinaliza em vez de tratá-los como erros. O stream, o inspetor de capacidades e a exportação sinalizam todos eles, e cada marcador nomeia o substituto.

Dois dos três agora são acessíveis apenas por meio de uma solicitação com múltiplas idas e voltas (round-trips), onde o nome do método fica dentro do mapa `inputRequests` do servidor, em vez de na própria frame. Esses também são sinalizados, para que um servidor que migrou para o novo padrão não pare silenciosamente de reportar.```bash
mcpsnoop check --fail-on deprecated session.jsonl

A coluna carrega a cor de aviso e nunca o vermelho da coluna ERR, e o
mcpsnoop continua sem alterar nada no tráfego que encaminha.

Nada é resolvido ou buscado. Um `$ref` externo é reconhecido apenas pela sua
forma, e o esquema para o qual aponta nunca é lido.

### Veja o quanto o servidor custa em contexto

As definições de ferramentas entram no contexto do modelo em todas as
conversas, e os resultados das ferramentas em todas as chamadas. O resumo da
ferramenta (`s`) mede ambos a partir da sessão que você realmente capturou.

A linha `definitions` é o custo fixo: quanto o `tools/list` deste servidor pesa
antes que uma única chamada seja feita. A coluna `DEF` detalha isso por ferramenta
e `RESULT` é o que as respostas de cada ferramenta custaram até agora. A tabela
permanece ordenada por erros e latência, então examine `DEF` para encontrar as
definições caras; a exportação as lista das mais pesadas primeiro. Uma linha
abaixo da tabela nomeia o resultado individual mais pesado, que um total esconde.

Os valores das definições são o JSON com espaços em branco insignificantes
removidos, portanto, um servidor que faz pretty-print do seu `tools/list` não é
contado como mais caro do que um que não o faz, e o mesmo servidor mede o mesmo
entre capturas. `RESULT` são os bytes como chegaram: um resultado é um payload
único, e não um contrato que valha a pena normalizar.```bash
mcpsnoop export -T json | jq '.summary.definitions'

O socket vive sob o diretório de estado do remoto, resolvido como `MCPSNOOP_HOME`,
senão `XDG_STATE_HOME/mcpsnoop`, senão `~/.local/state/mcpsnoop`. Por padrão, o mcpsnoop
assume o home Linux `/home/<user>` a partir do seu `user@host` e imprime um lembrete
no stderr sempre que recorre a essa suposição. Se o remoto resolver em outro lugar,
nomeie a peça não padrão.```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 manter uma cópia local em vez disso, use scp para copiar os logs para o diretório de sessões e execute
o TUI normalmente.```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 fluxos de trabalho remotos, use tunelamento SSH ou transferência de arquivos via SSH para que a autenticação de transporte,
criptografia, verificação de host, rotação de chaves e política de auditoria permaneçam na sua
configuração SSH existente.

## Contribuindo

Issues e pull requests são bem-vindos. Consulte [CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/HEAD/CONTRIBUTING.md) para obter os detalhes.

## Licença

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