Prenda seus contratos de servidor MCP como você prende suas dependências

Você fixa suas dependências npm. Você tem um arquivo de bloqueio. Você revisa a diferença quando muda.

Agora considere os servidores MCP dos quais seu agente depende. O que os fixa?

tools/list retorna nomes, descrições e esquemas JSON, e seu agente confia em tudo isso. A descrição não é documentação — é a instrução que o modelo lê para decidir o que uma ferramenta faz e quando chamá-la. Não há fixação de versão, nenhuma verificação de integridade, nenhuma diferença a ser revisada. O servidor muda, e o comportamento do seu agente muda com ele.

Quatro maneiras pelas quais uma dependência MCP te quebra silenciosamente

1. Uma descrição é reescrita. Mesmo nome da ferramenta, mesmo esquema, texto diferente. O modelo agora se comporta de maneira diferente e nada registra uma mudança. Esta é a que mais importa, porque não requer nenhuma mudança de esquema — que é exatamente o motivo pelo qual a comparação apenas de esquemas a ignora.

2. Um parâmetro obrigatório aparece. Suas chamadas existentes começam a falhar com parâmetros inválidos, e você descobre a partir do tráfego de produção.

3. readOnlyHint muda de true para false. Uma ferramenta que você permitiu como segura para chamar livremente agora pode mutar o estado.

4. Uma ferramenta desaparece. Melhor caso, um erro limpo. Pior caso, seu agente improvisa com algo mais.

Arte anterior, em destaque

Invariant Labs fez o trabalho fundamental aqui. Eles nomearam envenenamento de ferramentas e rug pulls de MCP, e seu mcp-scan detectou mudanças de descrição via hashing de ferramentas desde abril de 2025. Se você quiser auditar os servidores MCP instalados em sua própria máquina, essa é a ferramenta — ela escaneia as configurações de Claude, Cursor e Windsurf, detecta escalonamento entre origens (sombreamento de ferramentas) e oferece um modo proxy com guardrails ao vivo. Nada disso eu faço.

Eu precisava de algo adjacente: um CI gate. Não "meu laptop está seguro", mas "o contrato dessa dependência mudou desde meu último lançamento." E tinha que rodar contra servidores internos sem enviar descrições de ferramentas para a API de ninguém.

Então eu construí mcpward.

Dois comandos

npx mcpward baseline   # captura o contrato do servidor em um arquivo de bloqueio
npx mcpward diff       # em CI: falha a construção se tiver mudado

A linha de base captura o nome de cada ferramenta, hash da descrição, esquemas de entrada e saída e anotações. Então, quando o servidor envia uma atualização:

DRIFT (5 falhas)
  ✗ A descrição da ferramenta "echo" mudou (possível rug-pull)
  ✗ A ferramenta "compute" adicionou propriedade obrigatória "multiplier"
  ✗ A ferramenta "read_data" readOnlyHint mudou de true para false (a ferramenta pode agora mutar o estado)
  ✗ A ferramenta "removed_tool" foi removida

Resumo: 2 passaram | 5 falharam

Código de saída 1. A construção falha. Quatro mudanças de contrato, nenhuma das quais teria aparecido em tempo de execução até que algo quebrasse.

Quebrando vs não quebrando

Nem toda mudança deve falhar uma construção. Adicionar um parâmetro opcional é aceitável. Adicionar um obrigatório não é. A classificação:

Acertar essa linha é a parte difícil de toda a ferramenta. É uma função pura com um conjunto de testes exaustivo baseado em fixtures por trás dela, e é a parte que eu mais gostaria de ser informado que estou errado.

O que mais verifica

Uma vez que já está falando o protocolo como um cliente real:

Conformidade com o protocolo — handshake, negociação de versão, consistência de capacidade, correção do JSON-RPC.

O contrato de erro de duas camadas. Este é subestimado. O MCP distingue erros de protocolo (um objeto error do JSON-RPC) de erros de ferramenta (um resultado bem-sucedido carregando isError: true). Uma ferramenta que falha em seu trabalho — arquivo não encontrado, upstream 500 — deve retornar o segundo, não o primeiro. Os servidores costumam inverter isso, e muda como cada cliente deve lidar com a falha. Nada mais verifica isso.

Heurísticas de envenenamento de ferramentas — frases semelhantes a injeção nas descrições, unicode oculto e de largura zero, esquemas solicitando chaves de API ou senhas, readOnlyHint que contradiz uma ferramenta obviamente destrutiva. A saída é SARIF, então as descobertas vão para a aba de Segurança do GitHub.

Conjuntos comportamentais — casos YAML declarativos com asserções JSONPath:

suites:
  - tool: read_file
    cases:
      - name: arquivo ausente é um erro de ferramenta, não um erro de protocolo
        args: { path: "/does-not-exist" }
        expect: { tool_is_error: true }
      - name: parâmetros inválidos são um erro de protocolo
        args: {}
        expect: { protocol_error_code: -32602 }

Orçamentos de latência — p50/p95 por ferramenta contra um limite configurável.

Sobre confiar em uma ferramenta de teste

Um conjunto de testes em que ninguém pode confiar é pior do que nenhum, então a abordagem de teste é deliberadamente paranoica.

Cada verificação é desenvolvida contra servidores de fixture controlados cuja correção é definida desde o início: um totalmente compatível, um deliberadamente malformado, um par diferindo por exatamente uma mudança de cada classe de classificação, um lento e um envenenado. Servidores de terceiros reais não podem servir como verdade absoluta, porque você não controla se estão corretos.

E cada verificação tem um teste negativo provando que pode falhar. Uma verificação que só passa é um gerador de falsa confiança, não uma funcionalidade. A fixture limpa também deve permanecer 100% limpa em cada lançamento — uma verificação de segurança que grita lobo treina as pessoas a ignorá-la, o que é pior do que não enviá-la.

Experimente

suites:
  - tool: read_file
    cases:
      - name: arquivo ausente é um erro de ferramenta, não um erro de protocolo
        args: { path: "/does-not-exist" }
        expect: { tool_is_error: true }
      - name: parâmetros inválidos são um erro de protocolo
        args: {}
        expect: { protocol_error_code: -32602 }