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.

Experimente o Apidog hoje

Esse crescimento expôs uma lacuna prática: ainda falta uma forma limpa de testar servidores MCP. Executar JSON-RPC manualmente via stdio funciona para um hello-world, mas quebra rápido quando seu servidor tem 12 ferramentas, 3 prompts e uma API upstream instável.

Neste guia, você vai montar um fluxo de teste para servidores MCP: primeiro manualmente, depois com automação no Apidog. A ideia é tratar seu servidor MCP como qualquer outra API: com contrato, mocks e testes de regressão.

Se você vem de um contexto mais geral de agentes, nosso guia agents.md combina bem com este; as convenções ali ajudam a comunicar contratos MCP para o time.

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 validar respostas como initialize, tools/list, tools/call, resources/read e prompts/get contra um contrato.
• Comece manualmente: rode o servidor pela linha de comando, envie chamadas JSON-RPC e corrija erros de formato antes de adicionar clientes.
• Automatize depois: capture o tráfego JSON-RPC no Apidog, salve cada chamada, adicione asserções e execute no CI.
• Use mocks do Apidog para simular APIs upstream chamadas pelo seu servidor MCP.
• Baixe o Apidog para centralizar coleção de requisições, mock server e execução de testes.

O que o MCP realmente é

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 ou seu próprio agente — inicia um servidor MCP, executa um handshake de initialize e passa a emitir chamadas.

As chamadas que você mais vai testar são:

• initialize: negociação de versão e capacidades.
• tools/list: lista as ferramentas expostas e seus schemas de entrada.
• tools/call: invoca uma ferramenta pelo nome com argumentos.
• resources/list e resources/read: listam e leem conteúdos endereçados por URI.
• prompts/list e prompts/get: listam e renderizam modelos de prompt.

O transporte pode ser:

• stdio: frames JSON-RPC delimitados por nova linha em stdin/stdout.
• HTTP streamable: geralmente POST /, com SSE para streaming.

A maioria dos servidores locais usa stdio. Servidores remotos tendem a usar HTTP.

O motivo para testar é simples: qualquer cliente MCP chamará seu servidor do mesmo jeito. Um bug em tools/list pode quebrar Claude Desktop, Cursor e IDEs ao mesmo tempo.

O que testar em um servidor MCP

Um conjunto de testes útil cobre seis dimensões.

1. Conformidade do protocolo

Valide se initialize retorna a protocolVersion correta e se o servidor anuncia apenas as capacidades que realmente suporta.

Exemplo de pontos a verificar:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2026-04-01",
    "capabilities": {
      "tools": {},
      "resources": {},
      "prompts": {}
    }
  }
}

2. Correção dos schemas

Para cada ferramenta em tools/list, valide:

• name
• description
• inputSchema
• campos obrigatórios
• tipos dos argumentos
• descrições minimamente úteis

Descrições vazias ou genéricas prejudicam a seleção de ferramentas em clientes como o Claude.

3. Comportamento das ferramentas

Para cada tools/call, verifique se a resposta retorna blocos de conteúdo válidos:

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Resultado da ferramenta"
      }
    ]
  }
}

Também teste erros esperados:

{
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Argumento obrigatório ausente: city"
      }
    ]
  }
}

Erro de execução da ferramenta deve voltar como isError: true, não como erro JSON-RPC de protocolo.

4. Acesso a recursos

Valide se URIs retornadas por resources/list podem ser lidas via resources/read.

Também teste paginação quando existir.

5. Renderização de prompts

Valide se prompts/get retorna messages bem formados e se argumentos são interpolados nos lugares corretos.

6. Modos de falha

Teste cenários como:

• API upstream fora do ar
• argumento obrigatório ausente
• argumento com tipo inválido
• timeout
• resposta upstream inesperada
• chamadas concorrentes

Esses são os bugs que normalmente chegam à produção.

Testes manuais com stdio

Comece com a configuração mais simples possível:

• um terminal
• o binário do servidor
• o inspector MCP ou JSON-RPC bruto

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

Execute o servidor com o inspector:

npx @modelcontextprotocol/inspector node your-server.js

O inspector abre uma interface web local, conversa com seu servidor via MCP e mostra requisições e respostas. Use isso para confirmar:

• se o servidor inicia
• se initialize responde corretamente
• se capacidades são anunciadas
• se tools/list retorna o formato esperado
• se tools/call funciona no caminho feliz

Depois, execute o mesmo fluxo com stdio bruto para capturar frames que serão usados no 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.

Repita o processo para:

• initialize
• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

Ao final, você terá pares de requisição-resposta canônicos. Eles viram o contrato de teste do seu servidor.

Cuidados ao validar respostas MCP

Blocos de conteúdo

Um resultado de ferramenta pode retornar texto:

{
  "content": [
    {
      "type": "text",
      "text": "Previsão para Tokyo: 23°C"
    }
  ]
}

Ou imagem:

{
  "content": [
    {
      "type": "image",
      "data": "...",
      "mimeType": "image/png"
    }
  ]
}

Misturar tipos em uma resposta é permitido, mas clientes podem renderizar de formas diferentes. Teste o formato, não apenas o conteúdo.

Erros de ferramenta

A especificação separa erros de ferramenta de erros de protocolo.

Para falha esperada da ferramenta, use:

{
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Cidade não encontrada"
      }
    ]
  }
}

Evite retornar erro JSON-RPC para falhas de negócio da ferramenta. Muitos clientes interpretam isso como falha de protocolo e encerram a conexão.

Do manual ao automatizado com Apidog

Testes manuais pegam bugs óbvios. Automação evita regressões.

O fluxo é:

1. Capturar pares requisição-resposta durante os testes manuais.
2. Criar requisições salvas no Apidog.
3. Adicionar asserções JSONPath.
4. Mockar APIs upstream.
5. Executar tudo no CI.

1. Crie um projeto Apidog para o servidor MCP

Abra o Apidog e crie um novo projeto.

Configure:

• URL base do endpoint HTTP do servidor MCP; ou
• URL de um wrapper HTTP para servidores stdio.

Projetos Apidog suportam REST e JSON-RPC, então crie um ambiente JSON-RPC para organizar as chamadas.

Se seu servidor usa apenas stdio, rode-o atrás de um wrapper HTTP durante os testes. O inspector oficial fornece uma opção para isso. Outra alternativa é um script Node simples que recebe JSON-RPC por HTTP e encaminha para stdio.

Esse padrão também é usado em testes de API sem Postman em 2026 para backends que não expõem HTTP diretamente.

2. Salve as requisições canônicas

Crie uma requisição salva para cada chamada importante:

• initialize
• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

Uma chamada tools/call pode ficar assim:

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

Salve também variações negativas, por exemplo:

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

Essa requisição deve retornar isError: true, não quebrar o protocolo.

3. Adicione asserções

A automação não serve apenas para enviar requisições. O valor está nas asserções.

Para tools/list, valide no mínimo:

• $.result.tools existe
• $.result.tools.length é maior que zero
• toda ferramenta tem name
• toda ferramenta tem description
• toda ferramenta tem inputSchema
• cada inputSchema é um JSON Schema válido

Exemplo de estrutura esperada:

{
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "description": "Retorna a previsão do tempo para uma cidade",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }
}

Para tools/call com entrada válida, valide:

• $.result.isError é falso ou ausente
• $.result.content é um array
• $.result.content[0].type existe
• o conteúdo tem o formato esperado

Para tools/call com entrada inválida, valide:

• $.result.isError é true
• $.result.content[0].text existe
• a mensagem segue um padrão estável

Prefira regex ou códigos de erro estáveis em vez de comparar a string completa.

4. Simule APIs upstream

A maioria dos servidores MCP encapsula alguma API externa:

• clima
• GitHub
• Linear
• Notion
• banco interno
• plataforma de observabilidade

Não execute testes de CI contra APIs reais a cada commit. Isso cria dois problemas:

• custo
• instabilidade

Use o mock server do Apidog para definir endpoints upstream com respostas previsíveis.

Exemplo de mock de API de clima:

{
  "city": "Tokyo",
  "temperature": 23,
  "condition": "cloudy"
}

Durante testes, aponte seu servidor MCP para a URL do mock. Em produção, use a URL real.

O fluxo de mock também aparece em desenvolvimento de API com contrato primeiro.

Resultado: testes rápidos, determinísticos e sem dependência de rede externa.

5. Execute o conjunto de testes no CI

Projetos Apidog podem ser executados via CLI. O comando apidog run executa requisições salvas, avalia asserções e retorna código diferente de zero em caso de falha.

Exemplo com GitHub Actions:

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 }}

A partir daí, cada push valida o contrato MCP completo.

Como deve ser uma boa cobertura

Um plano completo de testes no Apidog geralmente inclui:

• 1 requisição initialize com asserções de versão e capacidades
• 1 requisição tools/list com validação de formato e JSON Schema
• 2 a 4 requisições tools/call por ferramenta:
  • caminho feliz
  • argumento ausente
  • tipo inválido
  • erro upstream
• 1 resources/list
• 1 resources/read por família de recurso
• 1 prompts/list
• 1 prompts/get por modelo de prompt

Para um servidor com 10 ferramentas, 3 recursos e 4 prompts, espere algo entre 50 e 70 requisições.

Com mocks aquecidos, esse conjunto pode rodar localmente em poucos segundos.

Erros comuns ao testar servidores MCP

Ignorar o initialize

Alguns servidores constroem o registro de ferramentas durante o handshake. Se você chama tools/list antes de initialize, o teste pode falhar por um motivo que não representa o fluxo real.

Sempre execute initialize primeiro.

Fazer asserções em mensagens exatas

Mensagens de erro mudam. Prefira validar:

• isError: true
• código de erro estável
• regex
• presença de campos estruturados

Evite comparar a string completa.

Deixar mocks divergirem da produção

Um mock incorreto dá testes verdes para uma integração quebrada.

Atualize os mocks com respostas reais a cada lançamento ou mudança relevante de contrato.

Esquecer streaming

Servidores HTTP MCP podem transmitir resultados via SSE. Se sua ferramenta usa streaming, ative SSE na requisição salva e valide o stream montado.

Não testar concorrência

Clientes MCP podem enviar múltiplas chamadas tools/call em paralelo. Se o servidor mantém estado compartilhado sem proteção, testes sequenciais passam e produção falha.

Adicione um teste de execução paralela.

Confundir erro de protocolo com erro de ferramenta

Erro de protocolo deve ser usado para falhas no nível JSON-RPC/MCP. Erro de ferramenta deve retornar isError: true.

Misturar os dois pode fazer clientes como o Claude Desktop encerrarem a conexão.

Esse tipo de problema de contrato também aparece em desenvolvimento de plataforma API com contrato primeiro.

Casos de uso reais

Uma equipe criou um servidor MCP interno para a API de gerenciamento de incidentes da empresa. Com asserções no formato de tools/list, detectou três regressões em uma semana. Sem os testes, os bugs teriam sido enviados para todos os engenheiros usando Claude Desktop.

Um desenvolvedor solo publicou um servidor MCP open source para o Notion. Ele usa mocks do Apidog para rodar testes sem atingir rate limits do Notion no CI. O conjunto roda em cada PR, leva cerca de 8 segundos e permite que colaboradores desenvolvam sem acesso à API real.

Uma equipe de plataforma com 14 servidores MCP internos criou um workspace compartilhado no Apidog. Cada servidor tem seu contrato, novos projetos herdam um conjunto base de testes e revisores comparam diferenças de schema antes do merge.

Outra equipe, trabalhando em um servidor MCP para observabilidade interna, usa ambientes do Apidog para executar o mesmo conjunto contra staging e produção. As mesmas 60 asserções validam os dois ambientes sem duplicar requisições.

Conclusão

O MCP se tornou mainstream, mas a história de testes ainda parece com o início dos testes de API REST: manual, frágil e ad hoc.

Você não precisa esperar o ecossistema amadurecer. Trate seu servidor MCP como uma API:

• defina um contrato
• capture chamadas canônicas
• valide schemas
• simule sistemas upstream
• execute regressão no CI

Cinco pontos para levar:

• Um servidor MCP é uma API JSON-RPC; teste com o mesmo rigor de uma API REST.
• Comece com o inspector oficial e stdio bruto.
• Transforme chamadas manuais em testes automatizados no Apidog.
• Cubra protocolo, schemas, ferramentas, recursos, prompts e falhas.
• Use mocks no Apidog para manter testes rápidos e determinísticos.

Próximo passo: abra o Apidog, crie um projeto, cole os corpos JSON-RPC capturados manualmente, adicione asserções JSONPath para tools/list e rode o conjunto de testes.

Em menos de uma hora, você saberá se o contrato do seu servidor MCP está pronto para ser lançado.

FAQ

O que é MCP?

MCP, o Model Context Protocol, é a especificação aberta da Anthropic para clientes de IA chamarem ferramentas externas, recursos e prompts. Ele usa JSON-RPC 2.0 via stdio ou HTTP streamable.

A especificação completa do MCP está publicada em modelcontextprotocol.io.

Posso testar um servidor MCP sem wrapper HTTP?

Sim. O inspector MCP oficial se comunica diretamente via stdio e oferece uma UI para testes manuais.

Para automação no Apidog, use um wrapper HTTP leve durante o CI. O tráfego de produção pode continuar usando stdio.

Como simulo APIs upstream chamadas pelo servidor MCP?

Defina cada endpoint upstream como mock no projeto Apidog. Durante testes, configure o servidor MCP para apontar para a URL do mock. Em produção, use a URL real.

Esse padrão também é abordado em ferramentas de teste de API para engenheiros de QA.

E resultados de ferramentas com streaming?

Servidores HTTP MCP podem transmitir resultados via Server-Sent Events. O Apidog suporta SSE em requisições salvas; ative streaming na configuração da requisição e faça asserções sobre o stream montado.

Devo testar a versão do protocolo?

Sim. Fixe a protocolVersion suportada no initialize e faça asserções contra ela. Incompatibilidades de versão podem gerar falhas silenciosas em clientes.

Posso testar contra o Claude Desktop real?

Sim, e vale fazer isso antes de cada lançamento como teste de fumaça.

Mas não use o Claude Desktop como loop principal de regressão. Ele é manual, lento e menos determinístico. Use o Apidog para regressão automatizada e o Claude Desktop para validação final.

Onde encontro exemplos reais de servidores MCP?

O repositório oficial de servidores MCP tem implementações de referência para filesystem, GitHub, Slack, Postgres e outros serviços.

Leia principalmente as definições de ferramentas. Elas mostram como bons schemas MCP são estruturados.