RAG de codebase con MCP para agentes que no deben leerlo todo

RAG de codebase con MCP es una capa de contexto para agentes de código. En vez de pedirle a Codex o a Claude Code que lean todo el repositorio, expones herramientas pequeñas: buscar un símbolo, encontrar un contrato de API, listar pruebas relevantes, recuperar una decisión de arquitectura y devolver solo el fragmento necesario para la siguiente decisión.

En 2026, GitHub dijo que Copilot code review creció 10 veces desde su lanzamiento inicial y ya representa más de una de cada cinco revisiones de código en GitHub (GitHub, "60 million Copilot code reviews and counting", 2026). Ese volumen deja claro el problema: los agentes necesitan contexto confiable, no prompts cada vez más grandes.

TL;DR práctico

• RAG de codebase con MCP debe responder preguntas pequeñas sobre código.
• Una buena herramienta devuelve ruta, fragmento, motivo y límite de confianza.
• Búsqueda lexical, símbolos y embeddings se complementan.
• La seguridad viene de alcance, auditoría y salidas cortas.

¿Por qué RAG de codebase con MCP se volvió urgente?

En 2025, el reporte DORA de Google Cloud midió 90% de adopción de IA entre profesionales de software (Google, "How are developers using AI? Inside our 2025 DORA report", 2025). RAG de codebase con MCP se volvió urgente porque la adopción creció más rápido que la capacidad de los equipos para organizar contexto para agentes.

El problema no es solo el tamaño de la ventana de contexto. Una ventana mayor acepta más ruido. En codebases reales, el agente debe separar regla vigente, código muerto, prueba rota, convención local y decisión antigua. Meter todo en el prompt convierte el descubrimiento en una lotería.

Este post amplía mi artículo sobre context engineering para agentes de código. Allí, el foco era el presupuesto de contexto. Aquí, el foco es la interfaz: cómo el agente pide contexto, cómo responde la herramienta y cómo el equipo audita lo que se usó.

Un servidor MCP bien diseñado funciona como una API interna para conocimiento de ingeniería. No concede "acceso al repo". Da respuestas estrechas, con fronteras. Cuando el agente pregunta por un símbolo, recibe archivos candidatos. Cuando pregunta por pruebas, recibe nombres y comandos. Cuando pregunta por riesgo, recibe áreas sensibles y motivos.

La ganancia práctica aparece en la revisión. Si el agente abre un PR con evidencia de qué fragmentos recuperó, el revisor puede separar error de implementación de error de contexto. Eso cambia la conversación: el equipo deja de preguntar "¿por qué la IA inventó esto?" y empieza a preguntar "¿qué herramienta devolvió contexto débil?".

¿Qué debe exponer un servidor MCP?

En 2025, la especificación de Model Context Protocol definió tres superficies de servidor: recursos, prompts y herramientas (Model Context Protocol, "Specification 2025-11-25", 2025). Para RAG de codebase, las herramientas deben ejecutar consultas controladas, los recursos deben cargar contexto estable y los prompts deben estandarizar flujos repetibles.

Empieza por herramientas de lectura. buscar_simbolo, buscar_referencia, encontrar_pruebas, leer_contrato_api y recuperar_decision cubren la mayor parte del trabajo. Cada herramienta debe tener argumentos tipados, límite de resultados y respuesta con ruta, fragmento corto, motivo de selección y aviso de cuándo la búsqueda puede estar incompleta.

Después expón recursos estables. Buenos candidatos son mapas de módulos, convenciones de pruebas, contratos de API, patrones de error, runbooks y decisiones de arquitectura. Esto encaja con la arquitectura de servicios en TypeScript, porque las fronteras claras hacen la recuperación más precisa.

Usa prompts MCP para flujos que el equipo repite. Un prompt de triage de bug puede pedir reproducción, archivos probables y pruebas. Un prompt de revisión de PR puede pedir alcance, riesgo y evidencia. Un prompt de migración puede pedir dependientes, rollback e impacto en datos.

Evita la herramienta "leer todo". Parece útil, pero rompe el contrato. Si una herramienta necesita devolver muchos archivos, debe escribir un artefacto en disco y responder con una síntesis. Para loops largos, uso RemoteCode para extender Claude Code y Codex con menos desperdicio de contexto como herramienta propia cuando una tarea debe cruzar sesiones sin cargar todo el historial en el prompt principal.

¿Cómo combinar búsqueda lexical, símbolos y embeddings?

En 2026, GitHub afirma que la arquitectura agentic de Copilot code review recupera contexto del repositorio, razona sobre cambios y generó un aumento inicial de 8,1% en feedback positivo (GitHub, "60 million Copilot code reviews and counting", 2026). La lección es práctica: la recuperación debe ser planeada, no incidental.

La búsqueda lexical es el primer filtro. Encuentra nombres exactos, mensajes de error, rutas, variables de entorno y comandos. Usa rg o un índice equivalente antes de embeddings. Si el error menciona SessionExpiredError, la búsqueda textual suele ser más confiable que una vecindad semántica.

Los símbolos aportan estructura. Un índice de definiciones y referencias entiende funciones, clases, exports, rutas y tipos. Eso evita que el agente confunda una cadena parecida con un contrato real. En TypeScript, por ejemplo, una búsqueda de referencias de tipo puede separar uso de producción, fixture y prueba.

Los embeddings entran cuando la pregunta es conceptual. "¿Dónde tratamos la expiración de sesión?" quizá no use las mismas palabras en todos los archivos. La búsqueda semántica encuentra candidatos. El reranking compara esos candidatos con símbolos y pruebas. El servidor MCP devuelve pocos resultados, no una pila de archivos.

Una buena respuesta tiene formato predecible:

{
  "consulta": "expiracion de sesion",
  "resultados": [
    {
      "archivo": "src/auth/session.service.ts",
      "fragmento": "funcion que renueva sesion antes de emitir nuevo token",
      "motivo": "define el comportamiento central de renovacion",
      "proximos_pasos": ["ejecutar prueba de sesion", "verificar revocacion"]
    }
  ],
  "limite": "resultado resumido por relevancia; usa buscar_referencia para ampliar"
}

Este contrato también ayuda a subagentes. Un subagente de seguridad puede consultar riesgo. Otro puede consultar pruebas. El agente principal recibe síntesis, no logs. Esa división encaja con el harness de agentes de código para PRs confiables, porque cada recuperación se vuelve evidencia revisable.

¿Cómo evitar que MCP se vuelva una brecha de seguridad?

En 2026, GitHub incorporó secret scanning al GitHub MCP Server para detectar secretos antes de commit o PR en IDEs y agentes compatibles con MCP (GitHub Changelog, "Secret scanning in AI coding agents via the GitHub MCP Server", 2026). Ese es el enfoque correcto: MCP debe reducir riesgo operativo, no ampliar permisos sin control.

Trata cada herramienta como una superficie de permiso. Una herramienta que lee código es distinta de una que abre PR. Una que consulta logs es distinta de una que consulta base de datos. Una que lista contratos es distinta de una que ejecuta migración. El agente no debe recibir todas porque "tal vez las necesite".

Usa alcance por workspace. Si Codex usa .codex/config.toml en un proyecto confiable, el servidor MCP de esa base debe resolver rutas dentro del proyecto. Si Claude Code ejecuta un servidor stdio, aprovecha la variable de directorio del proyecto para evitar rutas ambiguas. La regla es simple: una herramienta no debe cruzar a otro repositorio por accidente.

Audita llamadas. Registra herramienta, argumentos, archivos devueltos y tamaño de salida. No registres secretos. Si un PR de agente falla, ese log muestra si el error vino de la herramienta, el prompt, un índice desactualizado o una decisión del modelo. Sin log, el equipo solo debate síntomas.

En mi práctica, ese log es más útil cuando cabe en revisión humana. Quiero ver la consulta que llevó al archivo, no cada token devuelto por el índice. Si el agente eligió la prueba equivocada, el log muestra si recibió candidatos débiles o ignoró uno bueno.

También limita la salida. La documentación de Claude Code avisa cuando una herramienta MCP supera 10.000 tokens y usa un límite predeterminado de 25.000 tokens para salida (Claude Code Docs, "Connect Claude Code to tools via MCP", 2026). Incluso cuando la herramienta permite más, un buen RAG de codebase responde corto por defecto.

¿Cómo conectar esto con Codex y Claude Code?

En 2026, la documentación de Codex afirma que MCP vive en config.toml y puede tener alcance de proyecto con .codex/config.toml en proyectos confiables (OpenAI Developers, "Model Context Protocol - Codex", 2026). Esa configuración permite que CLI y extensión de IDE compartan los mismos servidores.

En Codex, trata el servidor de RAG de codebase como dependencia del repositorio. Su nombre, comando, permisos y alcance deben vivir cerca de la base, no perdidos en una configuración personal. Así, un agente que trabaja en un monorepo usa herramientas distintas de uno que trabaja en un servicio pequeño.

En Claude Code, MCP conecta herramientas, bases y APIs al flujo del agente. La propia documentación recomienda verificar confianza antes de conectar servidores, porque servidores que buscan contenido externo pueden exponer riesgo de prompt injection (Claude Code Docs, "Connect Claude Code to tools via MCP", 2026). Para RAG de codebase, eso significa preferir fuente local e índice controlado.

Un diseño mínimo puede verse así:

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

El servidor debe ofrecer pocas herramientas al principio. No implementes base vectorial, grafo de dependencias y análisis de PR el mismo día. Publica buscar_simbolo, buscar_referencia y encontrar_pruebas. Después mide qué preguntas el agente todavía hace manualmente.

Esta integración también debe aparecer en el PR. Pide al agente que registre "contexto consultado" en el cuerpo: herramienta, archivos devueltos y prueba elegida. Eso conecta MCP con el artículo sobre evals de PR para agentes de código en CI. Sin ese rastro, la recuperación mejora la sesión, pero no la revisión.

¿Cuál es el mínimo viable para esta semana?

En 2025, la encuesta de Stack Overflow mostró que 69% de usuarios de agentes percibieron aumento de productividad, pero solo 17% percibieron mejora de colaboración en equipo (Stack Overflow, "2025 Developer Survey: AI", 2025). El mínimo viable debe atacar esa brecha: convertir ganancia individual en contexto compartido y auditable.

Primero, elige un módulo con dolor real. Autenticación, cobros, colas o integraciones externas funcionan bien porque tienen contratos, pruebas y riesgo. No empieces por todo el monorepo. Un alcance pequeño revela el diseño correcto sin crear un índice caro y poco usado.

Segundo, crea tres herramientas. Una busca símbolos. Otra encuentra pruebas relacionadas. La tercera recupera decisiones de arquitectura desde archivos cortos, como ADRs o notas de diseño. Si no hay decisiones escritas, registra las tres más importantes antes de automatizar.

Tercero, define respuesta corta. Cada resultado debe tener archivo, fragmento, motivo y próximo paso. Si la herramienta no sabe, debe decirlo. Una herramienta que finge certeza entrena al agente a confiar en contexto equivocado.

Cuarto, corre un PR pequeño con rastro. El agente debe usar las herramientas, aplicar el patch, ejecutar una prueba y declarar qué consultó. Si el revisor entiende la cadena de contexto en menos de un minuto, el MVP funciona. Si necesita leer logs brutos, la salida sigue siendo demasiado grande.

FAQ sobre RAG de codebase con MCP

En 2026, GitHub reportó que más de 12.000 organizaciones ejecutan Copilot code review automáticamente en cada PR (GitHub, "60 million Copilot code reviews and counting", 2026). Las preguntas siguientes ayudan a convertir recuperación de contexto en práctica de plataforma.

¿MCP reemplaza el RAG tradicional sobre codebase?

No. En 2025, la especificación MCP separó recursos, prompts y herramientas (Model Context Protocol, "Specification 2025-11-25", 2025). RAG es la técnica de recuperación; MCP es la interfaz para que el agente pida esa recuperación dentro del flujo.

¿Necesito embeddings el primer día?

No. En 2026, GitHub atribuyó parte de la mejora del review agentic a recuperación inteligente de contexto, no a una técnica única (GitHub, "60 million Copilot code reviews and counting", 2026). Empieza con búsqueda lexical y símbolos. Añade embeddings cuando se escapen preguntas conceptuales.

¿MCP autoriza al agente a hacer cualquier cosa?

No debería. En 2026, la documentación de servidores MCP remotos de Anthropic recomienda conectar solo servidores confiables y revisar prácticas de seguridad y términos (Claude Platform Docs, "Remote MCP servers", 2026). En RAG de codebase, cada herramienta necesita alcance, límite y log.

¿Cómo medir si la capa de contexto mejoró?

Mide retrabajo de revisión. En 2025, Stack Overflow vio 69% de ganancia individual con agentes, pero solo 17% de mejora en colaboración (Stack Overflow, "2025 Developer Survey: AI", 2025). La capa mejoró cuando los PR llegan con menos archivos fuera de alcance y evidencia más clara.

Cierre

En 2026, Anthropic describió MCP como un estándar para conectar agentes a sistemas externos y reducir integraciones duplicadas (Anthropic, "Code execution with MCP: building more efficient AI agents", 2026). Para desarrollo de software, la aplicación más útil es simple: dar al agente una forma estrecha y auditable de preguntar por la codebase.

No empieces con infraestructura grande. Empieza con una interfaz pequeña. Tres herramientas, respuestas cortas, logs y un PR con rastro ya cambian la calidad del trabajo. Cuando la recuperación queda visible, el equipo puede mejorar el agente, el índice y la arquitectura del sistema.

Fuentes consultadas

• Google, "How are developers using AI? Inside our 2025 DORA report", recuperado el 2026-07-02, https://blog.google/innovation-and-ai/technology/developers-tools/dora-report-2025/
• GitHub, "60 million Copilot code reviews and counting", recuperado el 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 el 2026-07-02, https://modelcontextprotocol.io/specification/2025-11-25
• GitHub Changelog, "Secret scanning in AI coding agents via the GitHub MCP Server", recuperado el 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 el 2026-07-02, https://code.claude.com/docs/en/mcp
• OpenAI Developers, "Model Context Protocol - Codex", recuperado el 2026-07-02, https://developers.openai.com/codex/mcp
• Stack Overflow, "2025 Developer Survey: AI", recuperado el 2026-07-02, https://survey.stackoverflow.co/2025/ai
• Claude Platform Docs, "Remote MCP servers", recuperado el 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 el 2026-07-02, https://www.anthropic.com/engineering/code-execution-with-mcp