D2 · Tool Design & MCP › Cluster 7 · Building & Consuming MCP Servers

7.2 · The Claude API MCP Connector

Call remote MCP from the Messages API

CONCEPT Claude connects to a remote MCP server for you — no client to build

The MCP connector lets the Messages API reach a remote MCP server directly, without you writing or hosting an MCP client. You name the server(s) in the request; Anthropic makes the connection server-side, exposes the tools to Claude, executes the calls, and returns the results as content blocks. It requires two request components that work together:

ComponentWhereWhat it declares
mcp_serverstop-level request param (array)Connection details: type, url, name, optional authorization_token
mcp_toolsetan entry in the tools arrayWhich tools from a named server are enabled (via mcp_server_name)
⚠️ Every server in mcp_servers must be referenced by exactly one mcp_toolset in tools. Supplying mcp_servers alone is a validation error — the toolset is what actually surfaces the tools to the model.

CONCEPT The required beta header, the fields, and the limits

Beta header (verified): anthropic-beta: mcp-client-2025-11-20 — pass it as betas=["mcp-client-2025-11-20"] and call the client.beta.messages.create(...) path. (The older mcp-client-2025-04-04, which put tool config inside the server definition, is deprecated.)

🔑 mcp_servers[] fields — type (only "url" is supported), url (must start with https://), name (unique; referenced by one toolset), and optional authorization_token (OAuth Bearer token — see 7.3). Do not invent other fields.
Limits to know: it supports remote HTTP servers only — both Streamable HTTP and SSE transports; local STDIO servers cannot be connected. Of the MCP feature set, only tool calls are supported (not resources/prompts). It is not ZDR-eligible. Available on the Claude API, Claude Platform on AWS, and Microsoft Foundry — not on Amazon Bedrock or Google Vertex.

DIAGRAM One request, server-side connection, tool blocks back

sequenceDiagram participant You as Your app participant API as Messages API participant MCP as Remote MCP server (HTTPS) You->>API: mcp_servers:[{type:url,url,name,authorization_token}]
tools:[{type:mcp_toolset,mcp_server_name}]
beta: mcp-client-2025-11-20 API->>MCP: connect + list tools (server-side) API->>MCP: call tool (Claude decided) MCP-->>API: result API-->>You: content: mcp_tool_use + mcp_tool_result blocks

CODE A connector request and the response blocks

Enable all tools from one authenticated server. The response carries two new block types.

# Python — client.beta.messages.create, beta header required
response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What tools do you have available?"}],
    mcp_servers=[
        {
            "type": "url",                                 # only "url" is valid
            "url": "https://mcp.example.com/sse",        # must be https
            "name": "example-mcp",                       # unique; referenced below
            "authorization_token": "YOUR_OAUTH_TOKEN",  # optional (7.3)
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    betas=["mcp-client-2025-11-20"],
)
// Response content blocks — two new types
{ "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35...",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1" } }

{ "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35...",
  "is_error": false,
  "content": [{ "type": "text", "text": "Hello" }] }

Allowlist / denylist individual tools via the toolset's default_config (defaults for all tools) and configs (per-tool overrides), each supporting enabled and defer_loading:

# Allowlist: disable all by default, enable two
{ "type": "mcp_toolset", "mcp_server_name": "example-mcp",
  "default_config": { "enabled": false },
  "configs": { "search_events": { "enabled": true },
              "list_events":   { "enabled": true } } }

TRADE-OFFS The connector vs. running your own MCP client

✅ MCP connector (mcp_servers)

  • No client to build or host — Anthropic makes the connection
  • One API call; multiple servers per request
  • Allowlist/denylist & defer_loading per tool

⚠️ SDK client-side MCP helpers

  • Needed for local stdio servers, or MCP prompts/resources
  • You manage the connection, but gain full protocol access
  • More control, more code (you host the client)
Use the connector when you have a remote, URL-addressable server and only need tools. Reach for the SDK's client-side helpers (mcpTools, mcpMessages, …) when you need local servers, prompts, or resources.

EXAM TRAPS

Trap: Sending only mcp_servers and expecting tools to appear. → You must also add an mcp_toolset entry in tools referencing the server by mcp_server_name. Every declared server needs exactly one toolset.
Trap: Pointing the connector at a local stdio server. → The connector reaches remote HTTP servers only (Streamable HTTP or SSE). STDIO is not supported; the url must be https://.
Trap: Guessing connector fields (e.g. a headers or command key). → The only mcp_servers fields are type, url, name, and optional authorization_token. Tool config lives in the toolset, not the server definition.
Trap: Assuming resources/prompts flow through the connector. → Only tool calls are supported. Results arrive as mcp_tool_use / mcp_tool_result blocks, not tool_use / tool_result.

PRACTICE

Q1 · What beta header and which two request components does the connector require?

Header anthropic-beta: mcp-client-2025-11-20, plus (1) an mcp_servers array with {type:"url", url, name, authorization_token?} and (2) a matching {type:"mcp_toolset", mcp_server_name} entry in the tools array.

Q2 · Which transports and MCP features does the connector support?

Remote HTTP servers over Streamable HTTP or SSE — no local STDIO. Of the MCP feature set, only tool calls are supported (not resources or prompts). It is not ZDR-eligible and is unavailable on Bedrock/Vertex.

Q3 · How do the response blocks differ from ordinary tool use?

The connector returns mcp_tool_use (which also carries a server_name) and mcp_tool_result blocks — Anthropic executed the call server-side, so unlike a normal tool_use you don't send a tool_result back yourself.