O autoengano de espelhar rotas de API na interface de servidores MCP

Quem decide expor uma API para agentes autônomos quase sempre comete o mesmo erro de principiante: pega a documentação do Swagger ou o cliente do SDK e cria uma ferramenta MCP para cada endpoint existente. Se o serviço tem quinze métodos para inspecionar instâncias, listar volumes, checar faturas e desligar recursos ociosos, o servidor MCP nasce com quinze ferramentas declaradas. A consequência imediata não é apenas uma conta mais alta de tokens no fim do mês. É a degradação rápida da capacidade de raciocínio do modelo, soterrado por dezenas de definições de esquemas JSON que precisam ser reenviadas em cada rodada de conversa.

O debate recente sobre enxugar servidores MCP de quinze para quatro ferramentas trouxe esse atrito para a superfície. De um lado, defensores do desenho orientado a resultados argumentam que agrupar ações em ferramentas de nível mais alto resolve o problema ao limpar a área de contato do modelo. Do outro, desenvolvedores apontam que isso apenas transfere a conta do esquema para o retorno, já que ferramentas agregadas costumam devolver cargas enormes de dados não filtrados se a modelagem não for cirúrgica.

Ambas as posições tocam em partes reais do problema, mas a maioria dos times ainda erra feio ao escolher o que otimizar primeiro.

O modelo mental herdado do REST quebra em agentes

Quando construímos APIs para consumo humano ou para serviços tradicionais em Rails, granularidade faz sentido. Ter rotas específicas para cada recurso facilita cache HTTP, regras de autorização granulares e composição no cliente. Só que um modelo de linguagem consumindo ferramentas via protocolo MCP não se comporta como um desenvolvedor lendo documentação.

Cada ferramenta exposta no servidor exige a injeção do seu esquema JSON completo no contexto inicial. Isso inclui nomes, parâmetros tipados, descrições textuais e restrições de validação. Quando o servidor cresce para trinta, cinquenta ou noventa ferramentas, você gasta dezenas de milhares de tokens antes mesmo de o usuário digitar a primeira palavra. Pior do que o consumo fixo no primeiro turno é o consumo cumulativo em conversas longas: a menos que o provedor mantenha um cache de prefixo absolutamente estável, você paga essa taxa a cada nova mensagem.

Além do custo financeiro direto, existe um custo cognitivo severo. Quando você entrega quinze ferramentas com nomes parecidos para o modelo escolher, a taxa de alucinação e a hesitação disparam. O agente passa a fazer chamadas exploratórias desnecessárias apenas para descobrir qual ferramenta devolve o identificador que outra ferramenta exige como parâmetro.

A solução intuitiva tem sido fundir essas chamadas em ferramentas orientadas a objetivos. Em vez de obrigar o agente a chamar quatro rotas distintas para descobrir se um recurso em nuvem está ocioso, cria-se uma única função que já executa essa validação no backend e entrega a conclusão consolidada. A lógica parece impecável, mas ela esconde uma armadilha na ponta de saída.

A ilusão de economizar no esquema e sangrar no retorno

Parte dos críticos dessa consolidação levantou uma objeção técnica precisa: condensar ferramentas reduz a assinatura do método, mas frequentemente explode o tamanho do JSON devolvido. Se uma ferramenta unificada de auditoria varre dez recursos e cospe de volta o dump completo do SDK com quarenta campos por objeto, você trocou uma perda previsível de quinhentos tokens na declaração por uma avalanche de cinco mil tokens de resposta na conversa.

Pior: enquanto o esquema é estático, o histórico de mensagens acumula esses retornos a cada turno. Um único retorno inchado permanece no contexto até o encerramento da sessão, encarecendo todas as chamadas subsequentes e empurrando o limite de contexto para o teto.

A saída comum para contornar isso tem sido adicionar parâmetros de controle, como uma flag para alternar entre visão resumida e visão detalhada. Na teoria, o modelo usaria o modo compacto por padrão e ativaria o modo detalhado somente quando precisasse investigar um item específico. Na prática de produção, isso quase nunca funciona sem intervenção rígida. Modelos tendem a ser gananciosos. Na menor incerteza, o agente aciona a opção de detalhe máximo e anula qualquer ganho de eficiência obtido no desenho da ferramenta.

Eu discordo de quem acha que o problema se resolve apenas ajustando parâmetros opcionais na chamada. Delegar ao próprio modelo a decisão de quanta informação ele precisa receber é pedir para ser surpreendido na fatura. O servidor MCP é quem deve governar os limites do contrato de resposta.

## Exemplo de serialização defensiva em um servidor MCP
class AuditSummaryTool
  MAX_ITEMS = 5

  def call(filter:)
    raw_findings = CloudAuditor.scan(filter: filter)

    # Nunca devolva o payload completo do SDK ou do banco
    findings = raw_findings.first(MAX_ITEMS).map do |item|
      {
        id: item.resource_id,
        category: item.waste_type,
        cost_impact: item.estimated_monthly_loss,
        actionable: item.can_be_purged?
      }
    end

    {
      total_detected: raw_findings.size,
      showing: findings.size,
      items: findings,
      inspection_cursor: raw_findings.size > MAX_ITEMS ? generate_cursor(filter) : nil
    }
  end
end

Projeção estrita e proveniência como regra de contrato

Para desenhar ferramentas MCP que não queimem orçamento nem confundam o agente, adoto três regras estruturais nos sistemas que projeto.

A primeira é nunca expor métodos utilitários atômicos quando o objetivo do agente for uma tomada de decisão composta. Se o agente precisa inspecionar integridade de dados e sugerir correção, crie uma ferramenta que execute o pipeline de verificação no servidor e devolva o diagnóstico estruturado, em vez de expor consultas brutas ao banco de dados.

A segunda é aplicar projeção rígida nos dados retornados. Três a cinco campos bem escolhidos quase sempre bastam para o modelo decidir o próximo passo. Informações contextuais pesadas como metadados de configuração, logs detalhados de execução e históricos brutos devem ficar no servidor, acessíveis apenas sob demanda por meio de um identificador unívoco. Se o agente realmente precisar auditar a origem de um achado específico, ele deve fazer uma chamada pontual para aquele item isolado, e não receber a coleção inteira aberta.

A terceira regra envolve a retenção de proveniência enxuta. Cada dado resumido entregue ao modelo deve conter um carimbo curto de rastreabilidade (a origem da verificação, o identificador do registro e a data da coleta). Isso dá ao agente a segurança necessária para agir ou justificar sua decisão para o operador humano sem exigir a carga completa dos registros originais.

Onde a consolidação encontra o seu limite

Existe um limite claro para essa simplificação. Fundir ferramentas além da conta gera ferramentas genéricas demais, com parâmetros complexos e condicionais internas que transformam a implementação do servidor em um pesadelo de manutenção. Se uma ferramenta tenta fazer leitura diagnóstica e mutação destrutiva no mesmo contrato, você perde controle de auditoria e segurança.

A fronteira saudável divide ferramentas por intenção operacional e nível de risco, nunca por recurso de banco ou por endpoint HTTP. Ferramentas de leitura devem sintetizar diagnósticos e limitar o volume retornado na origem. Ferramentas de escrita devem exigir identificadores explícitos e parâmetros estritos, sem agregação preguiçosa.

Se o seu servidor MCP parece um cliente gerado automaticamente a partir de uma rota REST, ele foi desenhado para o consumidor errado. Menos ferramentas com contratos defensivos reduzem custos operacionais, tornam o comportamento do modelo previsível e evitam que a janela de contexto seja desperdiçada com o ruído de transporte que o backend deveria ter resolvido internamente.

Fontes

• https://dev.to/aws-builders/mcp-token-cost-i-cut-my-mcp-server-from-15-tools-to-4-cek