Esta série em 10 partes mostra como a Apidog desenvolveu o Apidog CLI, uma ferramenta de linha de comando para teste de API e gerenciamento do ciclo de vida de APIs. Leia em ordem ou pule para o tema que quiser implementar primeiro:
| Título | Foco | |
|---|---|---|
| 1 | Construímos 126 Ferramentas MCP. Mas Não É a Melhor Solução para Agentes | Descoberta do problema |
| 2 | Por Que Desenvolvemos o Novo Apidog CLI | Desenvolvimento da arquitetura |
| 3 | A Regra de Ouro: CLI Produz Fatos, Modelo Age com Base em Fatos | Filosofia central |
| 4 | agentHints: Ensinando CLIs a Falar com Agentes |
Saída estruturada |
| 5 | SKILL: Entregando Experiência Operacional como Código | Experiência operacional |
| 6 | Os Números Não Mentem: 30% Menos Chamadas de Ferramentas, 25% Menos Tokens | Resultados quantitativos |
| 7 | Do PRD ao Ciclo de Testes: Um Fluxo de Trabalho Completo de Agente com Apidog CLI | Tutorial prático |
| 8 | Por Que a Compatibilidade com CI/CD Não É Negociável para Ferramentas de Agente | Perspectiva DevOps |
| 9 | Ramificação de IA: Alterações de Projeto Mais Seguras com Agentes de IA | Camada de segurança |
| 10 | Spec-First Foi Ontem. Bem-vindo ao Skill-First. | Visão e futuro |
Quando o MCP virou o centro das atenções da indústria, construímos um servidor MCP completo com 126 ferramentas geradas. O resultado mostrou um ponto importante para quem está implementando integrações com agentes: mais ferramentas não significam, automaticamente, melhor capacidade operacional.
O hype do MCP
No início de 2025, o MCP, ou Model Context Protocol, tornou-se uma das principais respostas da indústria para conectar agentes de IA a ferramentas externas e fontes de dados.
A Anthropic promoveu o protocolo. Cursor, Claude Code, Antigravity, vários IDEs com agentes e muitos produtos SaaS passaram a adotá-lo.
A pergunta que quase todo produto com API começou a receber foi:
“Vocês têm MCP?”
Para a Apidog, a resposta parecia óbvia: sim, deveríamos expor nossas capacidades via MCP.
Por que o MCP parecia a resposta certa
A Apidog já reunia várias capacidades de desenvolvimento de APIs:
- 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
- Importação e exportação
- Colaboração por branch
- Outros fluxos do ciclo de vida de API
Se agentes se tornariam uma nova interface de uso de software, fazia sentido disponibilizar essas capacidades para eles.
A hipótese inicial era simples:
Mais recursos expostos como ferramentas = agentes mais capazes.
Na prática, esperávamos que agentes pudessem:
- Consultar documentação de API
- Criar casos de teste
- Executar cenários de teste
- Importar e exportar dados de projeto
- Gerenciar ambientes e variáveis
- Colaborar entre branches
Essa hipótese parecia tecnicamente correta. Mas, ao implementar e testar, encontramos limites estruturais.
O que construímos
O Apidog MCP não foi uma demo com poucos endpoints manuais. Construímos um servidor MCP completo.
1. Sistema de sessão
O cliente MCP inicializava uma sessão. O servidor gerava um sessionId e armazenava o estado da sessão no Redis. As chamadas seguintes continuavam usando esse sessionId.
Em termos práticos, não era apenas uma chamada HTTP isolada. Era um sistema de sessão em nível de protocolo.
Um fluxo simplificado seria:
Cliente MCP
-> initialize
Servidor MCP
-> cria sessionId
-> persiste sessão no Redis
Cliente MCP
-> chama ferramentas usando sessionId
Servidor MCP
-> lê estado da sessão
-> executa ferramenta
-> retorna resultado
2. Categorias de ferramentas
Não expusemos apenas alguns endpoints fixos. Organizamos as ferramentas em categorias:
| Categoria | Descrição | Exemplos |
|---|---|---|
| Ferramentas de projeto nativas | Operações em nível de projeto | Resumos de projeto, estruturas de pastas, detalhes de recursos |
| Ferramentas de domínio integradas | Funcionalidades centrais da Apidog | Importação/exportação, detalhes de endpoint, casos de teste, cenários de teste |
| Ferramentas OpenAPI geradas | Convertidas automaticamente a partir de definições OpenAPI | 126 ferramentas com identificadores, caminhos, métodos HTTP e schemas de entrada |
A terceira categoria foi a mais pesada: 126 ferramentas geradas.
Cada ferramenta tinha:
- Identificador único
- Caminho de API
- Método HTTP:
GET,POST,PUT,DELETE, etc. - Schema de entrada com tipos, descrições e enums
- Estrutura de retorno definida
3. Divulgação progressiva
Para evitar expor tudo de uma vez, implementamos uma camada de descoberta dinâmica.
O agente poderia seguir este fluxo:
1. listOpenApiEndpoints
-> lista endpoints/ferramentas disponíveis
2. getOpenApiDetails
-> obtém detalhes OpenAPI de uma ferramenta específica
3. executeOpenApi
-> executa a chamada real pelo ID da ferramenta
A ideia era que o agente primeiro descobrisse as opções, depois carregasse os detalhes necessários e só então executasse a operação.
Na prática, isso reduzia parte da exposição direta, mas não resolvia o problema principal: o agente ainda precisava decidir como navegar pelo conjunto de ferramentas.
O problema: uma parede de ferramentas aleatórias
Considere uma solicitação simples do usuário:
“Ajude-me a adicionar um teste para este endpoint e executar a verificação.”
Do ponto de vista do produto, isso é totalmente viável. A Apidog tem recursos para:
- Encontrar endpoints
- Criar casos de teste
- Executar cenários de teste
- Gerar relatórios
Mas, para o agente, essa solicitação vira uma cadeia de decisões:
| Ponto de decisão | Opções | Incerteza |
|---|---|---|
| Onde começar? | Encontrar o projeto primeiro? Encontrar o endpoint primeiro? | Sem orientação clara |
| O que ler? | Detalhes do endpoint? Casos de teste existentes? | Ambos parecem válidos |
| Como criar? | Usar createTestCase diretamente? Procurar um grupo primeiro? |
Requisito desconhecido |
| Como atualizar? | Chamar uma ferramenta update? Importar passos e reler? |
Fluxo de trabalho oculto |
O problema não era falta de ferramentas. Era o oposto.
Antes de resolver a tarefa do usuário, o agente precisava resolver a tarefa de descobrir qual ferramenta usar.
Isso cria uma parede de ferramentas aleatórias: muitas operações tecnicamente corretas, mas pouca orientação operacional sobre a sequência certa.
Quatro problemas estruturais da abordagem MCP
Com testes reais e feedback interno, identificamos quatro problemas principais.
Problema 1: o custo de descoberta cresce rápido
A Apidog não pode ser resumida em uma dúzia de endpoints.
| Módulo | Operações típicas |
|---|---|
| Endpoints | Listar, obter, criar, atualizar, excluir |
| Schemas | Listar, obter, criar, atualizar, excluir |
| Ambientes | Listar, obter, criar, atualizar, excluir, gerenciar variáveis |
| Mocks | Configurar, habilitar, desabilitar |
| Casos de teste | Listar, obter, criar, atualizar, excluir, duplicar |
| Cenários de teste | Listar, obter, criar, atualizar, excluir, importar passos, executar |
| Suítes de teste | Listar, obter, criar, atualizar, excluir |
| Relatórios | Listar, obter, gerar, baixar |
| Importação/exportação | Múltiplos formatos e opções |
| Branches | Listar, criar, mesclar, excluir |
Quando o número de ferramentas cresce de algumas unidades para dezenas ou centenas, a escolha da ferramenta vira parte relevante do trabalho do modelo.
Tentamos mitigar isso escrevendo instruções nas descrições das ferramentas. Por exemplo:
“Antes de consultar dados de endpoint, confirme o projeto por meio de outra ferramenta, obtenha metadados do projeto por uma terceira ferramenta e só então chame esta ferramenta.”
Isso funciona em conjuntos pequenos. Em conjuntos grandes, a própria description passa a competir pela atenção do modelo.
Quanto mais instruções colocávamos nas descrições:
- Mais tokens eram consumidos
- Maior ficava o contexto inicial
- Menor era a chance de o agente seguir todas as regras corretamente
Problema 2: o schema de negócio invade o contexto
Uma ferramenta MCP não é apenas um nome. Ela carrega:
descriptioninput schema- Parâmetros obrigatórios e opcionais
- Tipos
- Campos aninhados
- Restrições
- Enums
- Estruturas de retorno
- Tratamento de erros
Uma estimativa conservadora:
| Fator | Valor |
|---|---|
| Quantidade de ferramentas | 100+ |
| Média de tokens por ferramenta | ~500 |
| Total em descrições de ferramentas | ~50.000 tokens |
Ou seja:
Uma pergunta de usuário pode ter 50 caracteres, mas o modelo pode precisar carregar dezenas de milhares de tokens de ferramentas antes de começar a trabalhar.
Esse problema não é apenas teórico.
O post oficial do Cursor, Dynamic Context Discovery, mostrou que transformar descrições de ferramentas MCP, sessões de terminal e conversas longas em contexto carregável sob demanda reduziu o consumo de tokens em runtime em 46,9%.
A abordagem do Trae foi mais direta:
- Limite de ferramentas MCP: 40
- Limite de descrição por ferramenta: 8000 caracteres
Durante testes internos, equipes relataram que o Apidog MCP tinha ferramentas que não podiam ser invocadas no Trae. Com contexto limitado, o agente precisava fazer cortes — e ferramentas externas eram candidatas naturais a serem descartadas.
A conclusão prática:
Descrições de ferramentas não podem crescer indefinidamente dentro do contexto do modelo.
Problema 3: sessões de protocolo tornam a execução mais pesada
O servidor Apidog MCP precisava lidar com vários estados de protocolo:
| Estado do protocolo | Descrição |
|---|---|
| Inicialização MCP | Handshake entre cliente e servidor |
Geração de sessionId
|
Identificador único da sessão |
| Armazenamento no Redis | Persistência de estado |
| Conexão e fechamento de transporte | Gerenciamento da conexão |
| Toque de sessão | Mecanismo de keep-alive |
| Exclusão de sessão | Limpeza ao finalizar |
| Resposta JSON ou configuração SSE | Opções de formato de saída |
Para uma chamada isolada, esse custo é aceitável.
Para tarefas de agentes com muitas chamadas, tentativas e exploração, o custo operacional aumenta:
- Mais estado para manter
- Mais pontos de falha
- Mais diferenças entre clientes
- Mais compatibilidade para testar
Durante a implementação, a equipe gastou bastante energia adaptando o servidor a diferentes clientes de agente, como Cursor, Claude Code, Antigravity e Trae.
Mesmo assim, problemas de compatibilidade de protocolo continuavam aparecendo, enquanto o MCP oficial ainda recebia novas correções e versões.
Problema 4: ferramentas atômicas não expressam bem a semântica do produto
Em cenários de teste da Apidog, a estrutura não é apenas um array de steps.
Um cenário pode envolver:
| Componente | Complexidade |
|---|---|
| Importação | Passos de endpoints ou casos existentes |
| Leitura de retorno | Obter a estrutura completa após importar |
| Casos internos | Requisições HTTP embutidas nos passos |
| Pré/pós-processadores | Scripts antes ou depois das requisições |
| Asserções | Regras de validação de resposta |
| Extração de variáveis | Captura de valores das respostas |
| Ambiente de execução | Seleção de ambiente e variáveis |
| Verificação de relatório | Checagem dos resultados de teste |
Quando isso é dividido em muitas ferramentas MCP atômicas, o agente precisa orquestrar o fluxo sozinho.
Exemplo de perguntas que o agente passa a ter que responder:
- Por que a importação precisa de leitura de retorno?
- Por que 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?
Essas regras são semântica interna do produto. Esperar que o modelo deduza tudo apenas a partir de ferramentas atômicas não é robusto.
Na prática, a equipe precisou adicionar camadas de conversão e adaptação para que endpoints atômicos servissem melhor ao modelo. Isso aumentou o custo de engenharia e manutenção.
A causa raiz
Os quatro problemas têm a mesma origem:
O MCP é bom para conectar ferramentas. Mas tarefas complexas de P&D precisam de mais do que conexão: precisam de processos de engenharia executáveis.
| Ponto forte do MCP | Limitação do MCP |
|---|---|
| Conexão padronizada | Não expressa fluxo de trabalho completo |
| Protocolo unificado | Não guia sequência operacional |
| Exposição de ferramentas | Não impõe validação |
| Descoberta dinâmica | Não fornece julgamento de engenharia |
Para produtos simples, com poucas operações bem definidas, o MCP funciona bem. O agente consegue escolher uma ferramenta, chamá-la e interpretar o resultado.
Para produtos como a Apidog — com muitos módulos, centenas de operações, estruturas aninhadas, fluxos ocultos e semântica específica — o MCP sozinho tende a criar uma parede de ferramentas.
O que aprendemos
| Lição | Implicação prática |
|---|---|
| Mais ferramentas ≠ melhor capacitação de agentes | A contagem de ferramentas também é custo |
| Descrições competem por contexto | 500 tokens × 100 ferramentas = 50.000 tokens de carga |
| Sessões adicionam overhead | Cada chamada carrega gerenciamento de estado |
| Ferramentas atômicas exigem conhecimento do produto | O agente precisa entender detalhes internos para orquestrar |
| Conexão ≠ execução | MCP conecta; CLI + SKILL executa processos |
Como aplicar isso ao projetar ferramentas para agentes
Se você está expondo seu produto para agentes, use estes critérios antes de criar dezenas de ferramentas:
1. Comece pelo fluxo, não pelo endpoint
Em vez de mapear diretamente:
1 endpoint = 1 ferramenta
Modele primeiro os fluxos reais:
Criar teste para endpoint
-> localizar projeto
-> localizar endpoint
-> gerar caso de teste
-> configurar ambiente
-> executar
-> validar relatório
Depois decida quais partes devem ser ferramentas e quais devem ser abstraídas pelo sistema.
2. Reduza decisões ambíguas
Se duas ferramentas parecem igualmente corretas para o agente, há risco de erro.
Prefira comandos ou capacidades que carreguem intenção explícita:
apidog test create-from-endpoint --endpoint-id ep_123
apidog test run --scenario-id scn_456 --env staging
Em vez de obrigar o agente a combinar várias operações atômicas sem contexto.
3. Não coloque toda a regra de negócio em description
Descrições ajudam, mas não devem ser o único lugar onde o fluxo correto existe.
Evite depender de instruções longas como:
Antes de chamar esta ferramenta, chame A, depois B, depois verifique C,
exceto quando o projeto estiver em modo X...
Quando o fluxo fica assim, ele provavelmente deveria virar um comando, workflow ou skill executável.
4. Trate tokens como orçamento de execução
Cada ferramenta adiciona custo ao contexto.
Antes de expor uma nova ferramenta, pergunte:
- Ela será usada com frequência?
- Ela reduz ou aumenta a ambiguidade?
- O agente consegue usá-la sem conhecer detalhes internos?
- Ela substitui um fluxo inteiro ou apenas adiciona mais uma operação atômica?
5. Separe conexão de execução
Use MCP quando o objetivo for conectar capacidades a agentes.
Mas, para tarefas de engenharia com sequência, validação e qualidade, considere uma camada executável mais opinativa, como CLI + SKILL.
A virada: de MCP para CLI + SKILL
A pergunta que surgiu foi:
Se o MCP não é suficiente para capacitar agentes em tarefas complexas, o que é?
Não abandonamos o valor do MCP. Ele oferece conexão padronizada, o que é importante para o ecossistema.
Mas precisávamos de algo que pudesse:
- Expressar fluxos de trabalho, não apenas ferramentas
- Guiar agentes por sequências corretas
- Validar antes de escrever
- Impor gates de qualidade de engenharia
- Absorver a complexidade no sistema, não no contexto do modelo
A resposta foi: CLI + SKILL.
No próximo post, Por Que Desenvolvemos um Novo Apidog CLI, veremos a mudança arquitetural: a complexidade sai do contexto do modelo e passa para o sistema de engenharia.
Principais conclusões
- O MCP virou uma resposta padrão para conectar agentes a ferramentas.
- Construímos 126 ferramentas MCP achando que mais ferramentas significariam mais capacidade.
- Testes reais revelaram quatro problemas: descoberta, contexto, sessão e semântica do produto.
- O MCP conecta ferramentas, mas tarefas complexas precisam de processos executáveis.
- Em sistemas grandes, mais ferramentas podem aumentar o custo cognitivo do agente.
- Para fluxos de engenharia, CLI + SKILL oferece uma forma mais orientada a execução.
Baixe o 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 com agentes de IA.
Top comments (0)