mcp-connector changedagents-and-tools/mcp-connector
Nearest release: v2.1.312, published under an hour before 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+21added
Lines−21removed
From line
12
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits38to this page, all time
## Pin an MCP server’s tool list (beta) ## Pin an MCP server's tool list (beta)
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 allows 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 29
2929
3030## When Claude uses MCP tools
3131
32Once an MCP server is connected, Claude calls its tools when the user's request maps to a tool's described capability, either explicitly ("search Jira for open bugs") or implicitly ("what's blocking the release?" with a Jira server attached).
32Once an MCP server is connected, Claude calls its tools when the user’s request maps to a tool’s described capability, either explicitly (“search Jira for open bugs”) or implicitly (“what’s blocking the release?” with a Jira server attached).
3333
34Claude does **not** call an MCP tool for general knowledge questions about a connected service. Asking "how do Notion databases work?" with a Notion server attached is answered directly; asking "what's in my Projects database?" triggers the tool.
34Claude does **not** call an MCP tool for general knowledge questions about a connected service. Asking “how do Notion databases work?” with a Notion server attached is answered directly; asking “what’s in my Projects database?” triggers the tool.
3535
3636You can steer how readily Claude calls MCP tools through your system prompt. See [When Claude uses tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview#when-claude-uses-tools) for general guidance and example phrasings.
3737
from line 318
318318
319319| Property | Type | Required | Description |
320320| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
321| `type` | string | Yes | Currently only "url" is supported. |
321| `type` | string | Yes | Currently only `url` is supported. |
322322| `url` | string | Yes | The URL of the MCP server. Must start with `https://`. |
323323| `name` | string | Yes | A unique identifier for this MCP server. Must be referenced by exactly one MCPToolset in the `tools` array. |
324324| `authorization_token` | string | No | OAuth authorization token if required by the MCP server. See [Authentication](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#authentication) for how to obtain one, or the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) for protocol details. |
from line 350
350350
351351| Property | Type | Required | Description |
352352| ----------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
353| `type` | string | Yes | Must be "mcp\_toolset". |
353| `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. |
356356| `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
359With 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).
359With 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).
360360
361361### Tool configuration options
362362
from line 490
490490* **Server must exist:** The `mcp_server_name` in an MCPToolset must match a server defined in the `mcp_servers` array.
491491* **Server must be used:** Every MCP server defined in `mcp_servers` must be referenced by exactly one MCPToolset.
492492* **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).
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 524
524524}
525525```
526526
527## Pin an MCP server's tool list (beta)
527## 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 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.
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 550
550550
551551If your code reads `content[0]`, skip these blocks. Send the assistant message back unchanged, `mcp_tool_listing` blocks included, and keep sending `mcp-client-2026-09-15` on every request that carries one. Later requests then use the recorded list for that server instead of asking it again.
552552
553To pin a list yourself, copy a block's `tools` into the `tools` field of that server's MCPToolset. The API then doesn't ask the server for its tools, and the toolset's tools are exactly those entries, with `default_config` and `configs` applied:
553To pin a list yourself, copy a block’s `tools` into the `tools` field of that server’s MCPToolset. The API then doesn’t ask the server for its tools, and the toolset’s tools are exactly those entries, with `default_config` and `configs` applied:
554554
555555```json
556556{
from line 570
570570}
571571```
572572
573Each entry in `tools` holds the tool's `name` as the server lists it (without the server name), its `description`, and its `input_schema`.
573Each entry in `tools` holds the tool’s `name` as the server lists it (without the server name), its `description`, and its `input_schema`.
574574
575The following example sends one request with an unpinned toolset, copies the returned list into the toolset's `tools` field, and sends the request again. The second response has no `mcp_tool_listing` block, because the API doesn't ask the server:
575The following example sends one request with an unpinned toolset, copies the returned list into the toolset’s `tools` field, and sends the request again. The second response has no `mcp_tool_listing` block, because the API doesn’t ask the server:
576576
577577<CodeGroup>
578578 ```bash cURL
from line 1181
11811181
11821182## Authentication
11831183
1184For MCP servers that require OAuth authentication, you'll need to obtain an access token. The MCP connector beta supports passing an `authorization_token` parameter in the MCP server definition. API consumers are expected to handle the OAuth flow and obtain the access token prior to making the API call, and to refresh the token as needed.
1184For MCP servers that require OAuth authentication, you’ll need to obtain an access token. The MCP connector beta supports passing an `authorization_token` parameter in the MCP server definition. API consumers are expected to handle the OAuth flow and obtain the access token prior to making the API call, and to refresh the token as needed.
11851185
11861186### Obtaining an access token for testing
11871187
from line 1209
12091209
12101210### Using the access token
12111211
1212Once you've obtained an access token, 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 1374
13741374
13751375### Use MCP tools
13761376
1377Convert MCP tools for use with the SDK's [tool runner](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner), which handles tool execution automatically:
1377Convert MCP tools for use with the SDK’s [tool runner](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner), which handles tool execution automatically:
13781378
13791379<CodeGroup exclude="shell">
13801380 ```python Python
from line 1978
19781978
19791979### Error handling
19801980
1981The 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).
1981The 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).
19821982
19831983## Batch requests
19841984
from line 1986
19861986
19871987## Data retention
19881988
1989The MCP connector is not covered by ZDR arrangements. Data exchanged with MCP servers, including tool definitions and execution results, is retained according to Anthropic's standard data retention policy.
1989The MCP connector is not covered by ZDR arrangements. Data exchanged with MCP servers, including tool definitions and execution results, is retained according to Anthropic’s standard data retention policy.
19901990
19911991For ZDR eligibility across all features, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
19921992
19931993## Migration guide
19941994
1995If you're using the deprecated `mcp-client-2025-04-04` beta header, follow this guide to migrate to the new version.
1995If you’re using the deprecated `mcp-client-2025-04-04` beta header, follow this guide to migrate to the new version.
19961996
19971997### Key changes
19981998
No line in this hunk matches that.