MCP vs CLI: Por que servidores MCP consomem sua janela de contexto

MCP vs CLI para trabalho com APIs: quatro servidores MCP carregaram 11.923 tokens de definições de ferramentas antes mesmo do primeiro prompt. Veja quando uma CLI que seu agente aciona sob demanda custa menos.

Medy Evrard

16 novembro 2026

MCP vs CLI: Por que servidores MCP consomem sua janela de contexto

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Explorar Apidog Enterprise

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:

  1. Quantidade de ferramentas. Uma integração completa com o GitHub pode expor dezenas de ferramentas.
  2. Profundidade do schema. Objetos aninhados, enums e descrições longas se transformam em tokens.
  3. 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
Gráfico de barras dos tokens medidos de definições de ferramentas: Playwright MCP 4.634, Filesystem MCP 3.281, Memory MCP 2.013, Everything MCP 1.995, os quatro servidores juntos 11.923, contra 112 para a descrição da skill da Apidog CLI e 668 para apidog --help lido sob demanda

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
Diagrama comparando o carregamento antecipado do MCP, em que muitos cartões de JSON schema preenchem a maior parte da janela de contexto antes do prompt, com o carregamento sob demanda da CLI, em que o agente executa apidog --help apenas quando precisa e a janela de contexto permanece quase vazia

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:

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:

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

  1. Execute /context no Claude Code (ou o equivalente no seu cliente) e anote o total de definições de ferramentas.
  2. Mova os servidores que você não precisa da configuração global para a configuração do projeto.
  3. Ative o carregamento adiado (ENABLE_TOOL_SEARCH no Claude Code).
  4. Substitua servidores amplos por uma CLI mais uma skill curta para trabalho de terminal.
  5. 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.

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs