Conector MCP

Claude Managed Agents admite la conexión de servidores Model Context Protocol (MCP) a tus agentes. Esto le da al agente acceso a herramientas externas, fuentes de datos y servicios a través de un protocolo estandarizado.

La configuración de MCP se divide en dos pasos:

1. La creación del agente declara a qué servidores MCP se conecta el agente, por nombre y URL.
2. La creación de la sesión proporciona la autenticación para esos servidores haciendo referencia a un vault (bóveda) previamente registrado (consulta Autenticar con vaults).

Esta separación mantiene los secretos fuera de las definiciones de agentes reutilizables, a la vez que permite que cada sesión se autentique con sus propias credenciales.

Declarar servidores MCP en el agente

Especifica los servidores MCP en el array mcp_servers al crear un agente. Cada servidor necesita un type, un name único y una url. En esta etapa no se proporcionan tokens de autenticación.

Cada servidor declarado también necesita una entrada mcp_toolset correspondiente en el array tools. El mcp_server_name del toolset debe coincidir con el name del servidor.

ant apply github-assistant.md

---
name: GitHub Assistant
model: claude-opus-5-5
mcp_servers:
  - type: url
    name: github
    url: https://api.githubcopilot.com/mcp/
tools:
  - type: agent_toolset_20260401
  - type: mcp_toolset
    mcp_server_name: github
---

Referencia del campo mcp_servers

Cada entrada en el array mcp_servers define una conexión.

Restricciones:

• Un agente puede declarar hasta 20 servidores MCP. Los nombres de los servidores deben ser únicos dentro del array.
• Cada entrada de mcp_servers debe estar referenciada por un mcp_toolset en el array tools, y cada mcp_toolset debe hacer referencia a un servidor declarado. La API rechaza las definiciones de agentes con servidores no referenciados o toolsets huérfanos.

Configurar qué herramientas MCP están disponibles

La entrada mcp_toolset admite un objeto default_config y un array configs, que se aplican a las herramientas que expone el servidor MCP. Cada entrada de configs acepta únicamente name, enabled y permission_policy. A diferencia de las entradas del toolset integrado del agente, las entradas de herramientas MCP no llevan un campo type, y la configuración web disponible en web_search y web_fetch no se aplica a las herramientas MCP. El name en cada entrada de configs es el nombre simple de la herramienta tal como lo reporta el servidor.

De forma predeterminada, todas las herramientas expuestas por el servidor MCP están habilitadas. Para habilitar solo herramientas específicas, establece default_config.enabled en false y habilita explícitamente las herramientas que quieras:

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "get_issue", "enabled": true },
    { "name": "list_issues", "enabled": true },
    { "name": "add_issue_comment", "enabled": true }
  ]
}

Este patrón es útil cuando un servidor expone muchas herramientas pero el agente solo necesita unas pocas, o cuando quieres que las herramientas añadidas por el operador del servidor permanezcan desactivadas hasta que las revises.

Para deshabilitar herramientas específicas manteniendo el resto habilitadas, omite default_config y establece enabled: false en las entradas individuales:

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "configs": [{ "name": "delete_repository", "enabled": false }]
}

Consulta configurar el toolset para conocer el patrón general de default_config / configs, y permisos del toolset MCP para establecer permission_policy en las herramientas MCP y gestionar las solicitudes de confirmación.

Manejo de la salida de herramientas MCP

Cuando la salida de una herramienta MCP supera los 100,000 caracteres (aproximadamente 25,000 tokens), se escribe automáticamente en un archivo en el sandbox. El modelo recibe una vista previa truncada con la ruta del archivo y puede leer el contenido completo desde allí.

Proporcionar autenticación al crear la sesión

Al iniciar una sesión, pasa vault_ids para proporcionar credenciales para tus servidores MCP. Los vaults son colecciones de credenciales que registras una vez y a las que haces referencia por ID. Consulta Autenticar con vaults para saber cómo crear vaults y gestionar credenciales.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

Las credenciales se asocian por URL, por lo que el vault debe contener una credencial cuyo mcp_server_url haga referencia al mismo servidor que la url declarada en mcp_servers. Ambas URL se normalizan antes de la comparación (el esquema y el host se convierten a minúsculas, y se eliminan los puertos predeterminados y las barras finales), de modo que las diferencias en las mayúsculas del host, un puerto predeterminado o una barra final no impiden la coincidencia; una ruta, un subdominio o un puerto no predeterminado diferentes sí lo hacen. Si ninguna coincide, la conexión se intenta sin autenticación. Consulta Agregar una credencial para conocer los tipos de credenciales static_bearer y mcp_oauth.

Manejar fallos de conexión y autenticación

La creación de la sesión no valida la conectividad ni las credenciales de MCP. Si un servidor MCP no está accesible o rechaza la credencial proporcionada, la sesión se inicia de todos modos y la interacción sigue siendo posible. Se emite un evento session.error con el mcp_server_name del servidor afectado y un retry_status:

Puedes decidir si bloquear la interacción posterior ante este error, activar una rotación de credenciales o dejar que la sesión continúe sin las herramientas del servidor afectado. La conexión se reintenta en la siguiente transición de session.status_idle a session.status_running.

Próximos pasos