mcpsnoop v0.22.0

Wireshark para MCP. O mcpsnoop fica entre o seu cliente de IA e o seu servidor MCP e registra cada frame JSON-RPC que eles trocam, sem alterar nenhum dos lados. Assista ao vivo no seu terminal, faça o CI falhar com base no que ele encontra, ou envie para o seu backend de tracing como spans OpenTelemetry.

O problema

O MCP Inspector oficial conecta-se como seu próprio cliente, então ele nunca vê o que o seu cliente (Cursor, Claude Code, Codex) realmente envia ao seu servidor. E qualquer coisa que espere uma requisição chegar não consegue mostrar a chamada que o modelo nunca fez, ou 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 assista a cada frame JSON-RPC ao vivo, enquanto seu cliente e servidor reais conversam.

No CI

Esta página também é a listagem da GitHub Action do mcpsnoop, então aqui está ela por inteiro. 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 critério.

permissions:
  security-events: write
  contents: read

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

Sem uma captura em mãos? Grave uma sessão com seu próprio cliente uma vez, faça o commit dela e deixe a action reproduzi-la em cada build. Nenhum modelo e nenhuma chave de API são executados no CI. A reprodução é verificada como qualquer captura, e o job também falha quando o servidor ficou pior do que na gravação. Um servidor acessado via Streamable HTTP recebe target com seu endpoint, e uma gravação é reproduzida em qualquer um dos transportes.

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

Fixe a versão que desejar. A mais recente está na página de releases. Cada entrada e saída está em The GitHub Action mais abaixo, e cada sinal pelo qual a verificação pode falhar está em docs/CI.md.

OpenTelemetry

A revisão 2026-07-28 do MCP descontinua o Logging em nível de protocolo e orienta as implementações a migrar para stderr em stdio, ou para OpenTelemetry para observabilidade estruturada. O mcpsnoop cobre ambos sem tocar no cliente ou no servidor. As linhas de stderr de um servidor stdio aparecem no stream ao lado de seus frames, e cada requisição se torna um span que segue as convenções semânticas do 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

Uma chamada de ferramenta chega como um span chamado tools/call search, carregando mcp.method.name, gen_ai.tool.name e error.type, de modo que ela aparece em um dashboard criado para MCP em vez de um criado para mcpsnoop. Métricas de ferramentas ao vivo para Prometheus estão a uma flag de distância. Ambos estão em docs/OPENTELEMETRY.md.

Início rápido

Veja imediatamente, sem nada para configurar.

mcpsnoop demo

Para usá-lo de verdade, envolva seu servidor na configuração MCP do seu cliente.

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

Tudo após -- é o comando que normalmente inicia o seu servidor. Substitua pelo 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.

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

wrap encontra claude_desktop_config.json, copia-o para claude_desktop_config.json.mcpsnoop.bak na primeira vez e reescreve apenas a entrada desse servidor, de modo que a sua formatação e todos os outros servidores ficam intactos. Dentro da entrada reescrita, as chaves voltam por ordem alfabética. unwrap restaura o ficheiro e remove a cópia de segurança quando já não há nenhum servidor envolvido. Reinicie o Claude Desktop depois de qualquer uma das operações, uma vez que os servidores MCP são iniciados apenas uma vez no arranque.

Depois, utilize o seu cliente como habitualmente e abra a interface.

mcpsnoop

Sem flags, sem caminhos de socket, sem ordem de inicialização para lembrar. O shim e a UI se encontram sozinhos, e a UI preenche sessões passadas a partir do disco.

Para um servidor streamable-HTTP, execute o mcpsnoop como um proxy reverso.

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

O status HTTP de cada resposta aparece no stream, portanto uma resposta que não carrega nenhuma mensagem JSON-RPC própria ainda é um frame visível em vez de nada. Isso abrange o desafio 401, o 403 em uma Origin rejeitada, o 202 que confirma uma notificação e o 502 quando o alvo não pode ser alcançado de forma alguma. O cabeçalho WWW-Authenticate de um 401 é mantido literalmente e exibido no inspetor, pois ele nomeia o esquema de autenticação e os metadados do recurso a serem acessados em seguida. Filtre por status com status:401 na 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, e a chamada que ele respondeu é lida como falha em vez de uma ainda em espera.

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

Instalação

npm

Nenhum toolchain Go necessário. A maioria dos servidores MCP é escrita em Node ou Python, então este é o caminho mais curto.

npx mcpsnoop -- node build/index.js

O pacote npm não inclui código próprio. Seis pacotes de plataforma carregam cada um uma build, e o npm instala apenas aquele que corresponde à sua máquina, portanto não há nada para baixar no momento da instalação nem nada para desbloquear em um proxy. Para mantê-lo disponível em vez de buscá-lo a cada execução, use npm i -g mcpsnoop.

Homebrew

brew install mcpsnoop

Go

go install github.com/kerlenton/mcpsnoop/cmd/mcpsnoop@latest

Binários pré-compilados para todas as plataformas estão na página de Releases.