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_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "name": "GitHub Assistant",
  "model": "claude-sonnet-4-6",
  "mcp_servers": [
    {
      "type": "url",
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  ],
  "tools": [
    {"type": "agent_toolset_20260401"},
    {"type": "mcp_toolset", "mcp_server_name": "github"}
  ]
}
EOF
)
agent_id=$(jq -r '.id' <<<"$agent_response")

Provide auth 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_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "vault_ids": ["$vault_id"]
}
EOF
)
session_id=$(jq -r '.id' <<<"$session_response")

If the authorization credentials supplied in the vault are invalid, session creation will succeed and interaction is still possible. A session.error event is emitted describing the MCP auth failure. You can decide whether to block further interactions on this error, trigger a credential update, or allow the session to continue without the MCP. Authentication retries will happen on the following 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. The server must support the MCP protocol's streamable HTTP transport.

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