Você conectou um MCP server ao Claude Code. Pediu para ele analisar o schema do seu banco de dados. O server devolveu 80 mil caracteres de tabelas, relações e constraints. O Claude Code mostrou 700.
Não deu erro. Não avisou. Simplesmente cortou. E o modelo seguiu respondendo como se tivesse visto tudo — só que não viu. A migração que ele sugeriu ignorou 3 tabelas de auditoria, 2 foreign keys compostas e uma constraint que existia desde 2019.
Isso não é um cenário hipotético. É o que acontece toda vez que um MCP server retorna um resultado maior que o threshold padrão de persistência do Claude Code. O resultado é salvo em disco, truncado na conversa, e o modelo trabalha com dados incompletos. Na minha experiência com 300+ software houses, esse tipo de truncamento silencioso é o bug mais caro que ninguém investiga — porque tudo parece funcionar.
A partir da v2.1.91, o Claude Code introduziu uma anotação que permite ao MCP server declarar o tamanho máximo do resultado que precisa passar inteiro: _meta["anthropic/maxResultSizeChars"]. Até 500 mil caracteres. Sem truncamento. Sem surpresa.
O Que É o MCP Tool Result Persistence Override
Para entender o problema, precisa entender como o Claude Code lida com resultados de ferramentas.
Quando uma tool — seja nativa (Read, Bash, Grep) ou MCP — retorna um resultado, o Claude Code decide se mantém esse resultado na conversa ou persiste em disco. A partir da v2.1.51, resultados maiores que 50K caracteres são automaticamente persistidos em disco. Na prática, isso significa: o modelo não vê o conteúdo completo. Ele recebe uma referência ao arquivo salvo, mas trabalha com uma versão truncada.
Para ferramentas nativas, isso funciona bem. O Claude Code controla o fluxo e sabe quando precisa reler o arquivo. Mas para MCP servers externos — um server de banco de dados, um server de documentação interna, um server que consulta APIs — o resultado truncado é tudo que o modelo recebe. Não tem como “reler”. O dado cortado, cortado ficou.
A issue #2638 no GitHub documenta o problema com clareza brutal: um MCP server retornava 8.046 caracteres sobre CRDTs. O Claude Code mostrava ~700. O response era cortado no meio de uma frase. O workaround? O dev tinha que dar cat no arquivo temporário manualmente. Em 2026.
O _meta["anthropic/maxResultSizeChars"] resolve isso do lado certo — o MCP server. Na definição da tool (em tools/list), o server declara: “este resultado pode ter até X caracteres, e precisa passar inteiro”. O Claude Code lê essa anotação e ajusta o threshold de persistência para aquela tool específica. O teto é 500.000 caracteres — aproximadamente 125K tokens, o suficiente para o schema completo de um banco de dados de médio porte com centenas de tabelas.
Como Funciona na Prática
A implementação é no MCP server, não no Claude Code. Quem controla o tamanho é quem produz o resultado.
No tools/list response do seu MCP server, você adiciona a anotação _meta na definição da tool:
{
"name": "get_full_schema",
"description": "Returns complete database schema with all tables, relations, and constraints",
"inputSchema": {
"type": "object",
"properties": {
"database": { "type": "string" }
}
},
"_meta": {
"anthropic/maxResultSizeChars": 500000
}
}Quando o Claude Code carrega essa tool, ele registra que resultados dela podem ter até 500K chars sem truncamento. Se o resultado vier com 200K, passa inteiro. Se vier com 600K, o threshold declarado pelo server (500K) é respeitado, e o excedente segue a política padrão.
Não precisa de configuração do lado do dev. Não precisa de setting no settings.json. Não precisa de variável de ambiente. O MCP server declara, o Claude Code respeita.
Isso é importante porque inverte a responsabilidade. Antes, o dev que usava o MCP server sofria o truncamento e não tinha como resolver — a não ser parar de usar o server ou reformatar o resultado em chunks menores. Agora, o desenvolvedor do MCP server resolve o problema uma vez, e todos os usuários se beneficiam.
Cenários de uso concretos:
1. Database Schema Server
Um MCP server que conecta no PostgreSQL e retorna o schema completo. 200 tabelas, 800 colunas, 150 foreign keys, 50 constraints, 30 indexes. Facilmente 150-300K caracteres. Sem a anotação, o Claude Code corta. Com a anotação, o modelo vê tudo e pode sugerir migrações, identificar problemas de normalização, e gerar queries corretas.
2. Documentação Interna
Um MCP server que indexa a wiki interna da empresa. Uma consulta sobre “arquitetura do sistema de pagamentos” retorna 80K de documentação. Sem a anotação, cortado. Com a anotação, o modelo tem contexto completo para responder perguntas técnicas.
3. API Response Completo
Um MCP server que faz chamadas a APIs externas — Jira, Linear, GitHub — e retorna issues com todos os comentários. Uma issue com 40 comentários e attachments pode ter 100K+. Sem a anotação, o modelo vê os primeiros 10 comentários e ignora a resolução que estava no comentário 35.
Por Que Isso Importa Para Sua Software House
O truncamento silencioso de MCP results é um problema de qualidade de output, não de performance. E problemas de qualidade são os mais caros porque passam despercebidos.
Quando o modelo trabalha com dados incompletos, ele não diz “não tenho informação suficiente”. Ele responde com confiança. Sugere uma migração que ignora tabelas. Gera uma query que não considera constraints. Propõe uma arquitetura que contradiz a documentação interna — mas como o modelo só viu 30% da documentação, ele não sabe.
O custo real não é o token. É a hora do dev senior revisando output incorreto. É o bug em produção porque a migração ignorou uma foreign key. É a decisão de arquitetura baseada em documentação incompleta.
Um estudo da Morph LLM analisou 42 sessões de coding agents e encontrou que 70% dos tokens em sessões são desperdício — o agente lê arquivos que nunca referencia, carrega módulos inteiros quando precisa de uma definição de tipo. Com MCP, o desperdício é pior: um deployment com 5 MCP servers e 30 tools cada consome 30.000-60.000 tokens só em metadata, 25-30% de uma context window de 200K antes de uma única mensagem.
O Claude Code já atacou o lado do schema com Tool Search (redução de 46.9% em context bloat — de 51K tokens para 8.5K com lazy loading de tools). Mas o lado do resultado continuava sem solução até a v2.1.91.
Na prática, uma software house com 20 devs usando MCP servers para banco de dados, documentação e project management estava operando com resultados truncados em toda interação que retornasse mais de 50K chars. Ninguém sabia. Ninguém investigava. O output parecia correto.
Segundo dados do setor: 40-70% de input tokens em AI agents são desnecessários (Morph LLM, 42 sessões analisadas). A análise da Fazm.ai mostra que estratégias de otimização podem cortar custos de tokens em 60-80%. A Anthropic cobra $15/MTok em output tokens para Opus — cada resultado truncado que gera output incorreto e precisa ser refeito é dinheiro queimado duas vezes.
Três MCP servers conectados. Resultado médio de 80K. Sem anotação, 80% dos resultados truncados. 20 devs × 10 consultas MCP/dia = 200 consultas com dados incompletos por dia. Quantas dessas geram output que precisa ser corrigido manualmente? Quantas geram bugs silenciosos que só aparecem em produção?
Dados e Contexto do Mercado
O problema de context window e MCP não é exclusivo do Claude Code:
- 143.000 de 200.000 tokens (72% da context window) consumidos por 3 MCP servers antes de qualquer mensagem do usuário (EclipseSource, 2026)
- 55.000+ tokens queimados só em tool definitions antes do agente processar uma mensagem (Junia.ai)
- $35-130 por hora desperdiçados em tokens desnecessários com 5 agentes paralelos a pricing Opus (Fazm.ai)
- $280-1.040 por dia de trabalho em tokens desperdiçados em cenários enterprise
- Perplexity abandonou MCP em março 2026, migrando para APIs e CLIs tradicionais por causa de overhead de contexto
- Cloudflare lançou “Code Mode” que entrega uma API inteira em 1.000 tokens vs 50.000+ com MCP schemas tradicionais
A indústria está convergindo para uma conclusão: MCP sem controle de tamanho de resultado é insustentável em produção. O _meta["anthropic/maxResultSizeChars"] é a resposta do Claude Code para o lado do resultado — o complemento do Tool Search (que resolveu o lado do schema/definição).
Stack completo de otimização MCP no Claude Code:
- Tool Search (v2.1.76+): lazy loading de tool definitions, -85% em context de schemas
- Tool result persistence (v2.1.51): resultados >50K salvos em disco automaticamente
- _meta maxResultSizeChars (v2.1.91): MCP server declara tamanho máximo do resultado, até 500K
- Prompt caching: até 90% de economia em tokens de input recorrentes
- Read compact format (v2.1.86): formato compacto para leitura de arquivos
O Que Eu Penso
O truncamento silencioso de MCP results era o pior tipo de bug: invisível, consistente, e com impacto cumulativo. O dev não sabia que o resultado estava cortado. O modelo não avisava. O output parecia correto. E toda decisão baseada nesse output carregava um viés de dados incompletos.
O _meta["anthropic/maxResultSizeChars"] é elegante porque resolve no lugar certo. Não é o dev que configura. Não é o Claude Code que adivinha. É o MCP server — quem sabe o tamanho do resultado — que declara. É o princípio de menor surpresa aplicado a uma situação onde a surpresa custava horas de debugging.
Mas tem um detalhe que precisa ficar claro: essa anotação depende do MCP server implementar. Se você usa um MCP server de terceiro que não adicionou a anotação, o truncamento continua. Se você desenvolve MCP servers internamente na sua software house, adicionar essa anotação nas tools que retornam resultados grandes é obrigatório a partir de agora.
E se você está pagando por MCP servers que retornam dados truncados sem que você saiba — está pagando duas vezes. Uma pelo token do resultado incompleto. Outra pela hora do dev corrigindo o output errado.
Conclusão
O Claude Code v2.1.91 trouxe uma mudança que parece pequena — uma anotação _meta numa definição de tool — mas resolve um problema que custava silenciosamente horas de trabalho toda semana em qualquer software house usando MCP servers.
Se você desenvolve MCP servers: adicione _meta["anthropic/maxResultSizeChars"] em toda tool que pode retornar mais de 50K chars. É uma linha de JSON.
Se você usa MCP servers de terceiros: verifique se eles já implementaram a anotação. Se não implementaram, abra uma issue. Ou mude para um que implementou.
Se você quer implementar esse nível de controle sobre como sua software house usa IA — não só MCP, mas tokens, custos, governança, segurança — é isso que eu faço.
Sou Thulio, mentoro 300+ software houses desde 2016. Se IA está custando mais do que deveria e entregando menos do que poderia, fale comigo na Software House Exponencial.
Fontes:
