MCP de codebase RAG para agentes que não leem tudo

MCP de codebase RAG é uma camada de contexto para agentes de código. Em vez de pedir ao Codex ou ao Claude Code para lerem o repositório inteiro, você expõe ferramentas pequenas: buscar símbolo, achar contrato de API, listar testes relevantes, recuperar decisão arquitetural e devolver só o trecho necessário para a próxima decisão.

Em 2026, o GitHub disse que o Copilot code review cresceu 10 vezes desde o lançamento inicial e já responde por mais de uma em cada cinco revisões de código no GitHub (GitHub, "60 million Copilot code reviews and counting", 2026). Esse volume deixa clara a dor: agentes precisam de contexto confiável, não de prompts cada vez maiores.

TL;DR prático

• MCP de codebase RAG deve responder perguntas pequenas sobre código.
• A ferramenta boa devolve caminho, trecho, motivo e limite de confiança.
• Busca lexical, símbolos e embeddings se complementam.
• Segurança vem de escopo, auditoria e saídas curtas.

Por que MCP de codebase RAG virou prioridade?

Em 2025, o relatório DORA do Google Cloud mediu 90% de adoção de IA entre profissionais de software (Google, "How are developers using AI? Inside our 2025 DORA report", 2025). MCP de codebase RAG virou prioridade porque a adoção cresceu mais rápido que a capacidade dos times de organizar contexto para agentes.

O problema não é só tamanho de janela. Uma janela maior aceita mais ruído. Em codebases reais, o agente precisa diferenciar regra atual, código morto, teste quebrado, convenção local e decisão antiga. Jogar tudo no prompt transforma descoberta em loteria.

Esse post aprofunda o que ficou aberto no texto sobre context engineering para agentes de código. Lá, o foco era orçamento de contexto. Aqui, o foco é a interface: como o agente pede contexto, como a ferramenta responde e como o time audita o que foi usado.

Um servidor MCP bem desenhado funciona como uma API interna para conhecimento de engenharia. Ele não dá "acesso ao repo". Ele dá respostas estreitas, com fronteiras. Quando o agente pergunta por um símbolo, recebe arquivos candidatos. Quando pergunta por testes, recebe nomes e comandos. Quando pergunta por risco, recebe áreas sensíveis e motivo.

O ganho prático aparece na revisão. Se o agente abre PR com evidência de quais trechos recuperou, o revisor consegue separar erro de implementação de erro de contexto. Essa diferença muda a conversa: o time deixa de perguntar "por que a IA inventou?" e passa a perguntar "qual ferramenta devolveu contexto fraco?".

O que um servidor MCP deve expor?

Em 2025, a especificação do Model Context Protocol definiu três superfícies de servidor: recursos, prompts e ferramentas (Model Context Protocol, "Specification 2025-11-25", 2025). Para codebase RAG, ferramentas devem executar consultas controladas, recursos devem carregar contexto estável e prompts devem padronizar fluxos repetíveis.

Comece por ferramentas de leitura. buscar_simbolo, buscar_referencia, achar_testes, ler_contrato_api e recuperar_decisao cobrem a maior parte do trabalho. Cada ferramenta deve ter argumentos tipados, limite de resultados e resposta com caminho, trecho curto, motivo da seleção e quando a busca pode estar incompleta.

Depois exponha recursos estáveis. Bons candidatos são mapa de módulos, convenções de teste, contratos de API, padrões de erro, runbooks e decisões arquiteturais. Isso conversa com arquitetura de serviços em TypeScript, porque fronteiras claras tornam a recuperação mais precisa.

Use prompts MCP para fluxos que o time repete. Um prompt de triagem de bug pode pedir reprodução, arquivos prováveis e testes. Um prompt de revisão de PR pode pedir escopo, risco e evidência. Um prompt de migração pode pedir dependentes, rollback e impacto em dados.

Evite a ferramenta "ler tudo". Ela parece útil, mas destrói o contrato. Se uma ferramenta precisa devolver muitos arquivos, ela deve gravar artefato em disco e responder com síntese. Em loops longos, eu uso o RemoteCode para estender Claude Code e Codex com menos desperdício de contexto como recurso do próprio autor quando a tarefa precisa atravessar sessões sem carregar todo o histórico no prompt principal.

Como combinar busca lexical, símbolos e embeddings?

Em 2026, o GitHub afirma que a arquitetura agentic do Copilot code review recupera contexto de repositório, raciocina sobre mudanças e gerou aumento inicial de 8,1% em feedback positivo (GitHub, "60 million Copilot code reviews and counting", 2026). A lição é prática: recuperação precisa ser planejada, não incidental.

Busca lexical é o primeiro filtro. Ela encontra nomes exatos, mensagens de erro, rotas, variáveis de ambiente e comandos. Use rg ou índice equivalente antes de embeddings. Se o erro menciona SessionExpiredError, a busca textual costuma ser mais confiável que uma vizinhança semântica.

Símbolos dão estrutura. Um índice de definições e referências entende funções, classes, exports, rotas e tipos. Isso evita que o agente confunda string parecida com contrato real. Em TypeScript, por exemplo, uma busca por referência de tipo pode separar uso de produção, fixture e teste.

Embeddings entram quando a pergunta é conceitual. "Onde tratamos expiração de sessão?" talvez não use a mesma palavra em todos os arquivos. A busca semântica acha candidatos. O reranking compara esses candidatos com símbolos e testes. O servidor MCP então devolve poucos resultados, não uma pilha de arquivos.

Uma resposta boa tem formato previsível:

{
  "consulta": "expiracao de sessao",
  "resultados": [
    {
      "arquivo": "src/auth/session.service.ts",
      "trecho": "funcao que renova sessao antes de emitir novo token",
      "motivo": "define o comportamento central de renovacao",
      "proximos_passos": ["rodar teste de sessao", "verificar revogacao"]
    }
  ],
  "limite": "resultado resumido por relevancia; use buscar_referencia para expandir"
}

Esse contrato ajuda subagentes também. Um subagente de segurança pode consultar risco. Outro pode consultar testes. O agente principal recebe síntese, não logs. Essa divisão se encaixa no harness de agentes de código para PRs confiáveis, porque cada recuperação vira evidência revisável.

Como evitar que MCP vire uma brecha de segurança?

Em 2026, o GitHub colocou secret scanning no GitHub MCP Server para detectar segredos antes de commit ou PR, em IDEs e agentes compatíveis com MCP (GitHub Changelog, "Secret scanning in AI coding agents via the GitHub MCP Server", 2026). Isso mostra o ponto certo: MCP deve reduzir risco operacional, não ampliar permissão sem controle.

Trate cada ferramenta como superfície de permissão. Uma ferramenta que lê código é diferente de uma que abre PR. Uma que consulta logs é diferente de uma que consulta banco. Uma que lista contratos é diferente de uma que executa migração. O agente não deve receber todas porque "talvez precise".

Use escopo por workspace. Se o Codex usa .codex/config.toml em projeto confiável, o servidor MCP daquela base deve resolver caminhos dentro do projeto. Se o Claude Code executa servidor stdio, aproveite a variável de diretório do projeto para evitar caminhos ambíguos. A regra é simples: uma ferramenta não deve atravessar para outro repositório por acidente.

Audite chamadas. Registre ferramenta, argumentos, arquivos retornados e tamanho da saída. Não registre segredo. Se um PR de agente falha, esse log mostra se o erro veio de ferramenta, prompt, índice desatualizado ou decisão do modelo. Sem log, a equipe só debate sintomas.

Na minha prática, esse log é mais útil quando cabe em revisão humana. Eu quero ver a consulta que levou ao arquivo, não cada token retornado pelo índice. Se o agente escolheu o teste errado, o log mostra se ele recebeu candidatos ruins ou se ignorou um candidato bom.

Também limite saída. A documentação do Claude Code avisa quando uma ferramenta MCP passa de 10.000 tokens e usa limite padrão de 25.000 tokens para saída (Claude Code Docs, "Connect Claude Code to tools via MCP", 2026). Mesmo quando a ferramenta permite mais, codebase RAG bom responde curto por padrão.

Como integrar isso ao Codex e ao Claude Code?

Em 2026, a documentação do Codex afirma que MCP fica no config.toml e pode ser escopado ao projeto com .codex/config.toml em projetos confiáveis (OpenAI Developers, "Model Context Protocol - Codex", 2026). Essa configuração permite que CLI e extensão de IDE compartilhem os mesmos servidores.

No Codex, trate o servidor de codebase RAG como dependência do repositório. O nome, comando, permissões e escopo devem viver próximos da base, não perdidos em configuração pessoal. Assim, um agente que trabalha no monorepo usa ferramentas diferentes de um agente que trabalha em um serviço pequeno.

No Claude Code, MCP serve para conectar ferramentas, bancos e APIs ao fluxo do agente. A própria documentação recomenda verificar confiança antes de conectar servidores, porque servidores que buscam conteúdo externo podem expor risco de prompt injection (Claude Code Docs, "Connect Claude Code to tools via MCP", 2026). Para codebase RAG, isso significa preferir fonte local e índice controlado.

Um desenho mínimo pode ficar assim:

[mcp_servers.codebase_contexto]
command = "node"
args = ["tools/mcp-codebase-contexto/server.js"]
env = { WORKSPACE_ROOT = "." }

O servidor deve oferecer poucas ferramentas no começo. Não implemente banco vetorial, grafo de dependência e análise de PR no mesmo dia. Publique buscar_simbolo, buscar_referencia e achar_testes. Depois meça quais perguntas o agente ainda faz manualmente.

Essa integração também precisa aparecer no PR. Peça ao agente para registrar "contexto consultado" no corpo: ferramenta, arquivos retornados e teste escolhido. Isso conecta MCP ao texto sobre evals de PR que seguram agentes de código no CI. Sem esse rastro, a recuperação melhora a sessão, mas não melhora a revisão.

Qual é o mínimo viável para esta semana?

Em 2025, a pesquisa do Stack Overflow mostrou que 69% dos usuários de agentes perceberam ganho de produtividade, mas só 17% perceberam melhora de colaboração em equipe (Stack Overflow, "2025 Developer Survey: AI", 2025). O mínimo viável deve atacar essa lacuna: transformar ganho individual em contexto compartilhado e auditável.

Primeiro, escolha um módulo com dor real. Autenticação, cobrança, filas ou integração externa funcionam bem porque têm contratos, testes e risco. Não comece pelo monorepo inteiro. Um escopo pequeno revela o desenho certo sem criar um índice caro e pouco usado.

Segundo, crie três ferramentas. Uma busca símbolo. Outra encontra testes relacionados. A terceira recupera decisões arquiteturais de arquivos curtos, como ADRs ou notas de design. Se não há decisões escritas, registre as três mais importantes antes de automatizar.

Terceiro, defina resposta curta. Cada resultado deve ter arquivo, trecho, motivo e próximo passo. Se a ferramenta não sabe, ela deve dizer. Ferramenta que finge certeza treina o agente a confiar no contexto errado.

Quarto, rode um PR pequeno com rastro. O agente deve usar as ferramentas, aplicar patch, rodar teste e declarar o que consultou. Se o revisor consegue entender a cadeia de contexto em menos de um minuto, o MVP funciona. Se precisa reler logs brutos, a saída ainda está grande demais.

FAQ sobre MCP de codebase RAG

Em 2026, o GitHub relatou que mais de 12.000 organizações executam Copilot code review automaticamente em todo PR (GitHub, "60 million Copilot code reviews and counting", 2026). As perguntas abaixo ajudam a transformar recuperação de contexto em prática de plataforma.

MCP substitui RAG tradicional sobre codebase?

Não. Em 2025, a especificação MCP separou recursos, prompts e ferramentas (Model Context Protocol, "Specification 2025-11-25", 2025). RAG é a técnica de recuperação; MCP é a interface para o agente pedir essa recuperação dentro do fluxo de trabalho.

Preciso de embeddings no primeiro dia?

Não. Em 2026, o GitHub atribuiu parte da melhora do review agentic à recuperação inteligente de contexto, não a uma técnica única (GitHub, "60 million Copilot code reviews and counting", 2026). Comece com busca lexical e símbolos. Adicione embeddings quando perguntas conceituais escaparem.

MCP deixa o agente autorizado a fazer qualquer coisa?

Não deveria. Em 2026, a documentação de servidores MCP remotos da Anthropic recomenda conectar apenas servidores confiáveis e revisar práticas de segurança e termos (Claude Platform Docs, "Remote MCP servers", 2026). Em codebase RAG, cada ferramenta precisa de escopo, limite e log.

Como medir se a camada de contexto melhorou?

Meça retrabalho de revisão. Em 2025, o Stack Overflow viu 69% de ganho individual com agentes, mas só 17% de melhora em colaboração (Stack Overflow, "2025 Developer Survey: AI", 2025). A camada melhorou quando PRs chegam com menos arquivos fora de escopo e evidência mais clara.

Fechamento

Em 2026, a Anthropic descreveu MCP como um padrão para conectar agentes a sistemas externos e reduzir integrações duplicadas (Anthropic, "Code execution with MCP: building more efficient AI agents", 2026). Para desenvolvimento de software, a aplicação mais útil é simples: dar ao agente um jeito estreito e auditável de perguntar sobre a codebase.

Não comece por infraestrutura grande. Comece por uma interface pequena. Três ferramentas, respostas curtas, logs e um PR com rastro já mudam a qualidade do trabalho. Quando a recuperação fica visível, o time consegue melhorar o agente, o índice e a própria arquitetura do sistema.

Fontes consultadas

• Google, "How are developers using AI? Inside our 2025 DORA report", recuperado em 2026-07-02, https://blog.google/innovation-and-ai/technology/developers-tools/dora-report-2025/
• GitHub, "60 million Copilot code reviews and counting", recuperado em 2026-07-02, https://github.blog/ai-and-ml/github-copilot/60-million-copilot-code-reviews-and-counting/
• Model Context Protocol, "Specification 2025-11-25", recuperado em 2026-07-02, https://modelcontextprotocol.io/specification/2025-11-25
• GitHub Changelog, "Secret scanning in AI coding agents via the GitHub MCP Server", recuperado em 2026-07-02, https://github.blog/changelog/2026-03-17-secret-scanning-in-ai-coding-agents-via-the-github-mcp-server/
• Claude Code Docs, "Connect Claude Code to tools via MCP", recuperado em 2026-07-02, https://code.claude.com/docs/en/mcp
• OpenAI Developers, "Model Context Protocol - Codex", recuperado em 2026-07-02, https://developers.openai.com/codex/mcp
• Stack Overflow, "2025 Developer Survey: AI", recuperado em 2026-07-02, https://survey.stackoverflow.co/2025/ai
• Claude Platform Docs, "Remote MCP servers", recuperado em 2026-07-02, https://platform.claude.com/docs/en/agents-and-tools/remote-mcp-servers
• Anthropic, "Code execution with MCP: building more efficient AI agents", recuperado em 2026-07-02, https://www.anthropic.com/engineering/code-execution-with-mcp