Python 88.3%
TypeScript 7.6%
Shell 4.1%
1---2title: MCP connector3url: https://platform.claude.com/docs/en/managed-agents/mcp-connector4description: Connect MCP servers to your agents for access to external tools and data sources.5---67## Compatibility8- Status: Beta9- [Beta header](https://platform.claude.com/docs/en/api/beta-headers): `managed-agents-2026-04-01`1011Claude Managed Agents supports connecting [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers to your agents. This gives the agent access to external tools, data sources, and services through a standardized protocol.1213MCP configuration is split across two steps:14151. **Agent creation** declares which MCP servers the agent connects to, by name and URL.162. **Session creation** supplies authentication for those servers by referencing a pre-registered vault (see [Authenticate with vaults](https://platform.claude.com/docs/en/managed-agents/vaults)).1718This separation keeps secrets out of reusable agent definitions while letting each session authenticate with its own credentials.1920## Declare MCP servers on the agent2122Specify MCP servers in the `mcp_servers` array when creating an agent. Each server needs a `type`, a unique `name`, and a `url`. No authentication tokens are provided at this stage.2324Each declared server also needs a matching `mcp_toolset` entry in the `tools` array. The toolset's `mcp_server_name` must match the server's `name`.2526<CodeGroup defaultLanguage="CLI">27 ```bash cURL28 agent_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/agents \29 -H "x-api-key: $ANTHROPIC_API_KEY" \30 -H "anthropic-version: 2023-06-01" \31 -H "anthropic-beta: managed-agents-2026-04-01" \32 -H "content-type: application/json" \33 -d @- <<'EOF'34 {35 "name": "GitHub Assistant",36 "model": "claude-opus-5",37 "mcp_servers": [38 {39 "type": "url",40 "name": "github",41 "url": "https://api.githubcopilot.com/mcp/"42 }43 ],44 "tools": [45 {"type": "agent_toolset_20260401"},46 {"type": "mcp_toolset", "mcp_server_name": "github"}47 ]48 }49 EOF50 )51 agent_id=$(jq -r '.id' <<<"$agent_response")52 ```5354 <MultiFileExample language="cli" label="CLI">55 ```bash CLI56 ant apply github-assistant.md57 ```5859 <File filename="github-assistant.md">60 ```markdown61 ---62 name: GitHub Assistant63 model: claude-opus-564 mcp_servers:65 - type: url66 name: github67 url: https://api.githubcopilot.com/mcp/68 tools:69 - type: agent_toolset_2026040170 - type: mcp_toolset71 mcp_server_name: github72 ---73 ```74 </File>75 </MultiFileExample>7677 ```python Python78 agent = client.beta.agents.create(79 name="GitHub Assistant",80 model="claude-opus-5",81 mcp_servers=[82 {83 "type": "url",84 "name": "github",85 "url": "https://api.githubcopilot.com/mcp/",86 },87 ],88 tools=[89 {"type": "agent_toolset_20260401"},90 {"type": "mcp_toolset", "mcp_server_name": "github"},91 ],92 )93 ```9495 ```typescript TypeScript96 const agent = await client.beta.agents.create({97 name: "GitHub Assistant",98 model: "claude-opus-5",99 mcp_servers: [100 {101 type: "url",102 name: "github",103 url: "https://api.githubcopilot.com/mcp/",104 },105 ],106 tools: [107 { type: "agent_toolset_20260401" },108 { type: "mcp_toolset", mcp_server_name: "github" },109 ],110 });111 ```112113 ```csharp C#114 var agent = await client.Beta.Agents.Create(new()115 {116 Name = "GitHub Assistant",117 Model = BetaManagedAgentsModel.ClaudeOpus5,118 McpServers =119 [120 new() { Type = "url", Name = "github", Url = "https://api.githubcopilot.com/mcp/" },121 ],122 Tools =123 [124 new BetaManagedAgentsAgentToolset20260401Params125 {126 Type = "agent_toolset_20260401",127 },128 new BetaManagedAgentsMcpToolsetParams { Type = "mcp_toolset", McpServerName = "github" },129 ],130 });131 ```132133 ```go Go134 agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{135 Name: "GitHub Assistant",136 Model: anthropic.BetaManagedAgentsModelConfigParams{137 ID: anthropic.BetaManagedAgentsModelClaudeOpus5,138 },139 MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{140 Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL,141 Name: "github",142 URL: "https://api.githubcopilot.com/mcp/",143 }},144 Tools: []anthropic.BetaAgentNewParamsToolUnion{145 {146 OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{147 Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,148 },149 },150 {151 OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{152 Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset,153 MCPServerName: "github",154 },155 },156 },157 })158 if err != nil {159 panic(err)160 }161 ```162163 ```java Java164 var agent = client.beta().agents().create(165 AgentCreateParams.builder()166 .name("GitHub Assistant")167 .model(BetaManagedAgentsModel.CLAUDE_OPUS_5)168 .addMcpServer(169 BetaManagedAgentsUrlMcpServerParams.builder()170 .type(BetaManagedAgentsUrlMcpServerParams.Type.URL)171 .name("github")172 .url("https://api.githubcopilot.com/mcp/")173 .build()174 )175 .addTool(176 BetaManagedAgentsAgentToolset20260401Params.builder()177 .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)178 .build()179 )180 .addTool(181 BetaManagedAgentsMcpToolsetParams.builder()182 .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET)183 .mcpServerName("github")184 .build()185 )186 .build()187 );188 ```189190 ```php PHP191 $agent = $client->beta->agents->create(192 name: 'GitHub Assistant',193 model: 'claude-opus-5',194 mcpServers: [195 BetaManagedAgentsURLMCPServerParams::with(196 type: 'url',197 name: 'github',198 url: 'https://api.githubcopilot.com/mcp/',199 ),200 ],201 tools: [202 BetaManagedAgentsAgentToolset20260401Params::with(203 type: 'agent_toolset_20260401',204 ),205 BetaManagedAgentsMCPToolsetParams::with(206 type: 'mcp_toolset',207 mcpServerName: 'github',208 ),209 ],210 );211 ```212213 ```ruby Ruby214 agent = client.beta.agents.create(215 name: "GitHub Assistant",216 model: "claude-opus-5",217 mcp_servers: [218 {219 type: "url",220 name: "github",221 url: "https://api.githubcopilot.com/mcp/"222 }223 ],224 tools: [225 {type: "agent_toolset_20260401"},226 {type: "mcp_toolset", mcp_server_name: "github"}227 ]228 )229 ```230</CodeGroup>231232<Tip>233 The MCP toolset defaults to a permission policy of `always_ask`, which requires user approval before each tool call. See [permission policies](https://platform.claude.com/docs/en/managed-agents/permission-policies) to configure this behavior.234</Tip>235236### `mcp_servers` field reference237238Each entry in the `mcp_servers` array defines one connection.239240| Field | Description |241| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |242| `type` | Required. Must be `"url"`. |243| `name` | Required. A unique name for this server within the agent (1–255 characters). Used as the `mcp_server_name` in the `tools` array and surfaced on MCP tool events in the [session event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming). |244| `url` | Required. The endpoint of the remote MCP server (up to 2,048 characters). See [Supported MCP server types](https://platform.claude.com/docs/en/managed-agents/reference#supported-mcp-server-types) for transport requirements. |245246Constraints:247248* An agent can declare up to 20 MCP servers. Server names must be unique within the array.249* 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.250251## Configure which MCP tools are available252253The `mcp_toolset` entry supports a `default_config` object and a `configs` array, applied to the tools the MCP server exposes. Each `configs` entry accepts only `name`, `enabled`, and `permission_policy`. Unlike entries in the built-in agent toolset, MCP tool entries do not take a `type` field, and the [web settings](https://platform.claude.com/docs/en/managed-agents/tools#restrict-web-search-and-web-fetch-domains) available on `web_search` and `web_fetch` do not apply to MCP tools. The `name` in each `configs` entry is the bare tool name as reported by the server.254255By 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:256257```json258{259 "type": "mcp_toolset",260 "mcp_server_name": "github",261 "default_config": { "enabled": false },262 "configs": [263 { "name": "get_issue", "enabled": true },264 { "name": "list_issues", "enabled": true },265 { "name": "add_issue_comment", "enabled": true }266 ]267}268```269270This 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.271272To disable specific tools while keeping the rest enabled, omit `default_config` and set `enabled: false` on individual entries:273274```json275{276 "type": "mcp_toolset",277 "mcp_server_name": "github",278 "configs": [{ "name": "delete_repository", "enabled": false }]279}280```281282See [configuring the toolset](https://platform.claude.com/docs/en/managed-agents/tools#configuring-the-toolset) for the general `default_config` / `configs` pattern, and [MCP toolset permissions](https://platform.claude.com/docs/en/managed-agents/permission-policies#mcp-toolset-permissions) for setting `permission_policy` on MCP tools and handling confirmation requests.283284### MCP tool output handling285286When an MCP tool output exceeds 100,000 characters (about 25,000 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.287288## Provide authentication at session creation289290When 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](https://platform.claude.com/docs/en/managed-agents/vaults) for how to create vaults and manage credentials.291292<CodeGroup>293 ```bash cURL294 session_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \295 -H "x-api-key: $ANTHROPIC_API_KEY" \296 -H "anthropic-version: 2023-06-01" \297 -H "anthropic-beta: managed-agents-2026-04-01" \298 -H "content-type: application/json" \299 -d @- <<EOF300 {301 "agent": "$agent_id",302 "environment_id": "$environment_id",303 "vault_ids": ["$vault_id"]304 }305 EOF306 )307 session_id=$(jq -r '.id' <<<"$session_response")308 ```309310 ```bash CLI311 SESSION_ID=$(ant beta:sessions create \312 --agent "$AGENT_ID" \313 --environment-id "$ENVIRONMENT_ID" \314 --vault-id "$VAULT_ID" \315 --transform id --raw-output)316 ```317318 ```python Python319 session = client.beta.sessions.create(320 agent=agent.id,321 environment_id=environment.id,322 vault_ids=[vault.id],323 )324 ```325326 ```typescript TypeScript327 const session = await client.beta.sessions.create({328 agent: agent.id,329 environment_id: environment.id,330 vault_ids: [vault.id],331 });332 ```333334 ```csharp C#335 var session = await client.Beta.Sessions.Create(new()336 {337 Agent = agent.ID,338 EnvironmentID = environment.ID,339 VaultIds = [vault.ID],340 });341 ```342343 ```go Go344 session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{345 Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},346 EnvironmentID: environment.ID,347 VaultIDs: []string{vault.ID},348 })349 if err != nil {350 panic(err)351 }352 ```353354 ```java Java355 var session = client.beta().sessions().create(356 SessionCreateParams.builder()357 .agent(agent.id())358 .environmentId(environment.id())359 .addVaultId(vault.id())360 .build()361 );362 ```363364 ```php PHP365 $session = $client->beta->sessions->create(366 agent: $agent->id,367 environmentID: $environment->id,368 vaultIDs: [$vault->id],369 );370 ```371372 ```ruby Ruby373 session = client.beta.sessions.create(374 agent: agent.id,375 environment_id: environment.id,376 vault_ids: [vault.id]377 )378 ```379</CodeGroup>380381Credentials are matched by URL, so the vault must contain a credential whose `mcp_server_url` refers to the same server as the `url` declared in `mcp_servers`. Both URLs are normalized before matching (scheme and host lowercased, default ports and trailing slashes stripped), so differences in host casing, a default port, or a trailing slash don't prevent a match; a different path, subdomain, or non-default port does. If none matches, the connection is attempted unauthenticated. See [Add a credential](https://platform.claude.com/docs/en/managed-agents/vaults#add-a-credential) for the `static_bearer` and `mcp_oauth` credential types.382383### Handle connection and authentication failures384385Session 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`](https://platform.claude.com/docs/en/managed-agents/events-and-streaming) event is emitted with the `mcp_server_name` of the affected server and a `retry_status`:386387| Error type | Meaning |388| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |389| `mcp_connection_failed_error` | The MCP server could not be reached (network error, timeout, or non-authentication HTTP failure). |390| `mcp_authentication_failed_error` | Authentication with the MCP server failed: the server rejected the credential from the attached vault, required authentication when no matching credential was configured, or an OAuth token refresh failed. |391392You 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.393394## Next steps395396<CardGroup cols={2}>397 <Card title="Permission policies" icon="check" href="https://platform.claude.com/docs/en/managed-agents/permission-policies">398 Control when agent and MCP tools run.399 </Card>400401 <Card title="Session event stream" icon="lightning" href="https://platform.claude.com/docs/en/managed-agents/events-and-streaming">402 Send events, stream responses, and interrupt or redirect your session mid-execution.403 </Card>404405 <Card title="Supported MCP server types" icon="book" href="https://platform.claude.com/docs/en/managed-agents/reference#supported-mcp-server-types">406 Transport requirements for remote MCP servers.407 </Card>408</CardGroup>409