MCP connector

Claude Managed Agents supports connecting Model Context Protocol (MCP) servers to your agents. This gives the agent access to external tools, data sources, and services through a standardized protocol.

MCP configuration is split across two steps:

1. Agent creation declares which MCP servers the agent connects to, by name and URL.
2. Session creation supplies auth for those servers by referencing a pre-registered vault.

This separation keeps secrets out of reusable agent definitions while letting each session authenticate with its own credentials.

Declare MCP servers on the agent

Specify MCP servers in the mcp_servers array when creating an agent. Each server needs a type, a unique name, and a url. No auth tokens are provided at this stage.

The name you assign in the MCP server array is used to reference the mcp_toolset entries in the tools array.

AGENT_ID=$(ant beta:agents create \
  --name "GitHub Assistant" \
  --model claude-opus-4-7 \
  --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)

mcp_servers field reference

Each entry in the mcp_servers array defines one connection.

Constraints:

• An agent can declare up to 20 MCP servers. Server names must be unique within the array.
• Every mcp_servers entry must be referenced by an mcp_toolset in the tools array, and every mcp_toolset must reference a declared server. The API rejects agent definitions with unreferenced servers or dangling toolsets.

Configure which MCP tools are available

The mcp_toolset entry supports the same default_config and configs shape as the built-in agent toolset, applied to the tools the MCP server exposes. The name in each configs entry is the bare tool name as reported by the server.

By default all tools exposed by the MCP server are enabled. To enable only specific tools, set default_config.enabled to false and explicitly enable the tools you want:

{
  "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 }
  ]
}

This pattern is useful when a server exposes many tools but the agent only needs a few, or when you want tools added by the server operator to stay off until you review them.

To disable specific tools while keeping the rest enabled, omit default_config and set enabled: false on individual entries:

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

See configuring the toolset for the general default_config / configs pattern, and MCP toolset permissions for setting permission_policy on MCP tools and handling confirmation requests.

MCP tool output handling

When an MCP tool output exceeds 100k tokens, it is automatically written to a file in the sandbox. The model receives a truncated preview with the file path and can read the full content from there.

Provide authentication at session creation

When starting a session, pass vault_ids to provide credentials for your MCP servers. Vaults are collections of credentials that you register once and reference by ID. See Authenticate with vaults for how to create vaults and manage credentials.

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

Credentials are matched by URL, so the vault must contain a credential whose mcp_server_url exactly matches the url declared in mcp_servers; if none matches, the connection is attempted unauthenticated. See Add a credential for the static_bearer and mcp_oauth credential types.

Handle connection and authentication failures

Session creation does not validate MCP connectivity or credentials. If an MCP server is unreachable or rejects the supplied credential, the session still starts and interaction remains possible. A session.error event is emitted with the mcp_server_name of the affected server and a retry_status:

You can decide whether to block further interaction on this error, trigger a credential rotation, or let the session continue without the affected server's tools. The connection is retried on the next session.status_idle to session.status_running transition. See Session event stream for details on consuming session.error and other events.

Supported MCP server types

Claude Managed Agents connects to remote MCP servers that expose an HTTP endpoint, or to private MCP servers through MCP tunnels. The server must support the MCP protocol's streamable HTTP transport.

For more information on MCP and building MCP servers, see the MCP documentation.