Playbook de Teste de Servidor MCP: Manual + Automatizado com Apidog

Uma postagem “Ableton Live MCP” no Show HN alcançou 118 pontos e 78 comentários no início desta semana. O padrão já é familiar: alguém escreveu um servidor do Model Context Protocol para uma ferramenta improvável, o público do Claude Desktop adorou, e uma onda de postagens “devo escrever um para X?” se seguiu. O MCP passou de um experimento exclusivo da Anthropic para uma camada de integração de agente padrão em menos de um ano.

O que esse crescimento esconde é uma lacuna nas ferramentas: ninguém lançou uma maneira limpa de testar servidores MCP. Executar JSON-RPC manualmente via stdio com um depurador é bom para um "hello-world"; mas desmorona no momento em que seu servidor tem 12 ferramentas, 3 prompts e uma API upstream instável. Este guia oferece um manual prático para testar servidores MCP manualmente e automatizar esses testes com Apidog, para que você possa lançar servidores MCP da mesma forma que lançaria qualquer outra API: com um contrato, um mock e um conjunto de testes de regressão.

Se você vem de um contexto de agente mais geral, nosso guia agents.md combina bem com este; as convenções lá tornam os contratos de servidor MCP mais fáceis de comunicar à sua equipe.

button

TL;DR

MCP é o Model Context Protocol da Anthropic; é JSON-RPC 2.0 via stdio ou HTTP e expõe três primitivas: ferramentas, recursos e prompts.
Testar um servidor MCP significa verificar suas respostas initialize, tools/list, tools/call, resources/read e prompts/get contra um contrato.
Comece manualmente: opere o servidor pela linha de comando com stdio, confirme as respostas visualmente e corrija erros de formato antes de adicionar clientes.
Passe para o automatizado: capture o tráfego JSON-RPC no Apidog, transforme cada chamada em uma requisição salva, crie asserções sobre o formato e conteúdo da resposta e execute o conjunto de testes no CI.
Use o servidor de mock do Apidog para simular APIs upstream que seu servidor MCP chama, para que os testes permaneçam determinísticos.
Baixe o Apidog para obter a coleção de requisições, o servidor de mock e o executor de CI em um só lugar.

O que o MCP realmente é, em dois minutos

A especificação do Model Context Protocol define um formato de comunicação JSON-RPC 2.0 com uma superfície pequena. Um cliente (Claude Desktop, Cursor, seu próprio agente) inicia um servidor MCP, realiza um handshake de initialize e, em seguida, emite chamadas.

As cinco chamadas que você passará 90% do seu tempo testando:

initialize: negociação de versão e divulgação de capacidades.
tools/list: o servidor retorna as ferramentas que ele expõe, incluindo o JSON Schema para argumentos.
tools/call: o cliente invoca uma ferramenta pelo nome com argumentos.
resources/list e resources/read: o servidor expõe conteúdo endereçado por URI que pode ser lido.
prompts/list e prompts/get: o servidor expõe modelos de prompt que o cliente pode renderizar.

O transporte é via stdio (frames JSON-RPC delimitados por nova linha em stdin/stdout) ou HTTP streamable (tipicamente POST / com SSE para streaming). A maioria dos servidores locais usa stdio; servidores remotos usam HTTP.

Por que testar é importante: todo usuário do Claude Desktop, todo usuário do Cursor, todo IDE que adicionar suporte ao MCP chamará seu servidor. Bugs no formato de tools/list quebram todos os clientes de uma vez. O custo de uma regressão é alto.

O que você deveria estar testando

Um sólido conjunto de testes de servidor MCP cobre seis dimensões.

Conformidade do protocolo. initialize retorna a protocolVersion correta? O servidor anuncia as capacidades que realmente suporta?

Correção do esquema. Cada ferramenta em tools/list tem um JSON Schema válido para argumentos? Os campos obrigatórios estão marcados? A descrição tem mais de três palavras? Descrições vazias quebram a seleção de ferramentas no Claude.

Comportamento da ferramenta. Para cada ferramenta, tools/call retorna blocos de conteúdo do tipo correto (text, image, resource)? Os casos de erro retornam um resultado isError: true em vez de lançar erros JSON-RPC?

Acesso a recursos. Os URIs de resources/list são resolvidos quando chamados via resources/read? A paginação funciona além da primeira página?

Renderização de prompts. Os prompts retornam arrays messages bem formados? As substituições de argumentos caem nos lugares certos?

Modos de falha. O que acontece quando uma API upstream está fora do ar? Quando um argumento de ferramenta está faltando? Quando o cliente atinge o tempo limite? Estes são os bugs que aparecem em produção, não no "hello-world".

O restante deste guia aborda cada um deles, primeiro manualmente, depois automaticamente.

Testes manuais com stdio

Comece com a configuração mais simples possível: um terminal, seu binário de servidor e o inspetor MCP ou JSON-RPC bruto à mão.

Se você ainda não construiu um servidor, crie um com o guia de início rápido oficial do SDK MCP em Python ou TypeScript. O exemplo de previsão do tempo com duas ferramentas é suficiente para testar.

Execute o servidor no modo inspetor:

npx @modelcontextprotocol/inspector node your-server.js

O inspetor inicializa uma interface web local que se comunica via MCP com seu servidor e mostra todas as requisições e respostas. Esta é a maneira mais rápida de confirmar se o servidor inicia, anuncia capacidades e responde a tools/list.

Assim que a visualização do inspetor estiver correta, execute o mesmo fluxo com stdio bruto para que você possa capturar frames para o Apidog:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-04-01","capabilities":{}}}' | node your-server.js

Você receberá uma resposta JSON-RPC no stdout. Salve a requisição e a resposta. Repita para tools/list, tools/call, resources/list e o resto. Ao final deste exercício, você terá de 6 a 12 pares de requisição-resposta canônicos que definem o contrato no nível do wire do seu servidor.

Duas coisas para observar.

Primeiro, blocos de conteúdo. Um resultado de ferramenta retorna content: [{ type: "text", text: "..." }] ou content: [{ type: "image", data: "...", mimeType: "image/png" }]. A mistura de tipos em uma única resposta é permitida; os clientes diferem em como os renderizam.

Segundo, erros. A especificação MCP é clara: erros de execução de ferramenta retornam um resultado normal com isError: true e um bloco de conteúdo descrevendo a falha. Não lance respostas de erro JSON-RPC de dentro de uma ferramenta; isso sinaliza uma falha no nível do protocolo, não no nível da ferramenta. Muitos clientes encerram a conexão em erros de protocolo.

Do manual ao automatizado: construindo o conjunto de testes no Apidog

Testes manuais revelam os bugs óbvios. Você passa para a automação quando começa a se perguntar: "minha última alteração quebrou o esquema de argumento da ferramenta 7?" e não quer digitar 12 comandos curl para descobrir.

O padrão: pegue cada par de requisição-resposta que você salvou durante o teste manual, cole-o no Apidog como uma requisição salva, adicione asserções e execute o conjunto de testes a cada push.

1. Crie um projeto Apidog para o servidor MCP

Abra o Apidog, crie um novo projeto, defina a URL base para o endpoint HTTP do seu servidor MCP (ou URL da ponte stdio; veja abaixo). Os projetos Apidog suportam tanto REST quanto JSON-RPC; crie um ambiente JSON-RPC.

Para servidores stdio que não possuem uma interface HTTP, execute-os atrás de um invólucro HTTP fino para testes. O inspetor oficial fornece um; alternativamente, um script Node de 30 linhas que lê JSON-RPC sobre HTTP e o encaminha para stdio funciona bem. Usamos o mesmo padrão em testes de API sem Postman em 2026 para backends não HTTP.

2. Salve as requisições canônicas

Para cada uma das requisições initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, salve o corpo JSON-RPC como uma requisição. O Apidog as armazena com corpo, cabeçalhos e status esperado.

Uma requisição tools/call se parece com isto na visualização do corpo da requisição do Apidog:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "Tokyo"
    }
  }
}

3. Adicione asserções

O objetivo da automação é fazer asserções sobre a resposta, não enviar a requisição. O Apidog suporta asserções JSONPath nativamente. Para tools/list você quer pelo menos:

$.result.tools existe
$.result.tools.length é maior que zero
Toda ferramenta tem name, description e inputSchema
Todo inputSchema é um JSON Schema válido

Para tools/call em uma entrada conhecida boa, você quer:

$.result.isError é falso (ou ausente)
$.result.content é um array
O primeiro bloco de conteúdo tem o type e o conteúdo esperados

Para tools/call em uma entrada conhecida ruim (argumento obrigatório ausente), você quer:

$.result.isError é verdadeiro
$.result.content[0].text corresponde à sua mensagem de erro esperada

O Apidog armazena essas asserções por requisição. Falhas são mostradas no relatório de execução.

4. Simule as APIs upstream

A maioria dos servidores MCP encapsula uma API externa: dados meteorológicos, GitHub, Linear, um banco de dados interno. Você não quer que as execuções de CI atinjam APIs em tempo real a cada commit. Duas razões: custo e instabilidade.

O servidor de mock embutido do Apidog resolve isso. Defina cada endpoint upstream como um mock, retornando um corpo JSON realista. Aponte a configuração do seu servidor MCP para a URL do mock durante os testes e para a produção durante as execuções reais. Abordamos o fluxo de trabalho de mock em detalhes no desenvolvimento de API com contrato primeiro.

O resultado: um conjunto de testes que é executado em segundos, não requer rede externa e detecta regressões de esquema muito antes de serem lançadas.

5. Execute o conjunto de testes no CI

Projetos Apidog exportam para executores CLI. O comando apidog run recebe um ID de projeto, executa todas as requisições salvas, avalia asserções e sai com código diferente de zero em caso de falha. Conecte-o ao seu GitHub Actions ou a qualquer provedor de CI que você já use.

Um fluxo de trabalho mínimo:

name: MCP server tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - name: Start MCP HTTP wrapper
        run: node test/wrapper.js &
      - name: Run Apidog suite
        run: npx apidog run --project-id $APIDOG_PROJECT --env ci
        env:
          APIDOG_PROJECT: ${{ secrets.APIDOG_PROJECT }}
          APIDOG_TOKEN:   ${{ secrets.APIDOG_TOKEN }}

Cada push executa o contrato MCP completo. A regressão de esquema da ferramenta 7 não pode ser lançada sem ser detectada.

Como é uma boa cobertura de teste

Um plano completo de teste de servidor MCP no Apidog geralmente inclui:

1 requisição initialize com asserções de capacidade
1 requisição tools/list com asserções de formato e JSON Schema
2 a 4 requisições tools/call por ferramenta: caminho feliz, argumento faltando, tipo inválido, erro upstream
1 resources/list mais 1 resources/read por família de recursos
1 prompts/list mais 1 prompts/get por modelo de prompt

Para um servidor de 10 ferramentas com 3 recursos e 4 prompts, o conjunto de testes atinge de 50 a 70 requisições. O Apidog executa isso localmente em menos de 10 segundos com o servidor de mock aquecido.

Erros comuns ao testar servidores MCP

Estes são os padrões que vemos com mais frequência.

Ignorar a viagem de ida e volta de initialize. Vários servidores falham em tools/list se initialize nunca foi chamado porque eles constroem seu registro de ferramentas preguiçosamente dentro do handshake. Sempre execute initialize primeiro.

Asserções em strings de erro brutas. As mensagens de falha da ferramenta mudarão. Faça asserções em isError: true e em um código de erro estável ou uma regex, não em correspondências exatas de string.

Deixar o mock se desviar da produção. Um mock que retorna formatos que a API real nunca retorna lhe dá testes verdes em uma integração quebrada. Re-registre os dados de mock a partir de respostas reais a cada lançamento.

Esquecer o streaming. Servidores HTTP MCP transmitem resultados de ferramentas via SSE. Seu executor de testes deve lidar com SSE; o Apidog o faz, mas você precisa habilitar o streaming na requisição.

Não testar a concorrência. Clientes MCP enviam requisições tools/call concorrentes em loops de agente. Se seu servidor mantém estado compartilhado sem bloqueios, testes de requisição única passam e a produção falha. Adicione um teste de execução paralela ao conjunto de testes.

Confundir erros de protocolo com erros de ferramenta. A especificação MCP os separa propositalmente; misturá-los faz o Claude Desktop fechar a conexão. Cobrimos o mesmo tipo de erro de contrato em desenvolvimento de plataforma API com contrato primeiro.

Casos de uso no mundo real

Uma equipe construindo um servidor MCP interno para a API de gerenciamento de incidentes de sua empresa detectou três regressões em uma semana usando asserções Apidog no formato de tools/list. Sem o teste, os bugs teriam sido lançados para todos os engenheiros usando o Claude Desktop simultaneamente.

Um desenvolvedor solo publicando um servidor MCP de código aberto para o Notion usa mocks do Apidog para executar o conjunto de testes sem atingir os limites de taxa do Notion durante o CI. Seu conjunto de testes é executado em cada PR, leva 8 segundos e armazena os dados de mock do Apidog no repositório para que os colaboradores não precisem de acesso à API para desenvolver.

Uma equipe de plataforma executando 14 servidores MCP internos construiu um workspace Apidog compartilhado onde o contrato de cada servidor reside. Novos servidores herdam um conjunto de testes base; revisores podem comparar diferenças de esquema lado a lado antes de mesclar. A equipe relata duas interrupções evitadas no primeiro trimestre, ambas detectadas por asserções de formato de tools/list em um PR que teria lançado um argumento renomeado para todo usuário do Claude Desktop dentro da empresa.

Uma segunda equipe construindo um servidor MCP para uma plataforma de observabilidade interna usa o alternador de ambiente do Apidog para executar o mesmo conjunto de testes contra staging e produção. Cada ambiente aponta para um arquivo de dados de mock diferente, então as mesmas 60 asserções confirmam ambas as implantações sem reescrever uma única requisição.

Conclusão

O MCP se tornou mainstream este ano, mas a história dos testes ainda está onde os testes de API REST estavam uma década atrás: ad hoc, manual, frágil. Você não precisa esperar que o ecossistema se atualize. Trate seu servidor MCP como a API que ele é, projete um contrato, simule os sistemas upstream e execute asserções no CI.

Cinco lições:

Um servidor MCP é uma API JSON-RPC; teste-o com o mesmo rigor de uma API REST.
Comece manualmente com o inspetor oficial, depois capture requisições canônicas e passe para a automação.
O Apidog lida com JSON-RPC, asserções, mocks e CI em um único projeto.
Cubra as seis dimensões: conformidade do protocolo, correção do esquema, comportamento da ferramenta, acesso a recursos, renderização de prompts e modos de falha.
Simule APIs upstream no Apidog para que o conjunto de testes permaneça rápido e determinístico.

Próximo passo: abra o Apidog, crie um projeto, cole os corpos das requisições que você capturou manualmente, adicione asserções JSONPath para tools/list e execute o conjunto de testes. Você saberá em uma hora se o contrato do seu servidor é sólido o suficiente para ser lançado.

FAQ

O que é MCP?

MCP, o Model Context Protocol, é a especificação aberta da Anthropic sobre como os clientes de IA (como o Claude Desktop) chamam ferramentas externas, recursos e prompts. É JSON-RPC 2.0 via stdio ou HTTP streamable. A especificação completa do MCP é publicada em modelcontextprotocol.io.

Posso testar um servidor MCP sem um wrapper HTTP?

Sim. O inspetor MCP oficial se comunica diretamente via stdio e oferece uma UI para testes manuais. Para testes automatizados no Apidog, envolva o stdio em um servidor HTTP leve durante o CI; o tráfego de produção ainda passa por stdio.

Como simulo APIs upstream que meu servidor MCP chama?

Defina cada endpoint upstream como um mock em seu projeto Apidog, aponte a configuração do servidor MCP para a URL do mock durante os testes e mude para as URLs de produção em tempo de execução. Abordamos o mesmo padrão em ferramentas de teste de API para engenheiros de QA.

E os resultados de ferramentas de streaming?

Servidores HTTP MCP transmitem resultados de ferramentas via Server-Sent Events. O Apidog suporta SSE em requisições salvas; ative-o nas configurações da requisição e faça asserções no stream montado.

Devo testar a versão do protocolo?

Sim. Fixe a protocolVersion que você suporta em initialize e faça asserções contra ela. Incompatibilidades causam incompatibilidade silenciosa do cliente.

Posso testar meu servidor MCP contra o Claude Desktop real?

Você pode, e deve, pelo menos uma vez antes de cada lançamento. Mas não dependa do Claude Desktop como seu loop de teste; ele é lento, manual e não determinístico. Use o Apidog para o conjunto de testes de regressão e o Claude Desktop para o teste de fumaça.

Onde posso ver exemplos reais de servidores MCP?

O repositório oficial de servidores MCP tem implementações de referência para filesystem, GitHub, Slack, Postgres e dezenas mais. Leia as definições das ferramentas; elas são a maneira mais fácil de entender como é um bom formato MCP.