Context7 MCP: cómo crear un agente de IA con Agno (2026)

La mayoría de los asistentes de código con IA te dan respuestas basadas en datos de entrenamiento de hace meses o años. Si alguna vez has recibido una llamada a una API alucinada o el nombre de una función obsoleta de ChatGPT, conoces el problema. Context7 MCP lo soluciona dando a tu agente de IA acceso en vivo a la documentación actual de las bibliotecas y a fragmentos de código, y Agno es el framework de agentes que lo une todo.

MCP son las siglas de Model Context Protocol, un estándar abierto que permite a los agentes de IA llamar a herramientas externas a través de una interfaz uniforme. Context7 es un servicio (de Upstash) que expone la documentación de miles de bibliotecas a través de MCP. Agno es un framework de agentes en Python que gestiona el bucle del agente, la orquestación de herramientas y la salida en streaming.

Esta guía te lleva paso a paso por la creación de un agente de IA funcional en Python que obtiene documentación actualizada de bibliotecas bajo demanda. Al final tendrás un agente interactivo en funcionamiento.

¿Por qué usar Context7 con Agno?

Context7 ofrece documentación actualizada y ejemplos de código optimizados para LLMs. Combinado con Agno, obtienes un agente que:

• Obtiene dinámicamente la documentación más reciente de la API de cualquier biblioteca.
• Recupera fragmentos de código relevantes para demostrar el uso de la biblioteca.
• Responde a consultas complejas sobre funciones de la biblioteca, patrones de uso o resolución de problemas.
• Agiliza los flujos de trabajo de los desarrolladores proporcionando asistencia instantánea y consciente del contexto.

Así es como funciona: tu script de Python lanza el servidor MCP de Context7 como un subproceso local de npx (transporte stdio). La clase MCPTools de Agno actúa como cliente MCP, conectándose a ese subproceso. Cuando le haces una pregunta al agente, este llama a las herramientas de Context7 (resolve-library-id y luego query-docs) y devuelve los resultados en formato Markdown.

Requisitos previos

Si eres nuevo en Agno, empieza primero con Primeros pasos con los agentes de Agno. Cubre la instalación, la memoria y los conceptos básicos de RAG.

Paso 1: Configura tu entorno

Crea un entorno virtual e instala los paquetes necesarios:

uv venv --python 3.12
source .venv/bin/activate
uv pip install -U "agno[mcp]" openai

Verifica que Node.js esté disponible y sea lo suficientemente reciente:

node --version   # need 18+
npm --version

Configura tus claves de API:

export OPENAI_API_KEY="sk-..."
# optional: higher Context7 rate limits
export CONTEXT7_API_KEY="ctx7_..."

source .venv/bin/activate
export OPENAI_API_KEY="sk-..."

.venv\Scripts\activate
set OPENAI_API_KEY=sk-...

Verifica la instalación:

python -c "import agno; print(agno.__version__)"

Deberías ver un número de versión 2.x. Si obtienes ModuleNotFoundError, el entorno virtual no está activo o la instalación falló.

Paso 2: Entiende las herramientas MCP de Context7

El servidor MCP de Context7 expone dos herramientas:

El flujo consta siempre de dos pasos: resolver el nombre de la biblioteca a un ID y luego consultar ese ID para obtener la documentación. El agente gestiona esto automáticamente basándose en sus instrucciones.

Context7 también ofrece un endpoint MCP alojado en https://mcp.context7.com/mcp si prefieres no ejecutar el subproceso local de npx. Para esta guía usaremos el enfoque local, ya que es más sencillo de configurar.

Paso 3: Crea el agente de IA

Agente mínimo (una sola ejecución)

Empieza con el script funcional más corto posible para verificar la integración:

import asyncio
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.mcp import MCPTools

async def main():
    mcp_tools = MCPTools(command="npx -y @upstash/context7-mcp@latest")
    await mcp_tools.connect()

    try:
        agent = Agent(
            model=OpenAIResponses(id="gpt-5.4-mini"),
            tools=[mcp_tools],
            markdown=True,
            show_tool_calls=True,
        )
        await agent.aprint_response(
            "How do I make a GET request with the requests library?", stream=True
        )
    finally:
        await mcp_tools.close()

asyncio.run(main())

Guárdalo como main.py y ejecútalo:

python main.py

Si esto se ejecuta y ves llamadas a herramientas seguidas de la documentación, la integración funciona. Pasa al script interactivo completo.

Script interactivo completo

Aquí está el script completo con un bucle interactivo, manejo de errores y un ciclo de vida de conexión limpio:

import os
import asyncio
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.mcp import MCPTools

if "OPENAI_API_KEY" not in os.environ:
    raise ValueError("OPENAI_API_KEY environment variable is not set.")

INSTRUCTIONS = '''
You help users find up-to-date library documentation and code snippets via Context7.

When a user asks about a library:
1. Call `resolve-library-id` with `libraryName` set to the library name
   and `query` set to the user's full question.
2. Take the Context7 library ID it returns (slash-prefixed) and call
   `query-docs` with `libraryId` set to that ID and `query` set to the
   user's question/topic.
3. Return the documentation and code snippets in clear, concise Markdown.
Always explain which tools you called and show the results.
'''

async def main():
    mcp_tools = MCPTools(command="npx -y @upstash/context7-mcp@latest")
    await mcp_tools.connect()

    try:
        agent = Agent(
            name="Agno Context7 Doc Agent",
            role="An AI assistant that fetches up-to-date docs and code snippets using Context7 MCP.",
            model=OpenAIResponses(id="gpt-5.4-mini"),
            tools=[mcp_tools],
            instructions=INSTRUCTIONS,
            show_tool_calls=True,
            add_state_in_messages=True,
            markdown=True,
        )
        print("Agno Context7 Documentation Agent\n---------------------------------")
        print("Ask about a library. Type 'exit' or 'quit' to stop.\n")
        while True:
            user_input = input("\nYou: ").strip()
            if user_input.lower() in {"exit", "quit"}:
                print("Goodbye!")
                break
            try:
                await agent.aprint_response(user_input, stream=True)
            except Exception as e:
                print(f"\nError: {e}")
    finally:
        await mcp_tools.close()

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("\nInterrupted. Exiting.")

Algunas cosas a tener en cuenta sobre este script:

• try/finally garantiza que mcp_tools.close() se ejecute incluso si el script se interrumpe. Sin esto, el subproceso npx puede quedar huérfano.
• Las instrucciones son agnósticas a las herramientas. Hacen referencia a los nombres de las herramientas pero no fijan los esquemas de parámetros. Si Context7 renombra un parámetro en una versión futura, el agente seguirá funcionando porque lee las descripciones de las herramientas del servidor MCP.
• add_state_in_messages=True permite al agente mantener el contexto de la conversación entre turnos.

Cómo pasar una clave de API de Context7

Si tienes una clave de API de Context7 (gratis en context7.com/dashboard), pásala al servidor MCP mediante el parámetro env:

mcp_tools = MCPTools(
    command="npx -y @upstash/context7-mcp@latest",
    env={"CONTEXT7_API_KEY": os.getenv("CONTEXT7_API_KEY")},
)

Esto te da límites de peticiones más altos en el nivel gratuito.

Paso 4: Verifica que funciona

Después de ejecutar el script completo, prueba con algunas consultas:

You: requests how to make a GET request

Deberías ver:

1. El agente llama a resolve-library-id con libraryName="requests" y query="how to make a GET request".
2. Recibe un ID de biblioteca con prefijo de barra (algo como /psf/requests; el ID exacto depende del índice de Context7).
3. Llama a query-docs con ese ID de biblioteca y la consulta.
4. Devuelve en streaming la documentación formateada y los fragmentos de código.

Si el agente responde sin llamar a ninguna herramienta, comprueba que tools=[mcp_tools] esté configurado y que mcp_tools.connect() se haya completado sin errores.

Solución de problemas y costes

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install 22

source .venv/bin/activate
uv pip install -U "agno[mcp]" openai

Precios de Context7

El nivel gratuito se redujo a principios de 2026. Se recomienda encarecidamente una clave de API incluso en el plan gratuito, ya que te da límites de peticiones más altos. Consigue una en context7.com/dashboard.

Costes del modelo

GPT-5.4-mini cuesta aproximadamente 0,75 $ por millón de tokens de entrada y 4,50 $ por millón de tokens de salida. Una consulta de documentación típica de ida y vuelta (2-3 llamadas a herramientas más la respuesta final) cuesta fracciones de céntimo. Para razonamientos complejos con varias bibliotecas, gpt-5.4 está disponible pero es más caro.

Fijar versión vs @latest

Usar @latest significa que una subida de versión mayor de Context7 puede cambiar los esquemas de las herramientas sin avisar. Esto ya ocurrió con v4.0.0. Para configuraciones reproducibles, fija una versión:

npx -y @upstash/[email protected]

El compromiso: la versión fijada es estable pero no corrige errores automáticamente; @latest está al día pero puede romperse en las versiones mayores.

Buenas prácticas y optimización

• Instrucciones agnósticas a las herramientas. No fijes los nombres de los parámetros de las herramientas MCP en las instrucciones del agente: cambian entre versiones de Context7. Las instrucciones del Paso 3 son deliberadamente genéricas.
• Guarda en caché los IDs de las bibliotecas. Si consultas la misma biblioteca repetidamente, guarda en caché el ID devuelto por resolve-library-id para ahorrarte una ida y vuelta.
• Manejo de errores. Envuelve aprint_response en try/except. Registra los errores para depurar.
• Selección del modelo. gpt-5.4-mini para la mayoría de las consultas (rápido, barato). gpt-5.4 para razonamientos complejos con varias bibliotecas.
• Seguridad. Valida las entradas del usuario. No pases texto sin procesar del usuario a comandos de shell.
• Telemetría. Define AGNO_TELEMETRY=false para desactivar la telemetría de Agno si lo prefieres.
• Ciclo de vida de la conexión. Cierra siempre las herramientas MCP con close() en un bloque finally para evitar fugas de subprocesos.

Si estás decidiendo entre las herramientas MCP y las herramientas integradas de Agno, consulta MCP vs herramientas nativas para una comparación de cuándo tiene sentido cada enfoque.

Otros servidores MCP y el toolkit de Agno

El ecosistema MCP ha crecido significativamente. Ahora hay cientos de servidores disponibles a través del registro oficial de MCP. Puedes conectar Agno a cualquiera de ellos usando el mismo patrón MCPTools. Algunos ejemplos:

• BrightData MCP para web scraping: accede a datos web a escala a través de una interfaz MCP. Bright Data proporciona la plataforma de datos web detrás de él.
• Supabase MCP: consulta y gestiona tus bases de datos de Supabase.
• Airtable MCP: interactúa con bases de Airtable de forma programática.

Agno también tiene su propio toolkit con herramientas integradas (búsqueda web, operaciones con archivos, etc.) que no requieren MCP. Consulta la documentación de herramientas de Agno para la lista completa.

Nota: MultiMCPTools (para conectar varios servidores MCP) está obsoleto. Usa varias instancias de MCPTools en su lugar, cada una con su propio ciclo de vida connect()/close().

Conclusiones

Agno más Context7 MCP te da un agente de IA con acceso a la documentación actual de las bibliotecas: sin datos de entrenamiento obsoletos ni llamadas a API alucinadas. El agente resuelve los nombres de las bibliotecas a IDs, consulta la documentación en vivo y devuelve los resultados formateados en streaming.

Algunas formas de ampliar esto:

• Varios servidores MCP. Añade más instancias de MCPTools para diferentes fuentes de documentación.
• Agentes especializados. Crea agentes específicos de dominio para desarrollo web, ciencia de datos o DevOps. Consulta Escuadrón de investigación con IA en Agno para un enfoque multiagente.
• Agno Workflows. Encadena este agente en un pipeline más grande con Agno Workflows.
• Endpoint alojado. Prescinde por completo de Node.js local usando el endpoint MCP alojado de Context7 en https://mcp.context7.com/mcp.
• Alternativa CLI. Prueba la CLI ctx7 (npx ctx7 setup) para una configuración sin MCP.
• Bot de Discord. Envuelve este agente en un bot de Discord: consulta cómo crear un bot de IA para Discord con Agno.

Si estás explorando otros frameworks de agentes, también puedes crear un agente de IA con Mastra (basado en TypeScript).