mcpsnoop v0.13.0

Wireshark para MCP. Um proxy transparente que mostra cada chamada real de ferramenta entre o seu cliente de IA e os seus servidores MCP, ao vivo no seu terminal.

O problema

O MCP Inspector oficial conecta-se como um cliente próprio, por isso nunca vê o que o seu cliente (Cursor, Claude Code, Codex) realmente envia ao seu servidor. E qualquer coisa que espere por uma solicitação chegar não consegue mostrar a chamada que o modelo nunca fez, ou que fez com os argumentos errados. Quando uma ferramenta silenciosamente não é chamada, as capacidades não se alinham, ou uma chamada simplesmente trava, você fica vasculhando logs e adivinhando.

O mcpsnoop fica no caminho real dos dados. Envolva o comando do seu servidor com ele e observe cada frame JSON-RPC ao vivo, enquanto o seu cliente e servidor reais conversam.

Em CI

Esta página também é a listagem da GitHub Action mcpsnoop, então aqui está tudo sobre ela. Ela verifica uma sessão capturada, registra cada descoberta como um alerta de code scanning e falha o job com base no que você definiu como bloqueio.```yaml permissions: security-events: write contents: read

steps:

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

Escolha a versão que quiser. A mais recente está na
[página de releases](https://github.com/kerlenton/mcpsnoop/releases). Cada entrada,
o que significam os códigos de saída e como integrá-lo sem a action estão em
[A GitHub Action](#the-github-action) mais abaixo.

## Início rápido

Veja-o imediatamente, sem nada para configurar.```bash
mcpsnoop demo

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

Tudo o que vem depois de `--` é o comando que normalmente inicia o seu servidor. Substitua por
o que você já usa, como `python server.py`, `npx -y @scope/server`, ou um
binário compilado.

No Claude Desktop você não precisa fazer essa edição manualmente.```bash
mcpsnoop wrap my-server     # route my-server through mcpsnoop
mcpsnoop unwrap my-server   # put it back

wrap localiza o claude_desktop_config.json, copia-o para claude_desktop_config.json.mcpsnoop.bak na primeira vez e reescreve apenas a entrada daquele servidor, deixando a sua formatação e todos os outros servidores intactos. Dentro da entrada reescrita, as chaves voltam a ficar em ordem alfabética. unwrap restaura o arquivo e remove o backup assim que nenhum servidor estiver mais com wrap. Reinicie o Claude Desktop após qualquer uma das operações, pois os servidores MCP são iniciados uma única vez na inicialização.

Depois, use o seu cliente normalmente e abra a interface.```bash mcpsnoop

Sem sinalizadores, sem caminhos de socket, sem ordem de inicialização para lembrar. O shim e a interface encontram
um ao outro por conta própria, e a interface preenche sessões passadas a partir do disco.

Para um servidor HTTP transmissível, execute o mcpsnoop como um proxy reverso.```bash
mcpsnoop http --target http://localhost:3000/mcp --listen :7000

O status HTTP de cada resposta aparece no fluxo, portanto uma resposta que não carrega nenhuma mensagem JSON-RPC própria ainda é um quadro visível em vez de nada: o desafio 401, o 403 em uma Origin rejeitada, o 202 que reconhece 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 literalmente e exibido no inspetor, já que ele nomeia o esquema de autenticação e os metadados do recurso para onde ir em seguida. Filtre por status com status:401 na TUI, ou por qualquer falha com status:err. Um 4xx ou 5xx conta como erro, portanto uma execução padrão de mcpsnoop check falha nele.

Não tem servidor próprio? Experimente de verdade contra um servidor de teste publicado, dirigido pelo seu próprio cliente. Para inspecionar uma sessão depois que ela aconteceu, veja revisar sessões passadas a partir de logs.

Arquivo de configuração

Se você reutilizar os mesmos sinalizadores 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

Repita `redact-key`, `redact-value` e `redact-path` em linhas próprias para adicionar
mais de um de cada.

Essas são todas as chaves que ele suporta.

O arquivo só é procurado no diretório de trabalho atual, não em diretórios
pais.

Flags explícitas de linha de comando sobrescrevem valores do arquivo de configuração.

## Comandos

| Comando | O que faz |
|---|---|
| `mcpsnoop -- <server>` | envolve um servidor stdio como um shim transparente |
| `mcpsnoop` | abre a TUI ao vivo |
| `mcpsnoop http --target <url>` | faz proxy de um servidor HTTP streamable |
| `mcpsnoop export` | renderiza uma sessão para json, html, text, har ou otlp |
| `mcpsnoop check` | falha o CI em erros, frames inválidos, avisos, incompatibilidades de roteamento, chamadas penduradas, resultados atrasados ou um orçamento de latência |
| `mcpsnoop baseline` | inspeciona, aceita ou redefine definições de ferramentas confiáveis |
| `mcpsnoop diff` | compara ferramentas e chamadas entre duas sessões capturadas |
| `mcpsnoop open` | abre uma sessão salva na TUI |
| `mcpsnoop inventory` | lista todos os servidores que já passaram pelo mcpsnoop nesta máquina |
| `mcpsnoop stats` | consolida cada captura armazenada em uma linha por servidor e ferramenta |
| `mcpsnoop prune` | exclui logs de sessões salvas mais antigos que um limite |
| `mcpsnoop wrap <server>` | roteia um dos servidores do Claude Desktop pelo mcpsnoop |
| `mcpsnoop unwrap <server>` | restaura a entrada daquele servidor ao estado original |
| `mcpsnoop remote <user@host>` | imprime o comando de túnel SSH |
| `mcpsnoop demo` | reproduz uma sessão roteirizada |

Execute `mcpsnoop help` para a lista completa, ou `mcpsnoop help <command>` para as flags de um comando.

## Como ele se compara

| | MCP Inspector | mcpsnoop |
|---|:---:|:---:|
| Vê o tráfego real do seu cliente e servidor | não | sim |
| Sinaliza chamadas penduradas e erros de stream | não | sim |
| Sinaliza saída dispersa que corrompe o stream | não | sim |
| Sinaliza frames JSON-RPC malformados | não | sim |
| Detecta desvio de definição de ferramenta após aprovação | não | sim |
| Interface de terminal interativa | não | sim |
| Zero configuração, sem flags ou ordenação | não | sim |
| Inspetor de capacidades | parcial | sim |
| Reproduz uma chamada capturada | não | sim, via stdio e via HTTP |
| Exportação de sessão (json / html / text / otlp) | não | sim |
| Binário único, sem dependências de runtime | não | sim |

## Instalação