Conexión del Claude Agent SDK con servidores MCP

El Protocolo de Contexto del Modelo (MCP) es una forma estándar para que un agente llame a herramientas que residen fuera del SDK, en un proceso local o en un servidor remoto.

El Claude Agent SDK tiene soporte de cliente MCP de primera clase: registras un servidor, stdio para un proceso local o HTTP para uno remoto, y sus herramientas se vuelven invocables por el bucle de uso de herramientas de la misma manera que las herramientas integradas.

Resumen

Las herramientas integradas cubren la edición de archivos, bash y la web; MCP es cómo extiendes el bucle a cualquier otra cosa, una base de datos, una API interna, un sistema de tickets, un producto SaaS de terceros.

Un servidor MCP stdio se ejecuta como un subproceso en la misma máquina que tu agente y se comunica a través de la entrada/salida estándar.

Un servidor MCP HTTP se ejecuta de forma remota y se comunica a través de HTTP, útil cuando la herramienta reside en una infraestructura que no controlas directamente o quieres compartir entre varios agentes.

Esta página cubre el registro de ambos tipos de servidor y cómo sus herramientas interactúan con el resto del bucle una vez conectadas.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

from claude_agent_sdk import query, AgentOptions, McpServerConfig
 
options = AgentOptions(
    allowed_tools=["file_edit"],
    mcp_servers=[
        McpServerConfig(
            name="internal-search",
            transport="stdio",
            command=["python", "-m", "internal_search_mcp"],
        ),
        McpServerConfig(
            name="ticketing",
            transport="http",
            url="https://mcp.internal.example.com/ticketing",
        ),
    ],
)
 
async for message in query(
    prompt="Busca incidentes pasados relacionados y abre un ticket resumiendo este error.",
    options=options,
):
    print(message)

Cuándo usar esto:

• Una tarea necesita llamar a un sistema que no está cubierto por las herramientas de edición de archivos, bash o web.
• Ya tienes (o puedes configurar) un servidor MCP para ese sistema.
• Quieres reutilizar la misma herramienta en varios agentes o proyectos diferentes sin reescribir el código de integración cada vez.
• Necesitas una herramienta remota (HTTP) en lugar de una local (stdio) según dónde resida realmente la capacidad.

Ejemplo de trabajo

import asyncio
from claude_agent_sdk import query, AgentOptions, McpServerConfig
 
async def triage_incident(incident_description: str) -> None:
    options = AgentOptions(
        allowed_tools=["file_edit"],
        mcp_servers=[
            McpServerConfig(
                name="logs",
                transport="stdio",
                command=["node", "logs-mcp-server.js"],
                # Los servidores stdio no heredan acceso de red especial por defecto;
                # solo hacen lo que el proceso local está construido para hacer.
            ),
            McpServerConfig(
                name="pagerduty",
                transport="http",
                url="https://mcp.example.com/pagerduty",
                headers={"Authorization": "Bearer ${PAGERDUTY_MCP_TOKEN}"},
            ),
        ],
        # Las herramientas MCP se delimitan a través de allowed_tools como cualquier otra cosa;
        # nombrarlas explícitamente aquí evita que este agente llame a cada
        # herramienta que cualquier servidor pueda exponer.
        allowed_mcp_tools=["logs.search", "pagerduty.create_incident"],
    )
 
    prompt = (
        f"Se reportó un incidente: {incident_description}. Busca en los logs recientes "
        "errores relacionados, luego crea un incidente en PagerDuty resumiendo lo que "
        "encontraste, solo si encuentras una coincidencia genuina."
    )
 
    async for message in query(prompt=prompt, options=options):
        if message.get("type") == "text":
            print(message["text"], end="", flush=True)
        elif message.get("type") == "tool_call":
            print(f"\n[llamada a herramienta: {message['tool_name']}]")
 
asyncio.run(triage_incident("La API de Checkout devuelve intermitentemente 500 desde las 14:02 UTC"))

Lo que esto demuestra:

• Registro de un servidor local (stdio) para la búsqueda de logs y un servidor remoto (HTTP) para la paginación, emparejados con la ubicación real de cada capacidad.
• Paso de una cabecera de autenticación en el registro del servidor HTTP, ya que un servidor MCP remoto típicamente necesita su propia autenticación independiente de la clave API del SDK.
• Reducción de qué herramientas MCP específicas son invocables (allowed_mcp_tools) en lugar de exponer cada herramienta que un servidor pueda ofrecer.
• Un prompt que condiciona explícitamente la acción destructiva (abrir un incidente) a un hallazgo real, reduciendo la posibilidad de una página de falso positivo.

Profundización

Cómo funciona

• Registrar un servidor MCP con mcp_servers le dice al SDK cómo alcanzarlo (un comando de subproceso para stdio, una URL y cabeceras para HTTP) y que obtenga sus definiciones de herramientas al inicio.
• Una vez obtenidas, las herramientas del servidor se añaden al conjunto de herramientas disponibles del bucle junto con las herramientas integradas; desde la perspectiva del modelo durante el paso de decisión, una herramienta MCP y una herramienta integrada se ven igual, un nombre, una descripción y un esquema de argumentos.
• Un servidor stdio se comunica a través de los flujos de entrada/salida estándar del subproceso; el SDK gestiona el inicio, la comunicación y la eventual terminación de ese subproceso durante la ejecución.
• Un servidor HTTP se comunica a través de solicitudes HTTP ordinarias; puede ser compartido entre múltiples ejecuciones concurrentes de agentes y reside independientemente del ciclo de vida del proceso de cualquier agente individual.
• El ámbito de las herramientas todavía se aplica: allowed_tools/allowed_mcp_tools controlan cuáles de las herramientas expuestas por el servidor el bucle puede llamar realmente, el mismo modelo de ámbito en capas utilizado para las herramientas integradas.

stdio vs. HTTP de un vistazo

Notas de Python

# Los servidores stdio deben iniciarse con un comando explícito y mínimo;
# evita depender de la resolución de PATH ambiental que podría diferir entre
# tu máquina de desarrollo y un entorno de despliegue.
McpServerConfig(
    name="internal-search",
    transport="stdio",
    command=["python3", "/opt/mcp-servers/internal_search/main.py"],
)

Parámetros y Valores de retorno

Trampas

• Registrar un servidor y exponer todas las herramientas que ofrece. Un servidor construido para uso interno podría exponer más herramientas de las que un agente determinado necesita. Solución: usa allowed_mcp_tools para nombrar exactamente qué herramientas puede llamar este agente.
• Codificar secretos en las headers o command de un servidor. Comprometer un token de API directamente en AgentOptions corre el riesgo de filtrarlo a través de logs o control de versiones. Solución: lee secretos de variables de entorno en el momento de la llamada, no cadenas literales en el código.
• Asumir que el subproceso de un servidor stdio sobrevive a través de llamadas query() separadas. El ciclo de vida del proceso de un servidor stdio generalmente está ligado a la ejecución que lo inició. Solución: no confíes en que el estado del servidor stdio persista entre ejecuciones no relacionadas; usa un servidor HTTP si necesitas un proceso compartido de larga duración.
• No manejar un servidor MCP HTTP inalcanzable. Si el servidor remoto está caído, las llamadas a sus herramientas fallarán, y ese fallo retroalimentará al bucle como una observación sobre la que el modelo tiene que razonar. Solución: prueba el comportamiento de fallo deliberadamente y considera si el prompt debe tener en cuenta la indisponibilidad de una herramienta.
• Confiar ciegamente en las descripciones de herramientas de un servidor MCP. Una descripción de herramienta engañosa o maliciosa podría dirigir al modelo hacia llamadas no deseadas. Solución: solo registra servidores MCP en los que confíes y revisa sus descripciones de herramientas de la misma manera que revisarías el ámbito de una herramienta integrada.
• Confundir qué transporte necesita una integración dada. Elegir HTTP para algo que en realidad es una herramienta de desarrollo local (o viceversa) añade complejidad innecesaria. Solución: empareja el transporte con el lugar donde realmente reside la capacidad.

Alternativas

Preguntas frecuentes

Relacionados

• El Modelo Mental del Claude Agent SDK - cómo encajan las herramientas MCP en el bucle
• Habilitación de herramientas de edición de archivos, Bash y Web en el Agent SDK - ámbito de herramientas integradas, el mismo modelo aplicado a MCP
• Referencia de opciones de configuración del Claude Agent SDK - formas de opciones relacionadas con MCP
• Adición de puntos de control de Human-in-the-Loop a un flujo de trabajo del Agent SDK - puntos de control de llamadas MCP destructivas
• Referencia de patrones de despliegue del Claude Agent SDK - cómo la forma de despliegue afecta las elecciones de stdio vs. HTTP

Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el Claude Agent SDK (última versión, Python y TypeScript). Los nombres de modelos, versiones de SDK y precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.