Na semana passada um CTO de uma SH que mentoro me ligou frustrado. “Thulio, construímos um MCP server pra conectar o Claude Code no nosso PostgreSQL. Funciona lindo pra queries simples. Mas quando pedi pro Claude gerar um migration baseado no schema completo, ele criou uma migration que referenciava tabelas que não existem.”
Perguntei: “O schema inteiro tem quantas tabelas?”
“Cento e oitenta.”
“E o Claude viu quantas?”
Silêncio. Ele foi verificar. O MCP server retornava o schema completo — 47.000 caracteres. Mas o Claude Code estava trabalhando com um arquivo de referência no disco. O modelo nunca recebeu o schema. Recebeu um ponteiro pra onde o schema estava salvo. E fez o que qualquer IA faz quando não tem informação suficiente: inventou.
Esse problema tem nome. E agora tem solução.
O buraco negro do MCP: resultados que somem
MCP (Model Context Protocol) é provavelmente a melhor coisa que aconteceu pro ecossistema de ferramentas de IA em 2026. Mais de 97 milhões de downloads mensais do SDK. Mais de 5.800 servidores catalogados. Toda integração que você imaginar — banco de dados, Jira, Slack, Sentry, Figma, ERPs — já tem ou está ganhando um MCP server.
Mas o MCP tem um problema que quase ninguém discute abertamente: resultados grandes desaparecem.
Quando um MCP server retorna um resultado que excede o limite padrão de tamanho, o Claude Code não trunca o resultado e mostra o que sobrou. Ele faz algo pior: salva o resultado inteiro num arquivo em disco e substitui por uma referência de arquivo no contexto da conversa. O modelo recebe algo como “resultado salvo em /tmp/mcp-result-abc123.txt” em vez do dado real.
Isso parece inteligente — afinal, protege o context window de estourar. Mas na prática, o modelo perde acesso direto ao conteúdo. Ele não vai abrir o arquivo espontaneamente. Ele vai seguir em frente com o que tem. E o que ele tem é… nada.
A Issue #2638 no GitHub do Claude Code documenta exatamente essa frustração. Um desenvolvedor construiu um MCP server colaborativo que integrava Claude com Gemini. O server retornava respostas completas de 8.046 caracteres. O Claude Code exibia ~700 caracteres e cortava no meio da frase. “Isso destrói completamente o propósito de ferramentas MCP colaborativas,” escreveu o autor. A issue ganhou upvotes, comentários de outros devs com o mesmo problema, e workarounds criativos — como envolver todo resultado em JSON para enganar o display engine.
A issue foi fechada como “Not Planned”.
Até agora.
maxResultSizeChars: o controle que faltava
A versão v2.1.91 do Claude Code, lançada em 02 de abril de 2026, trouxe uma feature que resolve esse problema de forma elegante: _meta["anthropic/maxResultSizeChars"].
É uma annotation que o MCP server declara no response do tools/list. Você diz pro Claude Code: “essa ferramenta específica pode retornar resultados de até X caracteres, e eu quero que o modelo receba tudo inline no contexto.”
O teto máximo é 500.000 caracteres — meio milhão de chars. Para referência, isso é mais ou menos o equivalente a um livro de 250 páginas. Ou o schema completo de um banco com 500+ tabelas. Ou um log de deploy com milhares de linhas.
A configuração é uma única annotation no tools/list response do seu MCP server:
{
"name": "get_schema",
"description": "Returns the full database schema",
"_meta": {
"anthropic/maxResultSizeChars": 500000
}
}Pronto. Uma annotation. O Claude Code agora mantém o resultado dessa ferramenta inline no contexto até o limite que você declarou. Sem arquivo de referência. Sem truncation. O modelo recebe o dado completo e trabalha com ele.
E o brilhante dessa abordagem é a granularidade por ferramenta. Você pode declarar 500K para get_schema (schema completo do banco precisa estar inline), 200K para query_logs (logs extensos mas necessários), e não declarar nada para ping_health (resultado curto, limite padrão suficiente). Cada ferramenta com seu tamanho. Controle cirúrgico.
Por que isso é maior do que parece
Se você acha que isso é um detalhe técnico irrelevante, olha o que está acontecendo no mercado.
Em 11 de março de 2026, na conferência Ask 2026, o CTO da Perplexity — Denis Yarats — anunciou que a empresa está abandonando o MCP em favor de APIs tradicionais e CLIs. O motivo? 72% de desperdício de context window.
A Apideck documentou um deployment onde três MCP servers consumiam 143.000 de 200.000 tokens — 72% do contexto disponível — antes do agente processar uma única mensagem do usuário. Sobravam 57.000 tokens para conversa, documentos, raciocínio. É como alugar um escritório de 200m² e colocar os móveis em 143m². Sua equipe trabalha apertada nos 57m² restantes.
Testes da Scalekit revelaram que a operação mais simples — checar a linguagem de um repositório — consumia 1.365 tokens via CLI versus 44.026 tokens via MCP. Uma diferença de 32x para a mesma operação.
E o desperdício não é só de espaço. É de dinheiro. Análises de sessões de agentes mostram que 40-70% dos input tokens são desnecessários. No pricing do Opus — o modelo mais capaz — isso se traduz em $35 a $130 por hora em tokens que não contribuíram para o resultado. Num dia de 8 horas, são $280 a $1.040 jogados fora.
O problema tem dois lados: o input (tool definitions, schemas, instruções que incham o contexto) e o output (resultados de ferramentas que são grandes demais e desaparecem). A Anthropic já atacou o lado do input com o Tool Search — carregamento dinâmico de ferramentas que cortou o bloat em 46.9% (de 51K para 8.5K tokens). O maxResultSizeChars ataca o outro lado: garante que os resultados grandes que precisam estar no contexto realmente estejam lá.
Na prática: como sua SH deveria usar isso
Se sua software house tem MCP servers internos — e em 2026, se não tem, deveria ter — aqui está o playbook:
1. Identifique ferramentas com output grande
Passe pelos seus MCP servers e mapeie quais ferramentas retornam resultados que excedem o padrão:
- Database schemas —
get_schema,describe_tables,show_relationships - Full file trees —
list_project_structure,get_directory_tree - Query results —
execute_querycom JOINs complexos - Logs —
get_deploy_logs,fetch_error_traces - Documentação —
get_api_docs,read_confluence_page - Code analysis —
run_lint,security_scan,test_coverage
2. Declare a annotation por ferramenta
Não coloque 500K em tudo. Pense no tamanho real do output e adicione margem:
[
{
"name": "get_full_schema",
"description": "Returns complete database schema with all tables, columns, and relationships",
"_meta": { "anthropic/maxResultSizeChars": 300000 }
},
{
"name": "execute_query",
"description": "Executes a SQL query and returns results",
"_meta": { "anthropic/maxResultSizeChars": 100000 }
},
{
"name": "get_table_info",
"description": "Returns columns and types for a single table",
"_meta": { "anthropic/maxResultSizeChars": 10000 }
}
]3. Para MCP servers de terceiros: MAX_MCP_OUTPUT_TOKENS
Se você usa MCP servers que não controla (instalados do marketplace ou open source), não tem como adicionar a annotation. Nesse caso, use a variável de ambiente MAX_MCP_OUTPUT_TOKENS para aumentar o limite global:
export MAX_MCP_OUTPUT_TOKENS=50000O default é 25.000 tokens. Você pode aumentar conforme necessário. A desvantagem é que afeta todos os servers igualmente — sem a granularidade por ferramenta que a annotation oferece.
4. Combine com design patterns inteligentes
A equipe da Axiom publicou um blog post excelente sobre design de MCP servers para schemas grandes. Duas técnicas que recomendo:
Formato CSV em vez de JSON para dados tabulares. JSON é verboso. O mesmo resultado que consome 235 tokens em JSON consome 166 tokens em CSV — uma economia de 29% que escala linearmente. Em 1.000 linhas, são 13.800 tokens economizados.
Source-level capping. Em vez de retornar 100 buckets de histograma e deixar o Claude filtrar, retorne 15. A Axiom mostrou que 15 buckets são suficientes para o modelo entender a distribuição, reduzindo de 874 para 127 tokens. Menos dados, mesma qualidade de decisão.
A combinação é poderosa: maxResultSizeChars garante que o resultado chega inline, e design patterns inteligentes garantem que o resultado é eficiente.
Os dois lados do contexto
Esse é um tema que tenho batido bastante nos últimos artigos. A semana passada escrevi sobre o cap de output de hooks — como hooks que retornam texto demais poluem o contexto silenciosamente. O maxResultSizeChars é o outro lado da mesma moeda.
No caso de hooks, o problema era informação não solicitada entrando no contexto (output de hooks que o modelo não pediu). A solução foi um cap automático de 10K caracteres.
No caso de MCP, o problema é informação solicitada sendo removida do contexto (resultado de ferramentas que o modelo pediu explicitamente). A solução é uma annotation que permite tamanhos maiores.
As duas features juntas representam a mesma filosofia: controle granular sobre o que entra e o que fica no context window. É context engineering aplicada no nível do toolkit, não do prompt.
Se sua SH já tem hooks configurados com o conditional if e agora adiciona maxResultSizeChars nos MCP servers, você tem uma stack de context engineering que a maioria das empresas nem sabe que existe.
O elefante na sala: MCP é viável em produção?
Eu acompanho o debate “MCP tá morrendo” desde que a Perplexity fez o anúncio em março. E na minha experiência com 300+ software houses, a resposta é: MCP não está morrendo. Está amadurecendo.
O problema de 72% de context waste não é do protocolo. É de implementação. É de MCP servers que retornam tudo em JSON verboso. De deployments com 15 servers conectados ao mesmo tempo. De ferramentas com descriptions de 2KB que deveriam ter 200 bytes. De resultados de 50K tokens quando 5K seriam suficientes.
A Anthropic está atacando isso sistematicamente:
- Tool Search cortou bloat de definitions em 46.9%
- Tool descriptions capped em 2KB por server
- MCP deduplication (local wins) evita servers duplicados
MCP_CONNECTION_NONBLOCKINGeliminou startup blocking- E agora
maxResultSizeCharsresolve o lado dos resultados
É uma stack. Cada peça resolve um pedaço do problema. Empresas que implementam a stack completa não têm 72% de waste. Têm MCP eficiente.
O que eu penso
Na minha experiência com 300+ SHs, o MCP server mais comum que vejo hoje é o de banco de dados. É o primeiro que todo mundo constrói quando descobre MCP: “quero que o Claude Code acesse meu PostgreSQL/MySQL/MongoDB.” E é o primeiro que quebra quando o schema tem mais de 50 tabelas.
O dev pede pro Claude gerar uma migration. O Claude recebe uma referência de arquivo em vez do schema. Gera uma migration baseada no que ele “lembra” de mensagens anteriores. A migration falha. O dev acha que o Claude é burro. Na verdade, o Claude nunca teve a informação.
maxResultSizeChars é uma linha de código que muda isso. Uma annotation no tools/list. Sem configuração no client. Sem variável de ambiente. O server declara o que precisa, o client respeita.
Se sua SH tem MCP servers, adicione essa annotation hoje. Se não tem, essa é mais uma razão pra construir.
Se você quer implementar esse nível de inteligência artificial na sua software house e não sabe por onde começar — ou se já começou e está enfrentando exatamente esses problemas de context, truncation e produtividade — me chama. Desde 2016 eu ajudo SHs a escalar com tecnologia, e IA é o capítulo mais importante dessa história.
Sou Thulio, mentoro 300+ software houses desde 2016.
