Reduzir o consumo de tokens do MCP: como cortamos 60% das nossas definições de ferramentas

Em 27 de outubro, um usuário pagante cancelou a assinatura do AgentsRoom e deu os tokens como motivo. Antes de discutir, medimos o que nosso app acrescenta a cada agente que ele inicia.

O maior número não estava onde esperávamos. Nossas instruções de inicialização eram pequenas. As ferramentas MCP que entregamos a cada agente (backlog, memória do projeto, correio entre agentes, terminais, SSH, bancos de dados e o resto) eram 191 ferramentas e cerca de 380 KB de JSON. A uns 4 bytes por token, isso dá cerca de 95.000 tokens de definições de ferramentas. Uma semana antes eram 78.000. Ninguém tinha decidido isso: cada ferramenta nova simplesmente tinha acrescentado seu parágrafo.

Desenvolvemos o AgentsRoom, um app desktop que roda Claude Code, Codex e outros CLIs de código lado a lado e entrega a eles essas ferramentas. Isto é o que medimos, o que cortamos sem remover uma única ferramenta e o controle que impede que o problema volte. Você pode aplicar tudo isso aos seus próprios servidores MCP.

A resposta curta

• Uma definição de ferramenta é JSON que o modelo pode ler a cada requisição: nome, descrição, esquema de entrada. Conte cerca de 4 bytes por token.
• Se você paga isso a cada turno ou não depende do CLI. O Claude Code adia as ferramentas MCP por padrão e carrega uma definição quando precisa dela. Alguns CLIs enviam todos os esquemas com cada requisição.
• Meça antes de cortar. /context no Claude Code, ou um script de 40 linhas que pede a lista de ferramentas a qualquer servidor.
• Encurte o texto, mantenha as ferramentas. Uma descrição diz o quê e quando. O manual passa para um documento que o agente lê quando precisa. As nossas foram de cerca de 95.000 para cerca de 38.000 tokens, 2,5 vezes menos.
• Coloque um teto no build. Sem ele, as definições voltam a crescer sozinhas.

Quanto custa uma definição de ferramenta, e quem paga

Quando um cliente MCP se conecta a um servidor, ele pede a lista de ferramentas. Cada entrada é um nome, uma descrição escrita para o modelo e um esquema JSON dos parâmetros. O cliente transforma essa lista em definições de ferramentas enviadas ao modelo: é assim que o modelo sabe que a ferramenta existe e como chamá-la.

Então cada palavra de uma descrição é entrada que o modelo lê. Com que frequência ele lê depende do cliente:

• O Claude Code adia as ferramentas MCP por padrão. A documentação dele, lida em 3 de novembro de 2026 com o Claude Code 2.1.314 instalado, diz que no início da sessão só são carregados os nomes das ferramentas e as instruções dos servidores, e que uma definição é carregada pela busca de ferramentas quando o Claude precisa daquela ferramenta. Com ENABLE_TOOL_SEARCH=false, com auto abaixo de um limite de 10% da janela de contexto, em modelos anteriores ao Claude Opus 4 e ao Sonnet 4, ou para um servidor marcado como alwaysLoad, as definições são carregadas desde o início.
• Outros CLIs fazem diferente. No nosso próprio teste de 28 de outubro, com um agente instruído a responder "OK": o Claude Code começava em 67.500 tokens com nossas ferramentas adiadas, o Codex CLI 0.164 começava em 25.000 tokens e não enviava nossos esquemas em um único bloco, e o OpenCode carregava nossas 175 ferramentas mais 19 ferramentas de navegador na conexão e as enviava com cada requisição. Mesmo servidor, contas muito diferentes.

O cache de prompt suaviza o custo quando a lista de ferramentas não muda: depois da primeira requisição, um prefixo estável é lido do cache por uma fração do preço de entrada. Ele não devolve o espaço. As definições continuam ocupando a janela de contexto a cada requisição, ao lado do seu código e da sua conversa. E o modo adiado tem um custo próprio: uma etapa de busca antes do primeiro uso de cada ferramenta.

Meça as suas em dois minutos

No Claude Code, rode /context. Ele divide a janela por origem e marca as ferramentas MCP adiadas ou carregadas sob demanda. Rode em uma sessão nova do seu projeto, antes de digitar qualquer coisa, e você vê quanto sua configuração custa antes de o trabalho começar.

Para qualquer servidor e qualquer CLI, pergunte direto ao servidor. Um servidor MCP via stdio fala JSON-RPC, uma mensagem por linha: você envia initialize, depois tools/list, e mede o que volta. Este script faz exatamente isso, com Node e sem nenhuma dependência:

// Usage: node mcp-tool-cost.mjs <command that starts the server> [args...]
import { spawn } from 'node:child_process';

const [cmd, ...args] = process.argv.slice(2);
const server = spawn(cmd, args, { stdio: ['pipe', 'pipe', 'ignore'], shell: process.platform === 'win32' });
const tools = [];
let buffer = '';

const send = (msg) => server.stdin.write(JSON.stringify({ jsonrpc: '2.0', ...msg }) + '\n');
const listTools = (cursor) => send({ id: 2, method: 'tools/list', params: cursor ? { cursor } : {} });

server.stdout.on('data', (chunk) => {
  buffer += chunk;
  let end;
  while ((end = buffer.indexOf('\n')) >= 0) {
    const line = buffer.slice(0, end).trim();
    buffer = buffer.slice(end + 1);
    if (line) handle(JSON.parse(line));
  }
});

function handle(msg) {
  if (msg.id === 1) {
    send({ method: 'notifications/initialized' });
    listTools();
  } else if (msg.id === 2) {
    tools.push(...msg.result.tools);
    if (msg.result.nextCursor) listTools(msg.result.nextCursor);
    else { report(); server.kill(); }
  }
}

function report() {
  const rows = tools
    .map((tool) => ({ name: tool.name, bytes: Buffer.byteLength(JSON.stringify(tool)) }))
    .sort((a, b) => b.bytes - a.bytes);
  const total = rows.reduce((sum, row) => sum + row.bytes, 0);
  for (const row of rows.slice(0, 10)) {
    console.log(`${String(row.bytes).padStart(7)} bytes  ~${Math.round(row.bytes / 4)} tokens  ${row.name}`);
  }
  console.log(`${rows.length} tools, ${total} bytes, about ${Math.round(total / 4)} tokens`);
}

send({
  id: 1,
  method: 'initialize',
  params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'tool-cost', version: '1.0.0' } },
});

Rode com o mesmo comando que seu CLI usa para iniciar o servidor, por exemplo node mcp-tool-cost.mjs npx -y @playwright/mcp@latest. Ele mostra as dez ferramentas mais pesadas e o total. O que obtivemos em 3 de novembro de 2026:

Quatro bytes por token é uma estimativa, boa o bastante para comparar servidores e ver uma tendência, não para prever uma conta. Os tokenizadores reais variam com o modelo e o texto, como vimos quando contamos 3,8 bilhões dos nossos próprios tokens.

Os servidores de arquivos acima são razoáveis. O problema é a soma: cinco servidores desse tamanho já dão 20.000 tokens, antes mesmo de um servidor como o nosso.

O que cortamos, e o que não tocamos

A regra que definimos: nenhuma ferramenta removida, nenhum parâmetro removido, nenhum valor permitido nem campo obrigatório removido. Os agentes tinham que manter todas as capacidades. Só o texto podia mudar.

1. Uma descrição de ferramenta diz o quê e quando, em uma a três frases. Não como. O como era onde estavam os bytes: regras, valores padrão, casos-limite, exemplos, avisos escritos depois que um agente usou a ferramenta errado uma vez.
2. Um parâmetro ganha uma frase, ou nada quando seu nome, seu tipo e sua lista de valores permitidos já dizem tudo. Os parâmetros que se repetem entre ferramentas (project, author, ids de ticket) receberam a mesma frase padrão em todo lugar.
3. O manual mudou de lugar, não foi apagado. Cada família de ferramentas tem um arquivo de instruções que o agente lê antes da primeira chamada àquela família. Para a nossa maior ferramenta, a que salva uma equipe de agentes, a referência completa dos campos agora é devolvida por uma chamada de ferramenta quando o agente pede, em vez de viajar dentro do esquema.
4. Uma segunda passada verificou cada fato. Cada frase removida de uma descrição foi procurada nos arquivos de instruções, e colocada lá quando faltava.

Alguns dos resultados, em bytes de JSON por ferramenta:

No total, 380 KB viraram 152 KB. Treze ferramentas passavam de 4 KB; quatro ainda passam, por causa da quantidade de campos que carregam. A ideia por trás de toda a passada: para escolher uma ferramenta, o modelo precisa saber que ela existe e quando chamá-la. Os detalhes podem esperar o momento em que ele a usa.

Se você escreve um servidor MCP, o Claude Code dá mais um motivo. Ele corta em 4.096 caracteres uma descrição de ferramenta carregada desde o início, e quando compara uma busca com uma descrição, só lê a parte dentro desse limite. Qualquer coisa importante depois desse ponto pode nunca ser vista.

O mesmo truque para um arquivo de inicialização

Os esquemas de ferramentas não são o único custo fixo. Nossos agentes também leem um arquivo de instruções sobre as ferramentas antes de usá-las, e ele tinha crescido até 57,7 KB, cerca de 14.000 tokens, lidos inteiros a cada início e a cada retomada. Um usuário relatou que um agente Codex retomado atingia seu limite de contexto de trabalho em poucos minutos.

A correção seguiu a mesma ideia. O arquivo virou um índice de cerca de 11 KB: as regras que valem para todas as ferramentas, e uma linha por família de ferramentas apontando para o próprio arquivo. Os 31 arquivos de família só são lidos antes da primeira chamada àquela família. O texto deles não mudou, palavra por palavra. Um agente que só mexe no backlog nunca lê a seção sobre bancos de dados.

Isso também funciona para qualquer CLAUDE.md ou AGENTS.md longo: deixe no arquivo sempre carregado o que toda tarefa precisa, e coloque um link para o resto. Falamos mais sobre isso no nosso guia sobre AGENTS.md e arquivos de contexto.

Um orçamento que faz o push falhar

O número que mais nos preocupava não era 95.000. Era 78.000 uma semana antes. Cada ferramenta acrescentava um parágrafo, cada parágrafo era razoável, e a soma cresceu 20% em sete dias.

Então o tamanho virou uma verificação do build. Um arquivo JSON guarda o orçamento:

{
  "totalBytes": 160000,
  "perToolBytes": 4000,
  "oversized": {
    "teams_save": 9791,
    "triggers_save": 4071,
    "backlog_update": 4253,
    "backlog_create": 4399
  }
}

Um script inicia nossos servidores MCP em um sandbox, pede a cada um suas ferramentas, mede JSON.stringify(tool) em bytes e sai com erro quando o total passa de totalBytes ou quando uma ferramenta passa de perToolBytes. As quatro ferramentas que já eram grandes demais estão listadas com seu tamanho: uma catraca. Elas podem encolher, nunca crescer, e quando uma encolhe, o script pede para baixar o número. Ele roda antes de cada push e no build de release. Subir o teto é possível, mas é uma decisão escrita no arquivo, não um jeito de fazer a verificação passar.

Em 3 de novembro, seis dias depois, a mesma verificação marca 203 ferramentas e 159.957 bytes: doze ferramentas acrescentadas, 43 bytes abaixo do teto. A próxima ferramenta vai ter que abrir espaço para si mesma. É exatamente para isso que serve a verificação.

Desative o que você não usa

O token mais barato é o da ferramenta que seu agente nunca vê.

• Limite os servidores aos projetos que precisam deles. Um servidor declarado no nível do usuário segue você em cada repositório. No Claude Code, um .mcp.json de projeto o mantém onde ele é útil.
• Reserve alwaysLoad para um punhado de ferramentas. A documentação do Claude Code diz isso com todas as letras: cada ferramenta carregada desde o início consome contexto que de outra forma estaria disponível para a sua conversa.
• Fique de olho no que os resultados das ferramentas acrescentam, não só nas definições. Uma ferramenta que devolve uma página ou uma tabela inteira pode custar mais em uma chamada do que sua definição custa o dia inteiro.

No AgentsRoom, Configurações > Ferramentas do AgentsRoom lista cada família das nossas ferramentas com o peso dela, e você pode desativar uma família ou uma única ferramenta, para todos os projetos, um projeto, uma pasta ou um único agente. Uma ferramenta desativada nem é apresentada ao agente, então não custa contexto nenhum. A página AgentsRoom MCP descreve as ferramentas, e o rastreio da sessão mostra o que encheu o contexto de um agente, ferramentas MCP incluídas, ordenado por tamanho.

O que não mudamos

Dois outros custos saíram da mesma medição, e nós os deixamos como estavam, de propósito.

• O brief de inicialização que diz a cada agente seu papel e como relatar seu status: uma mediana de cerca de 5.000 tokens para o Claude, cerca de 2,5% de uma janela de 200.000 tokens, e lido do cache a partir da segunda requisição.
• O arquivo de status que cada agente escreve no fim de um turno: medido em 71 transcrições locais do Claude, cerca de 2,5% dos tokens de contexto.

Reduzir qualquer um dos dois teria economizado menos de 3% da janela e colocado em risco a qualidade do trabalho dos agentes. As definições de ferramentas eram 95.000 tokens. Foi ali que gastamos o tempo.

Perguntas que as pessoas realmente fazem

Quantos tokens as ferramentas MCP consomem?

Cada ferramenta custa sua definição inteira: nome, descrição e esquema de entrada, enviados como JSON. Uma regra aproximada é 4 bytes por token. Medido em 3 de novembro de 2026: o servidor filesystem oficial lista 14 ferramentas por cerca de 3.100 tokens, o Playwright MCP 25 ferramentas por cerca de 5.300. As ferramentas do AgentsRoom pesavam cerca de 95.000 tokens antes de as encurtarmos, cerca de 40.000 hoje.

O Claude Code carrega todas as ferramentas MCP na janela de contexto?

Não por padrão. A busca de ferramentas do Claude Code (tool search) adia as definições das ferramentas MCP: no início da sessão só são carregados os nomes das ferramentas e as instruções dos servidores, e o Claude carrega uma definição quando precisa daquela ferramenta. ENABLE_TOOL_SEARCH=false, um modelo anterior ao Claude Opus 4 e ao Sonnet 4, ou um servidor marcado como alwaysLoad colocam as definições de volta no contexto desde o início.

Os servidores MCP reduzem o consumo de tokens?

Podem reduzir, quando uma ferramenta devolve uma resposta curta em vez de algo que o agente leria inteiro, como uma consulta a um banco de dados em vez de um dump completo. Mas as definições custam contexto, e os resultados também: o Claude Code avisa quando um resultado MCP passa de 10.000 tokens e o corta em 25.000 por padrão. Um servidor MCP só economiza tokens quando seus resultados são menores do que aquilo que ele substitui.

Como vejo quanto contexto minhas ferramentas MCP ocupam?

No Claude Code, rode /context: ele divide o contexto por origem e marca as ferramentas MCP adiadas. Para qualquer servidor e qualquer CLI, peça ao servidor a lista de ferramentas e meça o JSON, que é o que faz o script de 40 linhas deste artigo.

O que faz uma boa descrição de ferramenta MCP?

De uma a três frases que dizem o que a ferramenta faz e quando chamá-la, com as palavras que um agente buscaria logo no começo. Um parâmetro ganha uma frase, ou nada quando seu nome, seu tipo e seus valores permitidos já dizem tudo. Regras, casos-limite e exemplos longos vão para um documento que o agente lê quando precisa. De qualquer forma, o Claude Code corta em 4.096 caracteres uma descrição carregada desde o início.

Como impedir que as definições de ferramentas voltem a crescer?

Dê a elas um orçamento que o build possa verificar. Mantemos um arquivo JSON com um teto total e um teto por ferramenta, um script que inicia nossos servidores MCP, mede cada ferramenta e sai com erro acima de qualquer um dos dois limites, e rodamos esse script antes de cada push. Ferramentas que já eram grandes demais podem encolher, nunca crescer.

Resumindo

Suas ferramentas MCP são texto que o modelo lê, e ninguém revisa esse texto como revisa código. Meça uma vez: /context no Claude Code, ou o script acima para qualquer servidor. Depois faça cada descrição dizer o quê e quando, mova o como para um arquivo que o agente lê quando precisa, e coloque um número no seu build para que nada volte a crescer sem ninguém ver.

Fomos de cerca de 95.000 para cerca de 38.000 tokens sem remover nenhuma ferramenta. Se você roda vários agentes com as mesmas ferramentas, o AgentsRoom é grátis para baixar, e a página Servidores MCP mostra como declarar um servidor uma única vez para todos os CLIs e projetos.