Você roda CI no seu backend. Faz lint no frontend. Seus containers Docker têm healthchecks. Tudo na sua stack tem uma história de testes — menos as conexões MCP das quais seu agente depende a cada chamada.

Em 19 de abril, a equipe do MCP publicou o roadmap de 2026. Quatro prioridades: autorização, registro, primitivas de UX rica e capacidades agênticas. Testes, health checks, validação de contratos — fora da lista. Nem mencionados. Nem planejados. 😾

Então você está por conta própria. Aqui vai como testar servidores MCP hoje com as ferramentas que realmente existem.

Com o que você tem pra trabalhar

O ecossistema MCP tem cerca de 17.000 servidores registrados. Auditorias da comunidade mostram que mais ou menos metade responde de forma confiável em qualquer momento. Seu agente se conecta a três servidores? Estatisticamente, um deles está instável agora mesmo.

A Testomat.io publicou o levantamento mais completo de ferramentas de teste MCP em 8 de abril. A conclusão deles é direta: nada fala MCP nativamente para testes. Tudo é gambiarra empilhada em cima de frameworks HTTP genéricos. Nenhum test runner entende transporte MCP. Nenhuma biblioteca de assertions sabe como é uma resposta válida de tool. Você constrói toda a stack de testes do zero para cada servidor do qual depende.

Aqui vai o inventário completo do que existe — e como fazer funcionar.

MCP Inspector: o ponto de partida manual

MCP Inspector é a ferramenta oficial de debug — pense no Postman para MCP. Você conecta num servidor, chama tools manualmente, inspeciona respostas.

O que ele te dá:

  • Descoberta e invocação interativa de tools
  • Inspeção de respostas JSON cruas
  • Diagnóstico de conexão para transportes stdio e HTTP+SSE

O que ele não dá:

  • Integração com CI
  • Detecção de regressão
  • Suítes de teste automatizadas
  • Validação de resposta contra qualquer schema

É uma chave de fenda. Útil pra cutucar durante o desenvolvimento, inútil pra prevenir regressões em produção. Você precisa de um test harness. 😹

Construindo wrapper tests (a abordagem gambiarra)

A maioria dos times que testam MCP hoje escrevem wrapper tests — suítes comuns de pytest ou Jest que chamam tools diretamente pelo SDK do cliente MCP e fazem assert no que volta.

# exemplo pytest — testando uma tool de servidor MCP
import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test_search_tool_returns_results():
    server = StdioServerParameters(
        command="npx",
        args=["-y", "@example/mcp-search-server"]
    )
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            result = await session.call_tool(
                "search",
                arguments={"query": "test query", "limit": 5}
            )
            
            assert result.content is not None
            assert len(result.content) > 0
            assert result.content[0].type == "text"
            
            data = json.loads(result.content[0].text)
            assert "results" in data
            assert len(data["results"]) <= 5

Isso funciona até o servidor upstream mudar o formato da resposta. O que acontece silenciosamente, sem versionamento, sem changelogs — a spec do MCP não tem convenção de semver, não tem equivalente a lockfile, não tem mecanismo pra anunciar breaking changes. Seu assert verifica data["results"] — o servidor renomeia pra data["items"] numa terça-feira às 2 da manhã. Melhor caso: seu teste fica vermelho. Pior caso: o campo ainda existe mas a estrutura interna muda, seu teste continua verde, seu agente alucina em cima de dados malformados, e você paga por token alucinado.

Teste de contrato sem contrato

A lacuna fundamental: servidores MCP não publicam schemas de resposta. A spec descreve o que uma tool deveria fazer em linguagem natural. Ela não oferece nenhum contrato legível por máquina pra validar.

O workaround: gere o seu próprio.

# Passo 1: Grave respostas reais ao longo do tempo
from genson import SchemaBuilder

builder = SchemaBuilder()
for response in recorded_responses:  # colete de staging/dev
    builder.add_object(json.loads(response))

inferred_schema = builder.to_schema()
# Salve no seu repo como o "contrato"

# Passo 2: Valide no CI
from jsonschema import validate, ValidationError

def test_tool_response_matches_contract():
    response = call_mcp_tool("search", {"query": "test"})
    try:
        validate(instance=response, schema=inferred_schema)
    except ValidationError as e:
        pytest.fail(f"Contract violation: {e.message}")

O processo: grave respostas reais do servidor por uma semana. Infira um JSON Schema dessas respostas usando um gerador de schema. Commite esse schema no seu repo. Valide respostas futuras contra ele no CI.

É teste de contrato engenharia reversa. Nada elegante. Mas pega mudanças silenciosas upstream que de outra forma chegariam em produção sem detecção. Quando o schema quebra, seu pipeline quebra — alto e claro, no CI, não silenciosamente na saída do seu agente. 😸

Monitoramento de saúde: construa ou reze

Seu orquestrador pinga containers Docker. Seu load balancer verifica /health. Servidores MCP não oferecem endpoint de saúde — a spec não define nenhum. Um servidor ou está respondendo ou não está, e você descobre quando a chamada de tool do seu agente trava.

Construa seu próprio health check:

import asyncio
from datetime import datetime

async def check_mcp_health(server_params, timeout=10):
    try:
        async with asyncio.timeout(timeout):
            async with stdio_client(server_params) as (read, write):
                async with ClientSession(read, write) as session:
                    await session.initialize()
                    tools = await session.list_tools()
                    return {
                        "status": "healthy",
                        "tools_available": len(tools.tools),
                        "checked_at": datetime.utcnow().isoformat()
                    }
    except (asyncio.TimeoutError, Exception) as e:
        return {
            "status": "unhealthy",
            "error": str(e),
            "checked_at": datetime.utcnow().isoformat()
        }

Rode isso num cron. Alerte em falhas consecutivas. Verifique não só conectividade mas a lista de tools — servidores adicionam e removem tools sem aviso, e seu agente esperando search_v2 depois do servidor silenciosamente tirar ela do ar produz o tipo de falha que parece bug do agente mas não é.

Injeção de falhas: a parte que todo mundo pula

Seu agente chama uma tool. A tool dá timeout. O que acontece depois?

Se você não testou isso, a resposta é: o modelo improvisa. Ele pode dar retry infinitamente. Pode alucinar a resposta esperada. Pode pedir desculpas pro usuário e não fazer nada. Você não vai saber até a produção te mostrar, e a produção cobra por token pela lição. 🙀

Envolva seu cliente MCP pra simular falhas:

import random

class ChaosProxy:
    """Envolve uma sessão MCP real pra injetar falhas durante testes."""
    def __init__(self, real_session, failure_rate=0.1, corruption_rate=0.05):
        self.session = real_session
        self.failure_rate = failure_rate
        self.corruption_rate = corruption_rate
    
    async def call_tool(self, name, arguments):
        # Simular timeout
        if random.random() < self.failure_rate:
            raise TimeoutError(f"Simulated MCP timeout on {name}")
        
        result = await self.session.call_tool(name, arguments)
        
        # Simular resposta corrompida
        if random.random() < self.corruption_rate:
            return self._corrupt_response(result)
        
        return result
    
    def _corrupt_response(self, result):
        # Retorna envelope MCP válido com conteúdo lixo
        # Testa se seu agente lida com dados malformados de forma graciosa
        ...

Rode seu agente por esse proxy com 10% de taxa de falha. Observe como ele lida com timeouts, dados lixo e tools ausentes. Corrija os problemas. Aumente a taxa. Repita até seu agente degradar graciosamente em vez de alucinar com confiança.

A stack completa de testes

Aqui vai como é um deploy MCP testado hoje — tudo feito à mão, nada padronizado:

Camada Ferramenta O que pega
Exploração manual MCP Inspector "Essa tool existe e responde?"
Testes unitários Wrappers pytest/Jest Formato da resposta, comportamento básico
Testes de contrato JSON Schema inferido Mudanças silenciosas de formato upstream
Monitoramento de saúde Cron customizado + alertas Quedas de servidor, drift na lista de tools
Injeção de falhas Wrapper proxy de caos Comportamento do agente em condições degradadas
Testes de integração Runs end-to-end do agente Regressões no pipeline completo

Total de ferramentas padronizadas que a spec MCP oferece pra qualquer coisa disso: zero. Cada camada que você constrói, você também mantém, debugga e reconstrói quando mudanças de transporte quebram sua infra de teste. 😾

As armadilhas que vão te morder

Poluição de estado. Tools MCP podem ter efeitos colaterais — gravar dados, deletar registros, cobrar dinheiro. A spec não define modo mock. Você ou constrói um servidor fake pra testes, roda contra produção (perigoso), ou mantém um ambiente de staging por dependência MCP (caro). A maioria dos times testa contra produção e torce. Torcer não é estratégia de teste.

Mismatch de transporte. Seus testes rodam via stdio. Produção roda via HTTP+SSE. Eles se comportam diferente sob carga, dão timeout de formas diferentes, falham de formas diferentes. Teste ambos os transportes ou aceite que seu ambiente de teste não corresponde à produção.

Expiração de auth. Tokens OAuth expiram. Seu CI roda às 3 da manhã. O token expirou às 2 da manhã. Seu teste falha, não porque o servidor quebrou, mas porque o auth falhou. Lide com refresh de token no setup do teste ou vai ficar caçando falhas fantasmas por horas.

Drift na lista de tools. Servidor adiciona uma tool, remove uma tool, renomeia um parâmetro — sem notificação, sem version bump. Teste a descoberta de tools como parte dos seus health checks. Faça diff da lista de tools contra um snapshot conhecido como bom. Alerte em mudanças.

Agora você é perigoso

Você pode testar servidores MCP. Não porque o protocolo te ajuda — o roadmap de 19 de abril confirma que isso não vai ser prioridade tão cedo — mas porque validação com JSON Schema, engenharia de caos e monitoramento de saúde são problemas já resolvidos. Você pode aparafusar tudo isso na superfície sem testes do MCP com Python comum e um cron job.

O setup é feio. A manutenção é manual. Toda a stack vai precisar ser reconstruída quando a spec eventualmente adicionar primitivas de teste — se algum dia adicionar.

Mas seu agente agora tem dependências testadas em vez de orações. Essa é a diferença entre "funcionou na demo" e "funciona em produção". Um desses paga seu salário. O outro te rende uma mensagem no Slack às 2 da manhã de alguém que confiou no seu agente pra algo importante. 😼

→ Roadmap MCP 2026 (19 de abril de 2026) → Testomat.io — Ferramentas de Teste para Servidores MCP