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.
Busca en todas las páginas de la documentación
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.
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.
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:
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:
allowed_mcp_tools) en lugar de exponer cada herramienta que un servidor pueda ofrecer.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.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.| Transporte | Se ejecuta dónde | Bueno para | Consideración |
|---|---|---|---|
| stdio | Subproceso local, misma máquina que el agente | Acceso a archivos locales, herramientas de desarrollo locales, sin necesidad de salto de red | Ciclo de vida del proceso ligado a la ejecución del agente |
| HTTP | Servidor remoto | Infraestructura compartida, sistemas ya expuestos como servicio | Necesita su propia autenticación, la fiabilidad de la red se convierte en un factor |
# 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ámetro | Tipo | Descripción |
|---|---|---|
name | str | Identificador utilizado para referenciar las herramientas de este servidor |
transport | str | "stdio" o "http" |
command | list[str] | Comando del subproceso, solo stdio |
url | str | Punto final del servidor, solo HTTP |
headers | dict | Cabeceras de autenticación u otras enviadas con las solicitudes HTTP |
allowed_mcp_tools | list[str] | Lista blanca granular de herramientas específicas a través de los servidores registrados |
allowed_mcp_tools para nombrar exactamente qué herramientas puede llamar este agente.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.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.| Alternativa | Usar cuándo | No usar cuándo |
|---|---|---|
| Solo herramientas integradas | La tarea encaja completamente dentro de las capacidades de archivo/bash/web | La tarea necesita un sistema externo específico al que MCP pueda acceder |
| Herramienta personalizada conectada directamente a tu aplicación | Necesitas una integración muy específica y estrechamente acoplada y no la reutilizarás en otro lugar | Quieres que la misma herramienta sea reutilizable en múltiples agentes o proyectos |
| Un subagente que a su vez utiliza herramientas MCP | El trabajo respaldado por MCP es una subtarea autocontenida que vale la pena aislar | La llamada MCP es un paso pequeño y único en un flujo más grande |
Sí, las herramientas MCP se delimitan a través del mismo mecanismo de lista blanca (a menudo a través de una lista dedicada allowed_mcp_tools), por lo que controlas exactamente qué herramientas registradas puede llamar el bucle.
Sí, mcp_servers acepta una lista y puede mezclar servidores stdio y HTTP en una sola configuración de agente.
Al inicio, el SDK obtiene las definiciones de herramientas de cada servidor registrado (nombres, descripciones, esquemas de argumentos) y las añade al conjunto de herramientas disponibles del bucle, de la misma manera que se presentan las definiciones de herramientas integradas.
Las llamadas a las herramientas de ese servidor fallan, y ese fallo retroalimenta al bucle como una observación que el modelo tiene que razonar, igual que cualquier otra llamada a herramienta fallida.
Solo si no existe ya uno adecuado para el sistema que necesitas; MCP es un protocolo, por lo que los servidores construidos por terceros o tu propio equipo funcionan siempre que hablen su idioma.
Sí, mcp_servers y allowed_mcp_tools se establecen por AgentOptions, por lo que las propias opciones de un subagente pueden registrar un conjunto diferente (o más estrecho) que las de su padre.
El SDK pasa las cabeceras que configures; el esquema de autenticación real (token de portador, clave API, etc.) lo define el servidor y se suministra a través de headers en tu registro.
Si una herramienta MCP realiza una acción destructiva o irreversible, sí; la configuración de puntos de control (checkpoint_tools) se aplica a las herramientas MCP de la misma manera que se aplica a las integradas.
Puede hacerlo, en principio, ya que las herramientas MCP son simplemente herramientas con nombre y esquemas. Sé deliberado sobre el ámbito si registras un servidor cuyas herramientas puedan entrar en conflicto o solaparse en propósito con una herramienta integrada.
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.
Revisado por Chris St. John·Última actualización: 16 jul 2026