MCP Servers: Quando curl se Torna uma Armadilha e Ferramentas Tipadas Resolvem Isso

Em fevereiro de 2024, eu precisava de um agente para consultar transações diretamente no banco de dados Postgres de staging. A API REST adicionou três camadas de abstração que tornaram o debug impossível. A solução óbvia: dar a ele Bash e deixá-lo executar psql.

Funcionou na primeira chamada. Na décima, o agente estava construindo consultas manualmente, escapando parâmetros incorretamente, quebrando na terceira tabela com uma convenção de nomenclatura inesperada. Era improvisação disfarçada de automação. Levei três dias para entender que o problema não era o agente: era que eu não havia dado a ele a ferramenta certa para o trabalho.

As ferramentas nativas de harness cobrem o caso em que o agente trabalha com código local. Mas quando você quer que o agente atualize um cartão do Jira, consulte logs no Grafana, execute uma consulta no banco de dados de produção ou envie uma mensagem no Slack? A primeira tentação é dar a ele Bash e deixá-lo chamar curl para cada API. Funciona mal: o agente tem que lembrar o endpoint, construir cabeçalhos, analisar respostas, lidar com tokens de autenticação. Cada chamada se torna improvisação. Erros silenciosos. Sem segurança de tipo.

MCP, o Protocolo de Contexto do Modelo, resolve isso. É um protocolo aberto que define como um processo externo expõe ferramentas ao agente. O agente descobre as ferramentas, suas assinaturas de JSON Schema, e as chama como se fossem nativas. O harness se torna a ponte.

A peça em uma frase

Um servidor MCP é um processo que fala um protocolo padronizado para: (1) descrever as ferramentas que oferece, (2) executar essas ferramentas quando o agente as chama. Para o agente, tudo são apenas chamadas de ferramentas. Não importa se são nativas do harness ou vieram de um servidor MCP.

Um servidor MCP "Jira" expõe jira_create_issue, jira_search, jira_update_status. O agente vê essas ferramentas ao lado de Read, Bash, etc. Ele as chama da mesma forma. O harness as roteia.

stdio vs HTTP

Os servidores MCP se conectam ao harness através de um dos dois transportes:

stdio: o servidor é um subprocesso. O harness inicia o servidor e troca mensagens JSON-RPC via stdin/stdout. O processo morre quando a sessão termina. Use quando o servidor roda localmente, sem dependência de rede, sem precisar ser compartilhado entre sessões.

HTTP: o servidor é um serviço web. O harness se conecta via HTTP/SSE. Você gerencia o ciclo de vida do servidor separadamente. Use quando o servidor roda remotamente, múltiplos agentes o compartilham, ou o servidor precisa de estado persistente.

90% dos servidores MCP que você usará começam como stdio. HTTP apenas quando você realmente precisa.

Configuração

No Claude Code, os servidores MCP são declarados em ~/.mcp.json:

{
  "mcpServers": {
    "postgres-prod": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://readonly@db.internal/app"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxxxxxxx" }
    }
  }
}

Quando a sessão começa, o harness lê o arquivo, inicia os servidores stdio e descobre as ferramentas de cada um. O agente vê tudo prefixado com o nome do servidor: mcp__postgres-prod__query, mcp__github__create_issue.

O que faz uma ferramenta boa

Um servidor MCP mal projetado é pior do que nenhum: o agente tropeça em suas próprias ferramentas.

Nomes verbais e específicos: create_issue, não issue ou do_jira_thing. O modelo lê o verbo e decide.

Descrições que ensinam discriminação: "Pesquise por problemas por consulta JQL. Use isso quando você tiver filtros específicos. Para pesquisa simples por palavra-chave, use search_text em vez disso." A descrição ensina quando usá-lo e quando não usá-lo.

Esquema rigoroso: required sempre marcado. Tipos precisos com enum quando as opções são fechadas. Descrições por campo.

Resultados estruturados: retorne JSON estruturado, não texto longo. O modelo extrai melhor de {"count": 5, "results": [...]} do que de "Encontrei 5 resultados, eles são: ..."

Anti-padrão: MCP para tudo

O padrão inverso de "Bash para tudo": criar servidores MCP para cada API que você usa. Agora você tem 12 servidores, cada um com 50 ferramentas, e a janela de contexto do agente está saturada com descrições de ferramentas antes da primeira mensagem.

A regra: servidor MCP para coisas que você usará com frequência e onde a segurança de tipo importa. Operação única contra uma API obscura? curl via Bash é mais barato. Fluxo de trabalho recorrente contra Postgres? Servidor MCP vale a pena.

Outra variação: uma ferramenta catch-all como execute(action: string) que delega tudo a um campo de string. O modelo perde a segurança de tipo. Divida em ferramentas específicas com esquemas específicos.

MCP em ação

Cenário: o operador relata "o usuário X não recebeu o e-mail de confirmação." O agente tem servidores MCP disponíveis para postgres-prod, mailgun, sentry, slack.

agente -> mcp__postgres-prod__query
         "SELECT id, email, created_at FROM users WHERE email = 'user@x.com'"

resultado -> {user_id: 4421, email: ..., created_at: "2026-05-20"}

agente -> mcp__mailgun__list_events
         {recipient: "user@x.com", since: "2026-05-20"}

resultado -> {events: [{event: "bounce", reason: "550 usuário desconhecido"}]}

agente -> texto final
         "E-mail retornando com 550 usuário desconhecido -- inválido..."