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:
| Component | Where | What it declares |
|---|---|---|
mcp_servers | top-level request param (array) | Connection details: type, url, name, optional authorization_token |
mcp_toolset | an entry in the tools array | Which tools from a named server are enabled (via mcp_server_name) |
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.DIAGRAM One request, server-side connection, tool blocks back
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_loadingper 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)
mcpTools, mcpMessages, …) when
you need local servers, prompts, or resources.EXAM TRAPS
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.url must be
https://.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.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.