MCP vs CLI se resume a quando o seu agente paga por uma ferramenta. Um servidor MCP envia o nome, a descrição e o JSON Schema de cada ferramenta para o modelo antes mesmo de você digitar qualquer coisa. Uma CLI não custa nada até que o agente a execute e leia seu --help ou a saída. Em uma configuração medida, quatro servidores MCP comuns adicionaram 11.923 tokens de definições de ferramentas; a skill da Apidog CLI adicionou 112.
Essa diferença é toda a história por trás de dois posts no Dev.to nesta semana. Um desenvolvedor digitou “Run tests” em um agente de programação e viu 28.400 tokens de entrada na primeira requisição, sem arquivos anexados e sem histórico. O culpado eram sete servidores MCP. Outro argumentou que construir com MCP é extremamente simples, e que as partes difíceis (autenticação, aprovações, chamadas duplicadas) começam logo depois que a demo funciona.
Este artigo se concentra em uma única pergunta: quanto as definições de ferramentas custam à sua janela de contexto, e quando uma CLI chamada sob demanda pelo agente custa menos? Se o seu problema são respostas enormes de ferramentas, leia o artigo complementar sobre como reduzir respostas de API infladas.
Por que servidores MCP consomem tokens da janela de contexto
Um servidor MCP anuncia suas ferramentas por meio do método tools/list. Segundo a especificação de ferramentas do MCP, cada ferramenta carrega um name, uma description e um inputSchema (um JSON Schema para seus argumentos). Para que o modelo escolha uma ferramenta, o cliente precisa colocar essas definições na requisição. Em uma configuração clássica, isso acontece a cada turno de cada conversa, independentemente de o agente chamar a ferramenta ou não.
Então o custo cresce com três fatores:
- Quantidade de ferramentas. Uma integração completa com o GitHub pode expor dezenas de ferramentas.
- Profundidade do schema. Objetos aninhados, enums e descrições longas se transformam em tokens.
- Turnos. Um loop de agente envia as definições novamente a cada etapa.
O post do necoz coloca números nisso: uma pilha com 52 ferramentas custou 24.600 tokens de schema no turno 1, contra 640 tokens para uma configuração com 4 ferramentas, e cerca de 246.000 tokens ao longo de um loop de 10 etapas. Trate esses números como a medição de um único desenvolvedor, não como um benchmark. O cache de prompt reduz o custo em dólares das definições repetidas, mas os tokens ainda ocupam a janela e competem com o seu código pela atenção do modelo.
Há também um custo de qualidade. A documentação de busca de ferramentas da Anthropic diz que uma configuração multi-servidor com GitHub, Slack, Sentry, Grafana e Splunk “pode consumir ~55 mil tokens em definições antes de Claude fazer qualquer trabalho”, e que a precisão de seleção de ferramentas de Claude degrada quando você passa de 30 a 50 ferramentas disponíveis.
Tokens de definições de ferramentas MCP: uma medição que você pode repetir
Em 16/11/2026, iniciei cinco servidores MCP localmente via stdio, enviei initialize e tools/list a partir de um script Node de 30 linhas e contei os tokens do name, da description e do inputSchema de cada ferramenta.
Uma ressalva desde já: contei usando a codificação o200k_base do tiktoken da OpenAI porque ela funciona offline. Claude, Gemini e outros modelos usam seus próprios tokenizadores, então seus números diferirão por uma margem. O que importa aqui são as proporções entre as configurações.
| Servidor MCP (versão) | Ferramentas | Tokens de definição | Média por ferramenta |
|---|---|---|---|
@playwright/mcp 0.0.85 |
25 | 4.634 | 185 |
@modelcontextprotocol/server-filesystem 2.3.0 |
16 | 3.281 | 205 |
@modelcontextprotocol/server-memory 2.1.1 |
9 | 2.013 | 224 |
@modelcontextprotocol/server-everything 2.3.0 |
16 | 1.995 | 125 |
| Os quatro juntos | 66 | 11.923 | 181 |
apidog-mcp-server 0.0.18 |
3 | 291 | 97 |
Quatro servidores comuns custaram cerca de 12.000 tokens antes de o agente ler um único arquivo.
A última linha é o contraponto útil. O servidor MCP da Apidog expõe três ferramentas restritas (ler a especificação OpenAPI do projeto, ler arquivos $ref, atualizar a especificação), por isso custa apenas 291 tokens. Quem dita a conta é a quantidade de ferramentas e a profundidade do schema, não o protocolo.
Quanto ao lado da CLI, medi o que um agente realmente lê ao usar a Apidog CLI 2.2.12:
| Texto da CLI | Quando entra no contexto | Tokens |
|---|---|---|
| Descrição da skill da Apidog CLI (frontmatter) | Toda sessão, como listagem de skills | 112 |
| Corpo da skill da Apidog CLI | Somente quando a tarefa corresponde | 1.189 |
apidog --help |
Somente quando o agente o executa | 668 |
apidog test-case --help |
Somente quando o agente o executa | 511 |
apidog run --help |
Somente quando o agente o executa | 1.036 |

O custo permanente da via CLI é de 112 tokens. Mesmo que o agente carregue a skill completa e leia três páginas de ajuda, ele chega perto de 3.500 tokens, e apenas na conversa que precisa disso.
MCP vs CLI: a comparação de custo em tokens
| Servidor MCP (definições carregadas antecipadamente) | CLI chamada pelo shell | |
|---|---|---|
| Custo antecipado | O schema de cada ferramenta, a cada turno | Zero, ou uma descrição curta de skill |
| Descoberta | tools/list estruturado |
Texto de --help, lido quando necessário |
| Saída | O que a ferramenta retornar | O que o comando imprimir (você pode filtrar) |
| Funciona em vários clientes | Qualquer cliente MCP, uma única configuração | Qualquer agente com uma ferramenta de shell |
| Argumentos tipados | Sim, via JSON Schema | Flags; arquivos de payload validados separadamente |
| Autenticação e permissões | Responsabilidade do servidor (OAuth para servidores HTTP remotos) | Seu login local e permissões do shell |

A CLI vence no custo antecipado porque o agente já tem uma ferramenta de shell. Executar apidog endpoint list --project 123 usa a ferramenta Bash que ele carregaria de qualquer forma. A via MCP vence quando você precisa da mesma capacidade em vários clientes sem escrever uma integração para cada um, que é o ponto que Sylwia Lask levanta: MCP não é um substituto do REST, é uma forma padrão para clientes de IA descobrirem e chamarem ferramentas.
Seu cliente pode já adiar ferramentas MCP
Antes de remover todos os servidores, verifique o que o seu agente faz. O custo acima pressupõe que as definições são carregadas antecipadamente. Alguns clientes já não fazem isso por padrão.
A documentação de MCP do Claude Code diz que a busca de ferramentas vem habilitada por padrão: “Apenas nomes de ferramentas e instruções do servidor são carregados no início da sessão”, e as definições completas são carregadas quando Claude as busca. Você controla isso com ENABLE_TOOL_SEARCH:
- não definido ou
true: as ferramentas MCP são adiadas e carregadas sob demanda auto: as ferramentas são carregadas antecipadamente enquanto suas definições somarem menos de 10% da janela de contextoauto:N: o mesmo, com sua própria porcentagemfalse: todas as ferramentas MCP são carregadas antecipadamente
Duas exceções importam. Modelos anteriores ao Opus 4 e ao Sonnet 4 carregam as ferramentas MCP antecipadamente de qualquer forma, e um servidor configurado com alwaysLoad: true ignora o adiamento. Execute /context no Claude Code para ver quais ferramentas estão marcadas como adiadas. Na API do Claude em si, a mesma ideia é a ferramenta de busca de ferramentas: você define defer_loading: true nas ferramentas que não devem ser carregadas antecipadamente, e a Anthropic diz que isso normalmente reduz os tokens de definição em mais de 85%.
O adiamento resolve o custo das definições, não o custo da saída: o Claude Code avisa quando uma ferramenta MCP retorna mais de 10.000 tokens e limita a saída a 25.000 por padrão (MAX_MCP_OUTPUT_TOKENS). Novato no protocolo? Comece por o que é o MCP e por que ele importa para APIs.
Quando usar MCP ou CLI para trabalho com APIs
Para design, testes e documentação de APIs, use esta divisão:
- Use uma CLI quando a tarefa é algo que você executaria em um terminal de qualquer forma: listar endpoints, exportar um arquivo OpenAPI, criar e executar um caso de teste, rodar uma suíte em CI. O agente só paga pelo texto de ajuda quando precisa dele, e você pode direcionar a saída pelo
jqou usar--reporterspara mantê-la curta. - Use um servidor MCP restrito quando o agente precisar de acesso de leitura estruturado a cada turno, como ler sua especificação OpenAPI enquanto escreve código cliente. Três ferramentas por 291 tokens é um preço justo.
- Evite deixar cinco ou mais servidores habilitados globalmente em todos os projetos. Essa é a configuração que produziu o “Run tests” de 28.400 tokens.
Qualquer que seja a sua escolha, os avisos de Sylwia continuam valendo: uma ferramenta que escreve dados precisa de verificações de permissão no servidor, de uma etapa de aprovação humana para ações arriscadas e de detecção de duplicatas para que uma nova execução não crie o mesmo registro duas vezes.
Deixe seu agente de programação comandar a Apidog CLI
Este é o caminho da CLI para trabalho com APIs, com seu agente de programação fazendo a digitação. Instale a CLI, faça login uma vez e adicione a skill do agente:
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
Você também pode dizer ao agente “Read https://apidog.com/apidog-cli-installation-guide.md and set up Apidog CLI”, e ele seguirá o guia de instalação amigável para agentes.
Depois, dê a ele um único prompt:
In Apidog project 123, list the endpoints, export the spec as OpenAPI 3.1 to
./openapi.json, then create a test case for GET /users/{id} that asserts a 200
status and an id field, run it against environment 456 and summarize failures.
Read --help for each command before using it. Print only the lines you need.
O agente lê a ajuda conforme avança, valida seu JSON e então executa o caso:
apidog endpoint list --project 123 --page 1 --page-size 500
apidog export --project 123 --format openapi --oas-version 3.1 --output ./openapi.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123 --file case.json
apidog run --test-case <caseId> --project 123 -e 456 -r cli,json
Cada comando retorna JSON estruturado, geralmente com agentHints.nextSteps, para que o agente saiba o que executar em seguida sem carregar um schema para cada ação possível. A mesma linha apidog run ... -r junit entra direto no CI, como mostra o guia de pipeline CI/CD da Apidog CLI. Para um passo a passo com o Claude Code, veja Apidog CLI no Claude Code, e para economias medidas em chamadas de ferramentas, 30% menos chamadas de ferramentas, 25% menos tokens.
Para conhecer todos os grupos de comandos antes de começar, leia a página da Apidog CLI.
Como reduzir o custo de tokens do MCP hoje
- Execute
/contextno Claude Code (ou o equivalente no seu cliente) e anote o total de definições de ferramentas. - Mova os servidores que você não precisa da configuração global para a configuração do projeto.
- Ative o carregamento adiado (
ENABLE_TOOL_SEARCHno Claude Code). - Substitua servidores amplos por uma CLI mais uma skill curta para trabalho de terminal.
- Nos servidores que você constrói, mantenha poucas ferramentas e descrições curtas.
FAQ
As ferramentas MCP consomem tokens se o agente nunca as chama? Em um cliente que carrega as definições antecipadamente, sim. O nome, a descrição e o schema de entrada de cada ferramenta entram em cada requisição. Clientes com carregamento adiado, como o Claude Code com a busca de ferramentas ativada, enviam apenas os nomes das ferramentas até que uma seja necessária.
Quantos tokens um servidor MCP consome? Depende da quantidade de ferramentas e da profundidade do schema. Na minha medição, o @playwright/mcp usou 4.634 tokens para 25 ferramentas e o servidor MCP da Apidog usou 291 para 3 ferramentas, contados com o tokenizador o200k_base.
Uma CLI é sempre mais barata que o MCP para agentes de IA? No custo antecipado, quase sempre, porque o agente reutiliza sua ferramenta de shell. Por chamada, uma CLI ainda pode inundar o contexto se o agente imprimir um payload grande, então filtre a saída em ambos os casos.
O cache de prompt resolve o inchaço de contexto do MCP? Ele reduz o preço das definições repetidas. Mas não libera a janela de contexto, e o modelo ainda presta atenção nesses tokens a cada turno.
Devo parar de usar servidores MCP? Não. Use servidores restritos para acesso estruturado a cada turno e para compartilhar uma mesma capacidade entre clientes. Mova o trabalho de API com formato de terminal, como exportações e execuções de testes, para uma CLI.
