mcpsnoop

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.

mcpsnoop demo

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.

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 ### npm Sem necessidade de toolchain Go. A maioria dos servidores MCP é escrita em Node ou Python, então esta é a forma mais rápida de começar.```bash npx mcpsnoop -- node build/index.js

`--older-than` é obrigatório (não há padrão que apagaria 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. Por estar no próprio pipe, e não à margem como o Inspector, ele vê exatamente o que 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` / `R` | reproduzir / editar e reproduzir | | `g` / `G` | topo / fim | | `c` | capacidades | | `ctrl-f` / `ctrl-b` | página | | `s` | resumo da ferramenta | | `p` | pausar | | `y` | copiar | | `shift`+`<tecla>` | ordenar por coluna | | `e` | exportar | | `ctrl-d` | excluir sessão | | `f` | seguir | | `?` | ajuda | | | | Pressione `?` no aplicativo para ver a lista completa. ## Filtrando o fluxo Pressione `/` em uma sessão e combine tokens separados por espaços, com AND. Texto simples corresponde ao método, ferramenta, id e 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 a continue | `id:7` | | `task:` | id da tarefa | `task:01J...` | | `dir:` | direção (`c2s`, `s2c`) | `dir:s2c` | | `kind:` | tipo de quadro (`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 obter algo 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)

Estas flags reescrevem o arquivo exportado ou a visã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 no lugar, de modo que uma execução que falhe deixa o arquivo anterior intacto. O `inputSchema` e o `outputSchema` de uma ferramenta, conforme anunciados em um resultado de `tools/list`, são deixados intactos por `--redact-key` e `--redact-secrets`, por três motivos. - Um nome dentro de um schema é uma declaração de tipo, não um valor. - O nome em si permanece no log de qualquer forma. - Limpar o subschema sob uma propriedade chamada `token` levaria junto as próprias verificações da ferramenta. A isenção vale apenas para essa posição, de modo que um argumento que por acaso se chame `inputSchema` é limpo como qualquer outro, e ela para em `default`, `const`, `examples` e `enum`, que contêm dados em vez de estrutura. Use `--redact-path` para nomear algo dentro de um schema, ou `--redact-value`, que corresponde a texto onde quer que esteja, exceto nas duas palavras-chave que o mcpsnoop analisa, `type` e `x-mcp-header`. O alcance de cada flag difere, então verifique o resultado em vez de presumir. Todas as quatro limpam payloads JSON-RPC, e `--redact-key`, `--redact-path` e `--redact-secrets` alcançam apenas esses. Somente `--redact-value` também limpa 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 demais 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. ### Transmitir chamadas concluídas para um coletor OTLP Envie spans enquanto o proxy está em execução apontando-o para um endpoint de traces OTLP/HTTP JSON. 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

Fixar uma release, a que você quiser. A mais recente está na [página de releases](https://github.com/kerlenton/mcpsnoop/releases). Não existe um `v1` flutuante, de propósito. A release fixada também é o binário que a action instala, então os dois nunca podem divergir e não há um padrão de versão que fique obsoleto. | Input | | |---|---| | `session` | a captura `.jsonl` a verificar, relativa à raiz do repositório. Obrigatório | | `fail-on` | como `--fail-on`, com padrão igual ao padrão da CLI | | `args` | quaisquer outras flags de `check`, entre aspas como numa linha de comando. `--format` é recusado, pois a action lê o relatório | | `upload-sarif` | envia o relatório para code scanning. `true` | | `category` | o namespace do code scanning. `mcpsnoop`. Varie-o por perna de uma matrix, ou as pernas se sobrescrevem | | `fail-on-findings` | falha o job numa finding. `true`. Defina `false` para arquivar os alertas e deixar a verificação obrigatória do code scanning decidir | | `version` | qual mcpsnoop instalar. Padrão: a release que você fixou | | `install` | `false` quando o mcpsnoop já está no PATH, que é o caminho numa plataforma para a qual nenhuma release foi compilada | As saídas são `outcome`, `sarif` e `exit-code`. `outcome` é `passed`, `findings` ou `error`, e a terceira vale a pena tratar separadamente. Significa que nada foi verificado, o que não é o mesmo que nada ter sido encontrado. **Uma execução que não conseguiu verificar falha o job, independentemente do que `fail-on-findings` disser**, porque um pipeline que fica verde tendo verificado nada é pior do que um que falha. O job precisa de `security-events: write`, ou o upload responde 403. Defina `upload-sarif: false` num repositório sem code scanning. ### Ou conecte você mesmo A action são quatro passos e nenhuma mágica. Fazer manualmente exige o mesmo cuidado que ela exige. O upload tem de rodar nas execuções que têm um relatório, que são as que saíram com 0 ou 1 e não as que saíram com 2, e o passo que falha o job tem de vir depois dele, ou as findings nunca chegam à aba para a qual existem.```yaml permissions: # required for all workflows security-events: write # only required for workflows in private repositories actions: read contents: read steps: - name: Check captured MCP session id: check run: | code=0 mcpsnoop check --format sarif artifacts/session.jsonl > mcpsnoop.sarif || code=$? echo "exit-code=$code" >> "$GITHUB_OUTPUT" # 2 means the check never happened, so there is no report to publish and # nothing was verified. Stop here rather than uploading an empty file. [ "$code" -le 1 ] || exit 1 - name: Upload mcpsnoop SARIF report if: ${{ !cancelled() }} uses: github/codeql-action/upload-sarif@v4 with: sarif_file: mcpsnoop.sarif category: mcpsnoop - name: Fail on findings # Separate, and after the upload, so the findings reach the Security tab on # exactly the runs that have some. if: ${{ !cancelled() && steps.check.outputs.exit-code == '1' }} run: exit 1

mcpsnoop check --fail-on drift --baseline .mcpsnoop/baselines session.jsonl ``` `drift` é opcional para `check`. O gate padrão `error,invalid,warn` permanece inalterado. ### Capturar um recurso que nenhum dos lados negociou SEP-2133 moveu recursos opcionais para fora do protocolo principal e para extensões, anunciadas no mapa `extensions` das capacidades de cada lado. Tasks é um deles, então em 2026-07-28 um `tasks/get`, um `notifications/tasks` ou um `tools/call` respondido com um handle de task só significa algo quando o outro lado disse que fala Tasks. Quando não falou, a especificação é explícita: a parte que suporta DEVE ou recuar para o comportamento principal ou rejeitar a solicitação. Fazer mesmo assim é por que um recurso parece estar conectado e depois silenciosamente não faz nada, e o que um leitor recebe em vez disso é um `-32601` ou um `-32021` vários frames depois, ou uma task que nunca progride. mcpsnoop avisa no frame que alcançou a extensão e nomeia qual lado nunca a anunciou.``` tool "slow" answered with a task handle uses the io.modelcontextprotocol/tasks extension, which the client never advertised ``` É um `warn`, portanto uma execução padrão de `check` falha nele. Ele permanece silencioso sempre que a captura não consegue mostrar o que foi negociado, o que é uma captura que começa após o handshake ou uma cujas capacidades foram removidas pela sua própria redação, e em revisões anteriores a 2026-07-28, onde `tasks/*` são protocolo central e usá-los é correto. ### Sinalizar recursos de protocolo obsoletos A revisão de 2026-07-28 desaprova Roots, Sampling e Logging. Eles continuam funcionando por pelo menos um ano, então o mcpsnoop os marca em vez de tratá-los como erros. O fluxo, o inspetor de capacidades e a exportação sinalizam todos eles, e cada marcador nomeia a substituição. Dois dos três agora são acessíveis apenas por meio de uma solicitação de múltiplas idas e voltas, onde o nome do método fica dentro do mapa `inputRequests` do servidor, em vez de no próprio quadro. 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 ``` Como `drift`, `deprecated` é opt-in. Uma execução padrão reporta a contagem e permanece verde, então uma sessão que usa um recurso obsoleto ainda legal nunca deixa o CI vermelho por conta própria. ### Construções de esquema de flag que os clientes lidam mal Um servidor pode ser perfeitamente válido e ainda assim ser difícil para um agente usar. Os clientes diferem em quanto do JSON Schema realmente suportam, e uma ferramenta que o modelo fica chamando incorretamente costuma ser uma ferramenta cujo esquema pediu mais do que o cliente entrega. O resumo de ferramentas, aberto com `s`, tem uma coluna SCHEMA nomeando o aspecto mais notável do esquema de cada ferramenta anunciada, com um `+` ao final quando há mais de um tipo. | Mostrado | Significado | |---|---| | `no root` | o `inputSchema` está ausente, não é um objeto JSON, ou tem um tipo raiz diferente de `"object"` | | `dialect` | um `$schema` nomeando um dialeto diferente do 2020-12 que a revisão usa por padrão | | `ext ref` | um `$ref` apontando para fora do documento, que também é o caso em que a especificação avisa os implementadores a não seguir cegamente | | `oneOf`, `anyOf`, `allOf`, `not` | uma palavra-chave de composição, tratada de forma inconsistente entre os clientes | | `ref` | um `$ref` apontando para dentro do mesmo documento | | `untyped` | uma propriedade que não declara tipo nem outra forma de dizer o que aceita | Todas, exceto a primeira, são observações em vez de veredictos. Um esquema usando `oneOf` não está errado, apenas provavelmente será lido de forma diferente por clientes diferentes, e um esquema pode declarar o dialeto que quiser. `no root` é a exceção: a definição de `Tool` exige `inputSchema` e fixa seu tipo raiz em `"object"`, então um cliente que valida uma listagem rejeita essa ferramenta por completo e ela nunca se torna chamável, sem nada no fio para explicar o porquê. `no root` lidera a coluna por esse motivo, e um esquema que a própria redação do mcpsnoop removeu nunca é reportado, já que um esquema ilegível não é um esquema errado. Essa divisão decide o que `check` faz com eles. `no root` é um aviso no frame `tools/list`, então falha o gate padrão `error,invalid,warn` sem nenhuma flag, que é o ponto: um servidor que envia uma ferramenta inutilizável responde normalmente a cada handshake e simplesmente nunca recebe um `tools/call`. As observações são contadas como `schema_findings` e reportadas sob `schema findings:`, e só falham a execução quando você adiciona `schema` a `--fail-on`. Ambas chegam a `--format junit` e `--format sarif`, e `export` carrega a lista por ferramenta sob `summary.definitions.per_tool[].findings`.```bash mcpsnoop check session.jsonl # a non-object root already fails this mcpsnoop check --fail-on schema session.jsonl # and now so do the observations ``` A coluna carrega a cor de aviso e nunca o vermelho da coluna ERR, e o mcpsnoop ainda não altera nada sobre o tráfego que encaminha. Nada é resolvido ou buscado. Um `$ref` externo é reconhecido pela sua forma sozinha, e o schema para o qual ele aponta nunca é lido. ### Reproduzir uma chamada capturada via HTTP `r` re-emite uma chamada capturada contra um servidor ativo. Para uma captura stdio, o comando está no log, então o mcpsnoop lança uma cópia isolada e envia a solicitação para ela. Uma captura HTTP não tem comando para lançar, e o endpoint que ela registra é despojado do seu userinfo e de cada valor de query, então ele nomeia o servidor sem ser um endereço para discar. Então você diz para onde uma reprodução vai, e o mcpsnoop nunca disca um endpoint de produção porque alguém pressionou uma tecla.```bash mcpsnoop open --replay-target https://api.example.com/mcp session.jsonl mcpsnoop open --replay-target https://api.example.com/mcp \ --replay-header 'Authorization: Bearer sk-…' session.jsonl ``` Sem `--replay-target`, uma sessão HTTP diz isso em vez de oferecer uma chave que não pode funcionar. Com uma, `r` ainda pergunta antes do primeiro envio de uma sessão, da mesma forma que um comando gravado é respondido antes de ser executado. Uma credencial chega ao servidor através de `--replay-header` e de nenhum outro lugar. O mcpsnoop não grava nenhum cabeçalho `Authorization` e não reproduz nenhum, portanto não há nada capturado que uma reprodução possa vazar. O POST reproduzido carrega o que o transporte torna obrigatório, o que um POST do corpo capturado puro não faz: `MCP-Protocol-Version`, um `Accept` listando tanto `application/json` quanto `text/event-stream`, `Mcp-Method`, `Mcp-Name` onde a especificação o exige, e cada `Mcp-Param-*` capturado. Esses são reenviados verbatim a partir da captura, sentinela base64 e tudo, portanto não podem discordar do corpo da forma como uma re-derivação poderia. O único cabeçalho que não é copiado é a versão do protocolo, porque o corpo reproduzido declara a revisão que o mcpsnoop fala e o cabeçalho tem que corresponder ao corpo. `Mcp-Name` é derivado do corpo que está sendo enviado em vez de copiado, porque a especificação o origina de `params.name` ou `params.uri` e exige que um servidor rejeite um cabeçalho que discorde do corpo, então uma edição que renomeie a ferramenta enviaria de outra forma o nome antigo. Os cabeçalhos `Mcp-Param-*` espelham os argumentos capturados, então uma reprodução editada não envia nenhum deles em vez de afirmar algo sobre um corpo que alguém reescreveu. Uma captura só pode definir cabeçalhos nessa única família. Um log é um arquivo que as pessoas compartilham, e deixá-lo nomear qualquer cabeçalho permitiria que ele sobrescrevesse os obrigatórios ou adicionasse uma credencial que ninguém passou. Um `Mcp-Param-*` que uma regra de redação limpou interrompe a reprodução com um motivo. Enviar o espaço reservado colocaria os próprios bytes do mcpsnoop em um servidor ativo como se um usuário os tivesse digitado. Um redirecionamento é recusado em vez de seguido. O endereço é aquele que você nomeou e pelo qual respondeu, e seguir um 307 entregaria essa escolha à outra ponta, reenviando o corpo e, em um salto que apenas muda a porta, a credencial também. O mcpsnoop informa para onde o servidor queria enviá-lo e deixa você decidir se quer nomear aquele em vez disso. Uma resposta que chega como um único objeto JSON e uma que chega como um fluxo de eventos são ambas lidas, e uma falha é nomeada em vez de numerada: - um 401 informa o esquema que o servidor exigiu - um `-32020` informa ao que ele se opôs - um 400 ou 404 não-JSON-RPC diz que o endereço não é um endpoint HTTP Streamable desta revisão ### Distinguir a latência do servidor da do usuário Em requisições de múltiplas idas e voltas, uma chamada de ferramenta são várias requisições, e os segundos que uma pessoa gastou respondendo a uma elicitação ficam dentro do intervalo. Isso é deliberado, já que esse intervalo geralmente é o que você mais quer ver, mas significa que um único número não pode responder a ambas as perguntas. Em uma cadeia `book_flight` onde o servidor trabalhou 1,2 segundos enquanto o usuário levou 37, `check --max-duration 5s` culpa a ferramenta por 38,2 segundos. Ele ainda culpa, porque mudar o que essa flag significa afrouxaria todos os pipelines que já a definem. Dois irmãos nomeiam o que medem em vez disso.```bash mcpsnoop check --max-server-duration 1s session.jsonl # the server's share alone mcpsnoop check --max-round-trips 2 session.jsonl # how chatty a tool is ``` ``` # Instalação ## Requisitos - Python 3.8 ou superior - pip - Git ## Instalação via pip ```bash pip install kitploit ``` ## Instalação a partir do código-fonte ```bash git clone https://github.com/kitploit/kitploit.git cd kitploit pip install -r requirements.txt python setup.py install ``` ## Verificação da instalação Para verificar se a instalação foi concluída com sucesso, execute: ```bash kitploit --version ``` Se a instalação estiver correta, você verá o número da versão exibido no terminal. ## Solução de problemas ### Erro: `pip: comando não encontrado` Certifique-se de que o Python e o pip estejam instalados e adicionados ao seu PATH. Você pode verificar com: ```bash python --version pip --version ``` ### Erro: `PermissionError` durante a instalação Tente usar `pip install --user` ou execute o comando com `sudo` (não recomendado em ambientes virtuais). ### Erro: dependências ausentes Execute `pip install -r requirements.txt` novamente para garantir que todas as dependências estejam instaladas.

Ambos estão desativados por padrão, portanto uma execução padrão de `check` não é afetada, e ambos são lidos a partir dos timestamps dos frames e de um link que o mcpsnoop já inferiu, então nenhum adivinha intenções. Pressione `i` na TUI para ver o detalhamento, ou leia `interactions` nas exportações json, text e html. Cada entrada é uma operação lógica com sua contagem de idas e voltas, seu total, a parcela que o servidor a manteve e a parcela em que ela esperou pelo cliente, além de uma linha por salto nomeando o que cada resposta solicitou. O resumo por ferramenta ganha uma coluna `TRIPS` para que uma ferramenta prolixa seja visível sem abrir nada. `export --format har` coloca a parcela do servidor em `wait` e o restante em `blocked`, que é para isso que esse campo serve, então um visualizador para de desenhar uma espera de servidor de 38 segundos que nunca aconteceu. As contagens e as duas parcelas são acumuladas conforme os frames chegam, em vez de derivadas quando você pede, porque o armazenamento ativo libera frames antigos para permanecer dentro de seu orçamento, e uma resposta derivada seria silenciosamente uma janela em vez de uma cadeia. O detalhamento por salto é lido dos frames ainda retidos e informa quando é apenas parte de um. `ServerTime + ClientTurnaround` é igual ao total por construção, e não por uma aritmética em que alguém precise confiar. `--max-round-trips` julga uma cadeia que ainda está em execução, porque cada requisição que ela já fez é contável, e um servidor que pergunta repetidamente produz exatamente a operação que ninguém jamais termina. `--max-server-duration` espera por um fim, que é a regra que `--max-duration` já aplica, já que uma operação ainda aberta não tem latência para julgar. Uma operação que o mcpsnoop não conseguiu vincular permanece como sua própria entrada de salto único. `matchRetry` recusa um vínculo ambíguo de propósito, e esta visão não preenche essa lacuna. Uma operação que levou uma requisição não carrega detalhamento de saltos, porque um único salto reafirma os totais acima palavra por palavra. Uma cadeia relata um salto por requisição e informa quando o armazenamento não retém mais todos os frames ou quando o trabalho se resolveu fora do par requisição e resposta do qual um salto é feito, o que um handle de tarefa faz. ### Veja o que um servidor pediu ao seu usuário Elicitação é o único caminho no MCP em que uma pessoa digita dados em um servidor, e sob o MRTR a pergunta e a resposta não são mais duas metades de uma única troca. A pergunta está enterrada em um `InputRequiredResult`, a resposta volta dentro de `inputResponses` em uma nova tentativa sob um id diferente, e a única coisa que as une é o link que o mcpsnoop já infere. Sem esse pareamento, uma solicitação de senha recusada é lida como um erro comum de ferramenta.``` tools/call login_legacy [form] creds: decline after 3s password string

Uma linha por servidor, e não por sessão. A chave da linha é o comando registado e o diretório de trabalho, nunca o rótulo, porque o rótulo vem do último elemento do caminho do comando e `node ~/one/build/index.js` e `node ~/two/build/index.js` derivam ambos `index.js`. Uma sessão HTTP baseia-se no endpoint que fez proxy, uma vez que o mcpsnoop não lançou nada ali. A leitura é um envelope por log, o quadro de metadados que o proxy escreve primeiro, por isso isto permanece barato num diretório de capturas grandes. `--tools` é a exceção e lê um log por servidor, a execução mais recente de cada um, razão pela qual é uma flag em vez de uma coluna. Mesmo assim, a leitura é limitada, porque um inventário de ferramentas é estado de sessão que a loja incorpora à medida que avança, pelo que uma captura de cem megabytes é lida através de uma janela fixa em vez de ser mantida inteira para produzir um único inteiro. Quando não há contagem, a linha indica qual de três coisas aconteceu, porque um log que não pôde ser lido não é um servidor que não anunciou nada, e uma frase para ambos faria o mcpsnoop afirmar algo falso. Um comando que uma regra `--redact` reescreveu é impresso como registado e marcado, em vez de ser apresentado como o comando que foi executado. Duas execuções de um servidor, uma limpa e outra não, são duas linhas. O mcpsnoop não pode saber o que o espaço reservado substituiu, e fundi-las significaria adivinhar que as metades ocultas coincidiam. Um servidor executado sob dois valores `--label` é uma linha que carrega ambos os nomes, uma vez que a chave é o comando em vez do nome. Nada numa linha é escrito pelo mcpsnoop. Um comando vem de quem instalou o servidor, um diretório de trabalho vem do sistema de ficheiros, e um rótulo derivado vem do comando. Um valor que contém um caráter de controlo é citado em vez de impresso em bruto, para que um diretório cujo nome contém uma nova linha não possa fechar o campo em que é impresso e fazer com que as linhas seguintes sejam lidas como servidores que nunca foram executados. Um argumento que contém um espaço também é citado, porque `node "~/My Project/ build/index.js"` é, de outra forma, indistinguível de dois argumentos. Qualquer coisa que a passagem não pudesse incorporar é nomeada no cabeçalho em vez de ser descartada. Logs vazios são contados separadamente dos danificados, uma vez que um log de zero bytes é o resíduo comum de uma execução cujo exec falhou ou de um proxy HTTP que ninguém chamou. A saída é ordenada por nome em vez de por recência, para que duas execuções sobre um diretório produzam os mesmos bytes, o que é o que a torna utilizável como linha de base para comparar posteriormente. Existem duas lacunas por construção, em vez de por descuido. Uma execução com `--trace-file` escreveu fora do diretório de sessões e não aparecerá, e `prune` elimina logs, pelo que a primeira vista só é tão antiga quanto o que ainda está em disco. O mcpsnoop reporta o que foi executado nesta máquina através dele. Não analisa nenhuma rede, não lê nenhuma configuração de cliente para a qual não foi apontado, e não julga nada. ### Distinguir um servidor avariado de uma ferramenta que diz não Uma ferramenta que responde `result.isError` está a funcionar. Ela procurou e não encontrou nada, ou rejeitou a entrada. Um servidor que responde a um erro JSON-RPC está avariado. Ambos eram um número no resumo de ferramentas, o que significava que uma ferramenta bem comportada que reporta falhas de domínio parecia exatamente um servidor avariado, e era ordenada acima de um. A coluna `ERR` separa-os. O vermelho é o lado do servidor, que é um erro JSON-RPC ou uma tarefa que terminou falhada sem dizer porquê. A cor de aviso é o próprio `isError` da ferramenta. Uma ferramenta com ambos mostra as contagens unidas, vermelho primeiro, e uma linha sob a tabela nomeia os dois totais sempre que há um número de aviso para explicar. A exportação carrega a mesma divisão como `protocol_errors` e `tool_errors` ao lado do total `errors` a que sempre somam. `check --fail-on error` permanece inalterado e ainda dispara em qualquer um dos casos, uma vez que uma porta que ignorasse um deles seria uma porta que um servidor poderia desativar devolvendo o outro.```bash mcpsnoop export -T json | jq '.summary.tools[] | {name, errors, protocol_errors, tool_errors}'

A exportação traz os mesmos números, por ferramenta e divididos entre descrição e bytes de schema, de modo que uma descrição grande e um schema grande permanecem separáveis e qualquer um pode ser rastreado entre capturas. `mcpsnoop diff` informa se uma descrição ou schema mudou entre duas sessões. A exportação é onde reside o tamanho dessa mudança. **Estes são bytes, não tokens.** Uma contagem de tokens depende do modelo, portanto medi-la significaria incluir um tokenizador e escolher de quem. Bytes são exatos e você pode aplicar sua própria proporção. Um `tools/list` inacabado relata o que viu como um piso e assim o diz, em vez de passar uma soma parcial como se fosse o total. ### Detectar um cliente que corrompe o estado do servidor No padrão de múltiplas idas e voltas, o servidor entrega ao cliente um `requestState` opaco e o cliente deve devolvê-lo intacto na nova tentativa. O servidor é instruído a tratá-lo como entrada controlada pelo atacante, porque um cliente que o adultera pode tentar alterar o comportamento do servidor ou contornar uma verificação de autorização. Posicionado no fluxo, o mcpsnoop vê o valor sair e voltar, então pode dizer quando o contrato foi quebrado. Há três maneiras de quebrá-lo, cada uma reportada como um aviso de protocolo na nova tentativa. | Reportado | Significado | |---|---| | `MRTR retry changed requestState` | o cliente devolveu algo diferente do que o servidor emitiu | | `MRTR retry is missing requestState` | o servidor emitiu um e a nova tentativa o omitiu | | `MRTR retry invented requestState` | a nova tentativa carregou um que o servidor nunca emitiu | Estas são violações de protocolo pelo cliente, e não observações nossas, portanto seguem o sinal de aviso comum e **uma execução padrão de `check` falha em uma delas**. Isso é deliberado. Um cliente que corrompe o estado do servidor merece interromper uma compilação. O valor em si nunca é exibido ou registrado, e nada o decodifica ou analisa. Pode ser um bloco criptografado carregando um principal e um token, e comparar bytes opacos é toda a verificação. Um caso está fora de alcance. Quando um servidor responde com um `requestState` e sem `inputRequests`, uma nova tentativa adulterada não corresponde a nada e não responde a nenhuma chave, portanto não resta nada para vinculá-la à solicitação original e ela é lida como uma chamada não relacionada, em vez de uma violação. Uma troca abandonada não perturba a próxima, e também não é mantida para sempre. Sessenta e quatro trocas abertas é muito mais do que qualquer cliente tem de uma vez, portanto uma sessão que mantém mais está mantendo aquelas que ninguém terminará, e as mais antigas são aposentadas porque a especificação instrui os servidores a dar a esse estado um prazo curto e rejeitá-lo depois. A aposentadoria é contabilizada em vez de silenciosa. O rodapé do fluxo mostra `N unlinked` e a exportação carrega `session.retired_exchanges`, porque uma nova tentativa que chega para uma operação aposentada é lida como sua própria chamada, e um leitor que compara contagens merece ser informado. Aposentar uma também permite que o armazenamento ativo a libere. Uma operação estacionada permanece pendente de propósito, portanto sua duração abrange toda a troca, e o armazenamento recusa-se a esquecer uma chamada pendente porque uma resposta ainda pode estar chegando. Uma vez que o limite aposentou uma operação, nada pode respondê-la, portanto mantê-la mantém uma chamada viva que nenhum leitor pode alcançar. O que a sessão relata não muda. Ela ainda é contada como pendente e ainda é contada em `N unlinked`, porque quanto de memória um registro ocupa e o que o registro diz são perguntas diferentes. Uma troca abandonada não perturba a próxima. O MRTR instrui os servidores a não assumir que um cliente fará nova tentativa, portanto um usuário que recusa uma elicitação deixa uma operação que nenhum quadro posterior jamais resolverá. O mcpsnoop procura primeiro entre as operações cuja presença de `requestState` concorda com a da nova tentativa, o que a especificação torna uma regra em ambas as direções, portanto uma nova tentativa conforme ainda encontra a única operação que continua, mesmo quando uma troca abandonada na mesma ferramenta está ao lado dela. A verificação que relata as três violações acima é executada apenas quando nada concorda, portanto uma nova tentativa genuinamente não conforme ainda é nomeada. ## Observando de outra máquina Mantenha a captura local na máquina onde o tráfego ocorre e use SSH para o salto de rede, de modo que o mcpsnoop nunca precise de um transporte remoto próprio. ### Visualização ao vivo Execute a TUI na sua estação de trabalho e encaminhe o socket do mcpsnoop da máquina remota de volta para ela. O túnel ao vivo usa encaminhamento de socket Unix via SSH, portanto ambas as extremidades devem executar Linux ou macOS. No Windows, use a cópia do log pós-morte abaixo.```bash # on your workstation, start the TUI mcpsnoop # create the remote socket directory once ssh remote-user@remote-host 'mkdir -p ~/.local/state/mcpsnoop' # print the tunnel command, then run the printed ssh -R line mcpsnoop remote remote-user@remote-host # on the remote host, wrap your server as usual mcpsnoop -- node build/index.js

## Segurança O mcpsnoop executa o comando do servidor que você envolve, portanto envolva apenas servidores em que confia e execute os não confiáveis em um contêiner. Ele nunca executa nada que você não tenha colocado na configuração do seu cliente. Para fluxos de trabalho remotos, use túnel SSH ou transferência de arquivos via SSH para que 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. ### Redigindo o que você captura Os quadros capturados podem incluir prompts, argumentos de ferramentas, credenciais e resultados de ferramentas. Se os payloads puderem carregar segredos, opte pela redação para limpar as cópias do trace observado enquanto os bytes intermediados ainda passam inalterados. A redação baseada em chaves substitui valores inteiros sob chaves JSON correspondentes, e o mesmo conjunto de chaves é aplicado com melhor esforço aos argumentos de linha de comando do servidor envolvido, de modo que `--api-key=sk-x` e `--token sk-x` sejam limpos sob `--redact-secrets`. Um argumento que carrega um segredo sem um nome de flag reconhecível não pode ser detectado. O endpoint HTTP não faz parte de nada disso, porque não é um payload que você escolheu enviar. `--target` é um flag que você precisa passar para executar o proxy, então sua URL chegaria ao log da sessão independentemente das suas configurações de redação. O mcpsnoop o registra com o userinfo, cada valor de query e o fragmento já removidos, sempre, por construção e não por padrão. As chaves de query sobrevivem, pois são o que distingue dois endpoints de um mesmo host, e o fragmento é descartado porque nunca chegou ao servidor em primeiro lugar. O que é registrado identifica o servidor e não é um endereço para discar. A redação baseada em caminhos substitui apenas valores selecionados por uma expressão JSONPath, o que é útil quando um nome de chave comum é sensível em um local, mas seguro em outro. Repita `--redact-path` para limpar mais de um local. A redação baseada em valores aplica expressões regulares a valores de string observados, texto de stderr e quadros de texto não JSON. Todos os três são de melhor esforço. Expressões regulares podem deixar passar segredos, capturar texto inofensivo em excesso ou não detectar valores transformados ou codificados. A redação nunca se transforma em uma acusação. Cada verificação que compara uma coisa observada com outra, um cabeçalho de roteamento contra o corpo, um valor de `Mcp-Param` contra o argumento que ele espelha, o schema de uma ferramenta contra o que a revisão exige dela, sabe quando o mcpsnoop foi o lado que reescreveu os bytes e permanece em silêncio em vez de reportar um servidor pela configuração de privacidade do próprio usuário. O desvio de definição de ferramenta é a exceção, e deliberadamente, pois ativar a redação muda o que é registrado e, portanto, o que uma linha de base contém. Consulte [Detectar desvio de definição de ferramenta](#detect-tool-definition-drift).```bash # built-in preset of common secret keys mcpsnoop --redact-secrets -- node build/index.js # or name your own keys mcpsnoop --redact-key token,api_key,password -- node build/index.js # scrub one location without redacting every field named password mcpsnoop --redact-path '$.params.arguments.password' -- node build/index.js # wildcards scrub every matching array element mcpsnoop --redact-path '$.params.arguments.accounts[*].password' -- node build/index.js # scrub obvious token-shaped values outside known keys mcpsnoop --redact-value 'sk-[A-Za-z0-9]+' -- node build/index.js # combine the layers in http mode mcpsnoop http --target http://localhost:3000/mcp --redact-secrets --redact-value 'Bearer\s+\S+'

Sinal	Falha em
`error`	uma chamada respondida com um erro JSON-RPC, um resultado marcado como `isError`, ou uma tarefa que terminou em falha
`invalid`	um frame no canal de protocolo que não é JSON-RPC válido, geralmente um servidor registrando logs no stdout
`warn`	um frame que quebra uma expectativa definida pela especificação MCP ou JSON-RPC
`mismatch`	um cabeçalho de roteamento em desacordo com o corpo, montado em um lote, ou ausente onde a revisão o exige
`pending`	uma solicitação ainda aberta quando a captura terminou, deixando o chamador esperando
`late-result`	uma resposta que chegou depois que sua solicitação foi cancelada
`drift`	uma definição de ferramenta anunciada que muda após a linha de base ser aprovada
`deprecated`	um recurso que a especificação descontinuou
`incomplete`	frames descartados a montante, o que torna cada outra contagem um piso em vez de um total
`schema`	um schema anunciado usando uma construção ou um dialeto que se propaga mal entre clientes

Flag	Falha quando
`--max-duration <dur>`	uma ou mais chamadas de ferramenta concluídas excederam o orçamento, reportando sua contagem e a pior chamada
`--expect-tool <name>`	a ferramenta nomeada nunca foi chamada (repetível)
`--forbid-tool <name>`	a ferramenta nomeada foi chamada (repetível)

Regra	Relatado como
o cliente DEVE enviar um `Accept` listando tanto `application/json` quanto `text/event-stream`	`warn` na requisição
um servidor que responde a uma requisição JSON-RPC DEVE retornar `Content-Type: application/json` ou `text/event-stream`	`warn` na resposta

Opção	Descrição
`-t, --alvo`	URL ou endereço IP do alvo (obrigatório)
`-p, --portas`	Portas a serem verificadas (padrão: 80, 443, 8080)
`-v, --verboso`	Habilita a saída detalhada
`-o, --saida`	Arquivo de saída para salvar os resultados
`--sem-cor`	Desativa a saída colorida no terminal
`-h, --help`	Mostra a mensagem de ajuda e sai

mcpsnoop

Mais Populares

Em CI

Arquivo de configuração

Go```bash

Completions de shell

Como funciona

Exportar sessões

Redação

Comparando sessões

Afirme o que deve e o que não deve acontecer

a contract for the run: search must run, delete must not, nothing over 2s

A GitHub Action

Capturar um cabeçalho de roteamento que discorda do corpo

Verificar os cabeçalhos de transporte que a especificação torna obrigatórios

Detectar deriva na definição de ferramentas

Uso

Comandos Básicos

Opções da Linha de Comando

Exemplos

Configuração

Solução de Problemas

Erro: "Permissão negada" ao executar

Erro: "Módulo não encontrado"

Problemas de conectividade

Perguntas Frequentes (FAQ)

Licença

Aviso Legal

Encontrar a ferramenta que falha uma em cada quatro execuções

Ver quais servidores realmente foram executados aqui

Veja o que o servidor custa a você em contexto

a non-Linux or custom home, macOS is /Users/ and root is /root

an explicit MCPSNOOP_HOME on the remote

an explicit XDG_STATE_HOME on the remote

copy the remote logs into your local sessions directory

open the TUI, it backfills the copied sessions

Contributing

License