Conector MCP

Claude Managed Agents admite la conexión de servidores de "Model Context Protocol", o 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 registrado previamente.

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



Declarar servidores MCP en el agente

Especifica los servidores MCP en el arreglo 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 arreglo tools. El mcp_server_name del toolset debe coincidir con el name del servidor.

AGENT_ID=$(ant beta:agents create \
  --name "GitHub Assistant" \
  --model claude-opus-4-8 \
  --mcp-server '{type: url, name: github, url: "https://api.githubcopilot.com/mcp/"}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: mcp_toolset, mcp_server_name: github}' \
  --transform id --raw-output)



Referencia del campo mcp_servers

Cada entrada en el arreglo 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 arreglo.
• Cada entrada de mcp_servers debe ser referenciada por un mcp_toolset en el arreglo tools, y cada mcp_toolset debe referenciar un servidor declarado. La API rechaza las definiciones de agentes con servidores no referenciados o toolsets sin correspondencia.



Configurar qué herramientas MCP están disponibles

La entrada mcp_toolset admite la misma estructura de default_config y configs que el toolset integrado del agente, aplicada a las herramientas que expone el servidor 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 deseas:

{
  "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 agregadas por el operador del servidor permanezcan desactivadas hasta que las revises.

Para deshabilitar herramientas específicas mientras mantienes el resto habilitado, omite default_config y establece enabled: false en 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 de MCP para establecer permission_policy en herramientas MCP y manejar solicitudes de confirmación.



Manejo de la salida de herramientas MCP

Cuando la salida de una herramienta MCP supera los 100,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 referencias por ID. Consulta Autenticar con vaults para saber cómo crear vaults y administrar credenciales.

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

Las credenciales se emparejan por URL, por lo que el vault debe contener una credencial cuyo mcp_server_url coincida exactamente con la url declarada en mcp_servers. 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 permitir 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