Construímos 126 Ferramentas MCP, mas não é a melhor solução para Agentes

Esta é uma série de 10 partes que compartilha como a Apidog desenvolveu o Apidog CLI, uma ferramenta de linha de comando para teste de API e gerenciamento do ciclo de vida da API. Leia em ordem ou pule para qualquer post que lhe interesse:

Quando o MCP se tornou o centro das atenções da indústria, construímos um servidor MCP completo com 126 ferramentas geradas. Veja o que deu errado — e por que mais ferramentas não significam melhor capacitação de Agentes.

O Hype do MCP

No início de 2025, o MCP (Model Context Protocol) tornou-se um centro das atenções da indústria.

A Anthropic promoveu o protocolo. Cursor, Claude Code, Antigravity, vários IDEs de Agentes e numerosos produtos SaaS rapidamente seguiram o exemplo. O protocolo prometia uma forma padronizada para Agentes de IA se conectarem a ferramentas externas e fontes de dados.

Durante esse período, quase todo produto com uma API recebia a mesma pergunta:

"Você tem MCP?"

Para a Apidog, essa escolha parecia especialmente natural.

Por Que o MCP Parecia a Resposta

A própria Apidog havia acumulado um conjunto abrangente de recursos de desenvolvimento de API:

• Documentação de API
• Definições de Schema
• Servidores Mock
• Casos de teste
• Cenários de teste
• Suítes de teste
• Relatórios de teste
• Fluxos de trabalho de importação/exportação
• Colaboração de branch
• E muito mais

Se os Agentes se tornassem o novo ponto de entrada de software — uma nova forma de os usuários interagirem com os produtos — então expor esses recursos através do MCP parecia um requisito necessário.

Acreditávamos que, se pudéssemos empacotar nossos recursos como ferramentas MCP, os Agentes seriam capazes de:

• Consultar documentação de API
• Criar casos de teste
• Executar cenários de teste
• Importar/exportar dados de projeto
• Gerenciar ambientes e variáveis
• Colaborar entre branches

A lógica era direta: mais recursos expostos = mais capacitação de Agentes.

O Que Realmente Construímos

Não levamos isso levianamente.

O Apidog MCP não era uma simples demonstração com alguns endpoints escritos à mão. Era um Servidor MCP completo:

Sistema de Sessão

O cliente MCP primeiro inicializa uma sessão. O servidor gera um sessionId e salva o estado da sessão via Redis. Solicitações subsequentes continuam a acessar com o sessionId.

Em outras palavras, não era uma chamada HTTP única, mas um sistema de sessão em nível de protocolo.

Categorias de Ferramentas

A camada de ferramentas também não foi escrita à mão com alguns endpoints fixos. Dividimos as ferramentas da Apidog em várias categorias:

Essa última categoria: 126 ferramentas geradas.

Cada ferramenta gerada possuía:

• Um identificador único
• Um caminho de API específico
• Um método HTTP (GET, POST, PUT, DELETE, etc.)
• Um Schema de entrada completo com descrições de campo, tipos e valores de enumeração
• Uma estrutura de retorno definida

Divulgação Progressiva

Para reduzir a pressão de exposição de ferramentas, também construímos uma camada de descoberta dinâmica:

O Agente poderia:

1. Primeiro, procurar por ferramentas de endpoint disponíveis (listOpenApiEndpoints)
2. Em seguida, obter os detalhes OpenAPI de uma ferramenta específica (getOpenApiDetails)
3. Finalmente, executar a chamada HTTP real pelo ID da ferramenta (executeOpenApi)

Esta foi nossa tentativa de divulgação progressiva. Não expusemos simplesmente todos os endpoints subjacentes de forma direta e explícita. Esperávamos que os Agentes procurassem primeiro, depois obtivessem os detalhes e, finalmente, executassem.

A Parede de Ferramentas Aleatórias

Mas ao entrar em tarefas reais, problemas surgiram rapidamente.

Considere uma solicitação de usuário simples:

"Ajude-me a adicionar um teste para este endpoint e executar a verificação."

Do ponto de vista da implementação, esta é uma solicitação razoável. Apidog possui as capacidades para:

• Encontrar endpoints
• Criar casos de teste
• Executar cenários de teste
• Gerar relatórios

Mas da perspectiva do Agente, essa solicitação simples aciona na verdade uma série de julgamentos contínuos:

O Agente não precisa apenas encontrar a ferramenta certa. Ele precisa resolver o problema de "qual ferramenta usar" primeiro, antes mesmo de começar a resolver o problema do usuário.

Do ponto de vista da implementação, todos esses problemas podem ser resolvidos através de ferramentas. Do ponto de vista da experiência do Agente, eles formam uma parede de ferramentas aleatórias.

Os Quatro Problemas Estruturais

Através de testes no mundo real e feedback interno, identificamos quatro problemas estruturais com a abordagem MCP.

Problema 1: Os Custos de Descoberta de Ferramentas Aumentam Rapidamente

Apidog não é um produto que pode ser descrito com apenas uma dúzia de endpoints.

Quando as ferramentas crescem de uma dúzia para dezenas ou centenas, o Agente precisa resolver o problema de "qual ferramenta usar" antes de começar a resolver os problemas do usuário.

Tentamos escrever fluxos de trabalho na descrição da ferramenta (o campo usado para expor ferramentas a Agentes de IA). Por exemplo, uma descrição de ferramenta explicitamente declararia:

"Antes de consultar dados de endpoint, você precisa primeiro confirmar o projeto por meio de outra ferramenta, depois obter metadados do projeto por meio de uma terceira ferramenta e, finalmente, chamar a ferramenta atual."

Este método funciona em conjuntos de ferramentas em pequena escala. Mas em uma parede massiva de ferramentas, a descrição em si compete pela atenção do modelo.

Quanto mais orientações escrevíamos nas descrições, mais tokens eram consumidos — e menor a probabilidade de o Agente realmente lê-los e segui-los.

Problema 2: O Schema de Negócio Invade o Contexto

Cada ferramenta MCP não é apenas um nome de ferramenta.

Por trás de cada ferramenta estão:

• description (o que a ferramenta faz)
• input schema (parâmetros, tipos, obrigatório/opcional)
• Explicações de campo (estruturas aninhadas, restrições)
• Valores de enumeração (opções permitidas)
• Estruturas de retorno (formato de resposta, tratamento de erros)

Façamos uma estimativa conservadora:

A pergunta de um usuário pode ter apenas 50 caracteres. Mas o modelo é forçado a introduzir primeiro 50.000 tokens de descrições de ferramentas — apenas para um servidor MCP.

Isso não é teórico. Dados da indústria apoiam isso.

A postagem oficial do blog do Cursor "Dynamic Context Discovery" forneceu dados de referência valiosos: ao converter descrições de ferramentas MCP, sessões de terminal e conversas longas em contexto carregável sob demanda, o consumo de tokens em tempo de execução foi reduzido em 46,9%.

A abordagem de Trae foi mais direta: limitando a contagem de ferramentas MCP e o comprimento da descrição de uma única ferramenta:

• Limite superior de contagem de ferramentas: 40
• Limite de descrição de ferramenta única: 8000 caracteres

De fato, durante os testes internos iniciais, muitas equipes relataram que o Apidog MCP tinha problemas com algumas ferramentas que não podiam ser invocadas no Trae. O Agente foi forçado a fazer concessões devido ao contexto limitado do modelo, e as ferramentas externas foram as primeiras a serem "cortadas".

Todas essas soluções apontam para o mesmo fato:

As descrições das ferramentas não podem entrar infinitamente no contexto do modelo.

Problema 3: Sessões de Protocolo Tornam as Cadeias de Execução Mais Pesadas

O servidor Apidog MCP precisa lidar com:

Para uma chamada de ferramenta simples, esses custos são aceitáveis. Para tarefas de Agente com grandes números de chamadas e exploração frequente, esses requisitos de gerenciamento de estado aumentam a complexidade tanto no lado do servidor quanto no lado do cliente.

Ao implementar o Apidog MCP, a equipe consumiu uma energia significativa na solução de problemas e na adaptação a diferentes clientes Agente (Cursor, Claude Code, Antigravity, Trae, etc.). No entanto, os problemas de compatibilidade de protocolo persistiram, e o protocolo oficial MCP continuou a ser corrigido com novas versões.

Todas as partes sofreram muito.

Problema 4: Ferramentas Atômicas Não Conseguem Expressar Naturalmente a Semântica do Produto

Nos cenários de teste da Apidog, não é apenas uma simples expressão de array de passos.

Um cenário de teste envolve:

Depois de dividir estes em múltiplas ferramentas MCP, o Agente ainda precisa realizar o trabalho de orquestração de testes por conta própria.

Quanto mais atômicas as ferramentas, mais o modelo precisa entender a semântica interna do produto:

• Por que a importação precisa de leitura de retorno?
• Por que os casos internos têm marcadores de atualização diferentes?
• Por que as asserções exigem comparadores específicos?
• Por que a extração de variáveis tem restrições de tipo?

Isso está obviamente além do escopo de capacidade do modelo.

Isso forçou a equipe da Apidog a fazer proativamente ajustes de engenharia técnica para a semântica interna do produto. Endpoints atômicos adicionaram passivamente uma camada de conversão, apenas para se adaptar a um único despacho de camada de ferramenta MCP.

Os desafios de engenharia e os custos de pós-manutenção são, sem dúvida, árduos.

A Causa Raiz

A causa raiz desses quatro problemas é a mesma coisa:

O MCP é melhor em conectar ferramentas, mas tarefas complexas de P&D precisam de mais do que apenas conexão de ferramentas — elas precisam de processos de engenharia executáveis.

Para produtos simples com uma dúzia de operações bem definidas, o MCP funciona bem. O Agente pode razoavelmente adivinhar a ferramenta certa, chamá-la e obter um resultado.

Para produtos como Apidog — com dezenas de módulos, centenas de operações, estruturas aninhadas, fluxos de trabalho ocultos e semânticas específicas do produto — o MCP sozinho cria uma parede de ferramentas aleatórias que os Agentes têm dificuldade em navegar.

O Que Aprendemos

A Virada

Esta percepção nos levou a fazer uma pergunta diferente:

Se o MCP não é a resposta para a capacitação de agentes, o que é?

Não abandonamos o valor do MCP — ele fornece conexões padronizadas, o que é importante para o ecossistema. Mas precisávamos de algo que pudesse:

• Expressar fluxos de trabalho, não apenas ferramentas
• Guiar Agentes através de sequências
• Validar antes de escrever
• Impor portões de qualidade de engenharia
• Absorver a complexidade no sistema

A resposta a que chegamos: CLI + SKILL.

No próximo post, Por Que Desenvolvemos um Novo Apidog CLI , exploraremos a mudança arquitetônica — onde a complexidade se moveu do contexto do modelo para o sistema de engenharia, e por que isso muda tudo para a capacitação de Agentes.

Principais Conclusões

• O MCP tornou-se a resposta da indústria para "como os Agentes se conectam a ferramentas"
• Construímos 126 ferramentas MCP, pensando que mais ferramentas = melhor capacitação
• Tarefas reais revelaram quatro problemas estruturais: custos de descoberta, invasão de contexto, sobrecarga de sessão, semântica do produto
• A causa raiz: o MCP conecta ferramentas, mas tarefas complexas precisam de processos executáveis
• Mais ferramentas são um custo, não um benefício, quando as descrições das ferramentas consomem contexto

Baixe Apidog para projetar, simular, testar e documentar APIs em um único workspace. Saiba mais sobre o Apidog CLI para teste de API via linha de comando, automação CI e fluxos de trabalho de Agentes de IA.