mcp-connector changedagents-and-tools/mcp-connector
Nearest release: v2.1.307, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+18added
Lines−18removed
From line
12
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits32to this page, all time
The whole hunk
from line 12, old and new numbered
/
from line 12
1212 Microsoft Foundry: beta
1313---
1414
15Claude's Model Context Protocol (MCP) connector feature enables you to connect to remote MCP servers directly from the Messages API without a separate MCP client.
15Claude's Model Context Protocol (MCP) connector feature allows you to connect to remote MCP servers directly from the Messages API without a separate MCP client.
1616
1717<Note>
1818 The previous version of this feature (`mcp-client-2025-04-04`) is deprecated. See [Deprecated version: mcp-client-2025-04-04](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#deprecated-version-mcp-client-2025-04-04).
from line 353
353353| `type` | string | Yes | Must be "mcp\_toolset". |
354354| `mcp_server_name` | string | Yes | Must match a server name defined in the `mcp_servers` array. |
355355| `default_config` | object | No | Default configuration applied to all tools in this set. Individual tool configs in `configs` override these defaults. |
356| `configs` | object | No | Per-tool configuration overrides. Keys are tool names, values are configuration objects. |
356| `configs` | object | No | Per-tool configuration overrides. Keys are tool names; values are configuration objects. |
357357| `cache_control` | object | No | [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) cache breakpoint configuration for this toolset. |
358358
359359With the `mcp-client-2026-09-15` beta header, an MCPToolset also accepts `tools`, a pinned copy of the server's tool list. See [Pin an MCP server's tool list](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#pin-mcp-tool-list).
from line 396
396396
397397Results in:
398398
399* `search_events`: `enabled: false` (from configs), `defer_loading: true` (from default\_config)
400* All other tools: `enabled: true` (system default), `defer_loading: true` (from default\_config)
399* `search_events`: `enabled: false` (from `configs`), `defer_loading: true` (from `default_config`)
400* All other tools: `enabled: true` (system default), `defer_loading: true` (from `default_config`)
401401
402402## Common configuration patterns
403403
from line 479
479479
480480In this example:
481481
482* `search_events` is enabled with `defer_loading: false`
483* `list_events` is enabled with `defer_loading: true` (inherited from default\_config)
484* All other tools are disabled
482* `search_events` is enabled with `defer_loading: false`.
483* `list_events` is enabled with `defer_loading: true` (inherited from `default_config`).
484* All other tools are disabled.
485485
486486## Validation rules
487487
488488The API enforces these validation rules:
489489
490* **Server must exist:** The `mcp_server_name` in an MCPToolset must match a server defined in the `mcp_servers` array
491* **Server must be used:** Every MCP server defined in `mcp_servers` must be referenced by exactly one MCPToolset
492* **Unique toolset per server:** Each MCP server can only be referenced by one MCPToolset
493* **Unknown tool names:** If a tool name in `configs` doesn't exist on the MCP server, a backend warning is logged but no error is returned (MCP servers may have dynamic tool availability)
490* **Server must exist:** The `mcp_server_name` in an MCPToolset must match a server defined in the `mcp_servers` array.
491* **Server must be used:** Every MCP server defined in `mcp_servers` must be referenced by exactly one MCPToolset.
492* **Unique toolset for each server:** Each MCP server can only be referenced by one MCPToolset.
493* **Unknown tool names:** If a tool name in `configs` doesn't exist on the MCP server, a backend warning is logged but no error is returned (MCP servers might have dynamic tool availability).
494494
495495## Response content types
496496
from line 526
526526
527527## Pin an MCP server's tool list (beta)
528528
529An MCP server can change its tools at any time. The `mcp-client-2026-09-15` beta header records the tool list each server returns and lets you pin it, so a server that changes its tools doesn't change what Claude sees partway through a conversation. It includes everything `mcp-client-2025-11-20` does, so send it in place of that header. It's available on the Claude API.
529An MCP server can change its tools at any time. The `mcp-client-2026-09-15` beta header records the tool list each server returns and lets you pin it, so a server that changes its tools doesn't change what Claude receives partway through a conversation. It includes everything `mcp-client-2025-11-20` does, so send it in place of that header. It's available on the Claude API.
530530
531531When the API asks an MCP server for its tools while producing a response, the response starts with an `mcp_tool_listing` block for that server, one block for each server it asked:
532532
from line 1177
11771177}
11781178```
11791179
1180With many tools available, Claude selects based on tool names and descriptions. Clear, specific tool descriptions improve selection accuracy. For large tool sets (dozens of tools across several servers), consider enabling [`defer_loading`](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#tool-configuration-options) with the [Tool search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) so only relevant tools are surfaced per query.
1180With many tools available, Claude selects based on tool names and descriptions. Clear, specific tool descriptions improve selection accuracy. For large tool sets (dozens of tools across several servers), consider enabling [`defer_loading`](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#tool-configuration-options) with the [Tool search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) so only relevant tools are surfaced for each query.
11811181
11821182## Authentication
11831183
from line 1209
12091209
12101210### Using the access token
12111211
1212Once you've obtained an access token using either of the preceding OAuth flows, you can use it in your MCP server configuration:
1212Once you've obtained an access token, you can use it in your MCP server configuration:
12131213
12141214```json
12151215{
from line 1976
19761976
19771977### Error handling
19781978
1979The conversion functions fail with `UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`) if an MCP value isn't supported by the Claude API (thrown, or in Go returned as an error). This can happen with unsupported content types, MIME types, or resource links (resolve resource links with your MCP client before converting).
1979The conversion functions fail with `UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`) if an MCP value isn't supported by the Claude API (thrown, or in Go returned as an error). This can occur with unsupported content types, MIME types, or resource links (resolve resource links with your MCP client before converting).
19801980
19811981## Batch requests
19821982
from line 1994
19941994
19951995### Key changes
19961996
19971. **New beta header:** Change from `mcp-client-2025-04-04` to `mcp-client-2025-11-20`
19982. **Tool configuration moved:** Tool configuration now lives in the `tools` array as MCPToolset objects, not in the MCP server definition
19993. **More flexible configuration:** New pattern supports allowlisting, denylisting, and per-tool configuration
19971. **New beta header:** Change from `mcp-client-2025-04-04` to `mcp-client-2025-11-20`.
19982. **Tool configuration moved:** Tool configuration now lives in the `tools` array as MCPToolset objects, not in the MCP server definition.
19993. **More flexible configuration:** New pattern supports allowlisting, denylisting, and per-tool configuration.
20002000
20012001### Migration steps
20022002
No line in this hunk matches that.