Context Mode - o servidor MCP que reduz em 98% o consumo de contexto do Claude Code

• Resolve o problema de grandes volumes de dados brutos consumirem rapidamente a janela de contexto ao chamar ferramentas externas
• Fica entre o Claude Code e a saída das ferramentas para comprimir e filtrar dados, reduzindo 315 KB para 5,4 KB (economia de 98%)
• Com uma arquitetura em sandbox, isola cada execução e inclui apenas o stdout no contexto, bloqueando o vazamento de dados brutos como logs e snapshots
• Com uma base de conhecimento baseada em SQLite FTS5, indexa conteúdo em Markdown e aplica ranking BM25 e Porter stemming para oferecer busca precisa em blocos de código
• Com o mesmo limite de 200K tokens, a duração da sessão aumenta de 30 minutos para 3 horas, permitindo um gerenciamento de contexto mais eficiente para agentes de IA

---

Problema

• As chamadas de ferramenta MCP do Claude Code despejam dados brutos diretamente na janela de contexto de 200K a cada chamada
  • Snapshot do Playwright 56 KB, 20 issues do GitHub 59 KB, logs de acesso 45 KB etc.
  • Em cerca de 30 minutos de uso, 40% de todo o contexto é consumido
• O MCP se tornou o padrão para usar ferramentas externas, mas há uma limitação estrutural em que tanto as definições de entrada quanto os dados de saída preenchem o contexto
• Com mais de 81 ferramentas ativas, 72% (143K tokens) já eram consumidos antes mesmo da primeira mensagem

Estrutura do Context Mode

• Um servidor MCP posicionado entre o Claude Code e a saída das ferramentas, transmitindo os dados com o mínimo possível de conteúdo bruto
  • Uma saída de 315 KB é reduzida para 5,4 KB (queda de 98%)
• Cada chamada execute roda em um subprocesso isolado, executando de forma independente sem compartilhar memória nem estado
  • Apenas o stdout entra no contexto, enquanto logs, respostas de API, snapshots etc. permanecem dentro da sandbox
• Suporte a 10 runtimes de linguagem: JavaScript, TypeScript, Python, Shell, Ruby, Go, Rust, PHP, Perl, R
  • Detecção automática do Bun melhora a velocidade de execução de JS/TS em 3 a 5 vezes
• CLIs autenticadas (gh, aws, gcloud, kubectl, docker) transmitem credenciais com segurança por meio de herança de variáveis de ambiente

Base de conhecimento (knowledge base)

• A ferramenta index divide o Markdown por heading e o armazena em uma tabela virtual SQLite FTS5, preservando os blocos de código como estão
• Na busca, usa o algoritmo de ranking BM25 para calcular relevância com base em frequência de termos, frequência inversa de documento e normalização do tamanho do documento
• Com Porter stemming, “running”, “runs” e “ran” são associados à mesma raiz
• Ao chamar search, retorna blocos de código exatos e a hierarquia de headings, não um resumo
• fetch_and_index busca uma URL, converte HTML em Markdown e depois indexa, sem incluir a página original no contexto

Métricas de desempenho

• Em 11 cenários reais (triagem de testes, diagnóstico de erro em TypeScript, revisão de git diff etc.), a saída ficou abaixo de 1 KB em todos os casos
  • Snapshot do Playwright: 56 KB → 299 B
  • Issues do GitHub (20): 59 KB → 1,1 KB
  • Logs de acesso (500 entradas): 45 KB → 155 B
  • Análise de CSV (500 linhas): 85 KB → 222 B
  • Log do Git (153 commits): 11,6 KB → 107 B
  • Investigação de repositório (subagent): 986 KB → 62 KB (5 chamadas vs 37)
• No total da sessão, redução de 315 KB para 5,4 KB, com duração da sessão de 30 minutos → 3 horas
• Contexto restante após 45 minutos: antes 60% → agora 99%

Instalação e uso

• Suporte a hook de roteamento automático e comandos slash por meio do Plugin Marketplace
• Também é possível instalar apenas para MCP
• Pronto para uso imediatamente após reiniciar o Claude Code

Mudanças na prática

• Sem alterar a forma de uso, o hook PreToolUse faz o roteamento automático da saída
• Subagentes usam batch_execute como ferramenta padrão
• O subagente Bash foi atualizado para general-purpose, passando a ter acesso às ferramentas MCP
• Como resultado, a janela de contexto deixa de encher rapidamente, permitindo sessões mais longas com a mesma quantidade de tokens

Contexto de desenvolvimento

• Ao operar o MCP Directory & Hub, foi identificado um padrão comum em que todos os servidores MCP despejavam dados brutos no contexto
• Inspirado pelo Code Mode da Cloudflare, que comprimiu definições de ferramentas, o projeto expandiu a ideia para a compressão dos dados de saída
• Após confirmar que era possível trabalhar 6 vezes mais tempo em uma sessão do Claude Code, o projeto foi publicado como open source sob licença MIT
• GitHub: mksglu/claude-context-mode

[GN⁺]

Comentários no Hacker News

• A abordagem de índice FTS5 proposta aqui está correta, mas acho que dá para ir um passo além
  A saída das ferramentas mistura dados estruturados (JSON, tabelas, configurações) e linguagem natural (comentários, mensagens de erro, docstrings), então BM25 puro perde desempenho
  Para resolver um problema parecido, eu criei um buscador híbrido combinando Model2Vec + sqlite-vec + FTS5. Junto os dois resultados com Reciprocal Rank Fusion (RRF), assim consigo ao mesmo tempo a correspondência exata de palavras-chave do BM25 e a correspondência semântica da busca vetorial
  Indexação incremental também é importante. Meu indexador reembeda só os chunks alterados com a flag --incremental. Reindexar os 15.800 arquivos inteiros leva 4 minutos, e o incremental diário fica abaixo de 10 segundos
  Do lado de cache, essa abordagem também ajuda. Para a mesma consulta, a saída comprimida é determinística, então o cache de prompt funciona de forma estável
  Algo que eu adicionaria à arquitetura do Context Mode é rodar esse mesmo buscador com um hook PostToolUse, para que a saída seja comprimida antes de entrar na conversa

  • O problema na abordagem do OP era que as respostas estruturadas continuavam intactas, mas estou criando um gateway MCP sem possibilidade de execução em sandbox, então isso parece muito útil para mim. Vou tentar isso hoje
  • Eu gostaria muito de ler um texto mais aprofundado sobre isso. Acho que o pessoal detalhista do HN ia adorar
  • Eu também queria ver em detalhes o contexto e o processo de implementação desse trabalho de indexação no Obsidian

• Sou o autor do post. Compartilhei o repositório no GitHub há alguns dias e recebi um bom feedback. Este texto é a explicação da arquitetura
  A ideia principal é que, em vez de jogar na janela de contexto de 200K os dados brutos despejados pelas chamadas de ferramenta MCP, o Context Mode cria um subprocesso isolado e envia só o stdout para o contexto. Sem chamadas de LLM, totalmente baseado em algoritmo, usando SQLite FTS5 + BM25 + Porter stemming
  Recentemente cheguei a 228 estrelas e consegui dados de uso reais, e percebi o quanto o roteamento para subagentes é importante. Se você atualiza automaticamente o subagente Bash para um genérico e usa batch_execute, dá para evitar encher o contexto com saída bruta

  • Seria bom adicionar no post do blog o link para o post do Cloudflare Code Mode. Está no README, mas não no texto principal
  • Achei muito interessante e pretendo testar por conta própria. Só queria confirmar se entendi certo que o Context Mode não lida exatamente com o uso de contexto do próprio MCP. Eu uso MCP em vários ambientes do Claude, então só a CLI tem suas limitações
  • Fico curioso para saber se isso também pode ser usado com outros agentes, como o Zed Agent
  • Queria saber se existe algum motivo para não suportar Codex. Pela estrutura, isso parece independente do agente
  • Fico me perguntando se isso não quebra o cache

• Não entendo por que não usam o modo mcp-cli. Eu fiz uma versão clonada com wener-mcp-cli

• Ótimo trabalho. Acho que ainda existe bastante espaço para melhorar o gerenciamento da janela de contexto. Por exemplo, quando o modelo encontra a resposta certa depois de várias tentativas, uma abordagem de backtracking para remover do contexto as tentativas fracassadas parece útil

  • Também concordo. Logs e registros de falha gerados durante o debugging deveriam poder ser removidos depois que o bug é corrigido. Nos IDEs atuais isso é incômodo de fazer manualmente. Seria bom se o agente gerenciasse o contexto por conta própria, e coisas como logs fossem limpas automaticamente depois de certo número de vezes. O contexto não deveria ser uma pilha simples, mas um espaço que pode ser manipulado livremente
  • Tentativas fracassadas no fim são ruído. Detectar automaticamente padrões de repetição e deixar só a última versão bem-sucedida é perfeitamente viável
  • Agora parece o fim dos anos 1990. Naquela época era HTML e SQL; agora são os agentes de programação. Já somos engenheiros experientes, então ao usar Claude Code acabamos encontrando otimizações naturalmente
  • Usar subagentes também é uma forma de fazer isso. Quando surge um problema, você pode criar um fork de um subagente para resolvê-lo e trazer só o resultado. Também é interessante imaginar o modelo apagando a própria memória e voltando a um estado anterior por conta própria
  • Eu realmente faço isso. Cada chamada de tarefa roda em um subprocesso separado, então não contamina o contexto pai. Depois de concluir, ele envia ao pai quatro itens: resultado, resumo do processo, tentativas fracassadas e lições aprendidas. A saída das ferramentas fica salva em arquivos, e o LLM lê só as partes necessárias. Por exemplo, se termina com “Success!”, basta olhar a última linha. Se falhar, lê só a mensagem de erro. Também estou experimentando resumir logs com um modelo local e passar isso para um modelo em nuvem. Talvez não seja a técnica mais recente, mas funciona bem no meu ambiente

• Depois de ler este post, percebi que eu não sabia absolutamente nada sobre o uso de tokens do Claude Code, então de manhã criei uma CLI chamada claude-trace
  Ela faz parsing de ~/.claude/projects/*/*.jsonl para analisar uso e custo por sessão, ferramenta, projeto e linha do tempo, incluindo leitura/geração de cache
  Se o Context Mode resolve bem a compressão da saída, isso funciona como uma camada de medição para visualizar o consumo antes e depois das mudanças

  • Como na pergunta “/context?”, o ponto central é visualizar para onde os tokens realmente estão indo

• Dá para reduzir muito uso de tokens usando apps CLI em vez de MCP. Por exemplo, o GitHub CLI faz a mesma coisa com muito menos tokens do que o MCP

• Os hooks parecem agressivos demais. Bloquear todo curl/wget/WebFetch e criar snapshots em sandbox de 56 KB é legal, mas é exagero em casos como um simples curl api.example.com/health, quando só 200 bytes bastam
  Se você comprime 153 commits do git em 107 bytes, o modelo só consegue ver os dados se escrever um script de extração perfeito. Se usar o comando errado, a informação necessária desaparece
  O benchmark presume que o modelo sempre escreve o código de resumo correto, mas na prática não é assim

  • Também concordo com isso, então removi essa funcionalidade

• Não é ruim, mas existe perda de precisão e risco de alucinação. Por causa de dados incompletos ou de uma lógica de extração incorreta, o Claude pode chegar a conclusões erradas. Existe a suposição de que o MCP é inteligente o bastante para escrever tanto bons scripts de extração quanto boas consultas de busca. Acho que preservação da informação é, na prática, um grande problema

• A taxa de compressão é impressionante, mas fico curioso para saber se, com o contexto comprimido, o modelo ainda entrega a mesma qualidade de saída. Não adianta aumentar a sessão de 30 minutos para 3 horas se a qualidade do raciocínio na segunda hora não se mantiver
  A economia de cache mencionada pelo esafak também é importante. Se o cache de prompt funcionar bem, até um contexto prolixo sai praticamente de graça. Mas, se a compressão quebrar a continuidade do cache, o custo pode até aumentar
  Um problema ainda mais fundamental é que a maioria das ferramentas MCP traz todos os dados com SELECT *. É um problema de projeto de protocolo: falta suporte a resumo e drill-down

  • Mesmo quando o cache parece grátis, na prática ele ainda causa queda de atenção e de velocidade. Mesmo reutilizando prefixos longos, o volume de cálculo continua alto

• Fico em dúvida se realmente é necessário colocar mais de 80 ferramentas no contexto. Contexto é ouro: quanto mais coisa sem relação com o problema você coloca, pior o resultado fica. Em vez de compressão de dados, separar subagentes parece uma abordagem melhor

  • Faz sentido. Mas a maioria das pessoas não gerencia servidores MCP diretamente por tarefa. Só de instalar 5 ou 6 servidores, já carregam 80 ferramentas por padrão. O Context Mode não resolve esse excesso na definição das ferramentas. Em vez disso, ele trata do lado da saída despejada depois da execução. Por exemplo, só um snapshot do Playwright ou um git log já pode consumir 50 mil tokens, então isso é processado em sandbox