# MCP 连接器

---

Claude 的模型上下文协议（MCP）连接器功能使您可以直接从 Messages API 连接到远程 MCP 服务器，无需单独的 MCP 客户端。

<Note>
  **当前版本：** 此功能需要 beta 头：`"anthropic-beta": "mcp-client-2025-11-20"`

  之前的版本（`mcp-client-2025-04-04`）已弃用。请参阅[弃用版本：mcp-client-2025-04-04](#deprecated-version-mcp-client-2025-04-04)。
</Note>

<Note>
此功能**不**符合[零数据保留（ZDR）](/docs/en/build-with-claude/api-and-data-retention)的条件。数据根据该功能的标准保留策略进行保留。
</Note>

## 核心功能

- **直接 API 集成**：无需实现 MCP 客户端即可连接到 MCP 服务器
- **工具调用支持**：通过 Messages API 访问 MCP 工具
- **灵活的工具配置**：启用所有工具、允许特定工具或拒绝不需要的工具
- **单工具配置**：使用自定义设置配置各个工具
- **OAuth 认证**：支持 OAuth Bearer 令牌用于认证服务器
- **多服务器**：在单个请求中连接到多个 MCP 服务器

## 限制

- 在 [MCP 规范](https://modelcontextprotocol.io/introduction#explore-mcp)的功能集中，目前仅支持[工具调用](https://modelcontextprotocol.io/docs/concepts/tools)。
- 服务器必须通过 HTTP 公开暴露（支持 Streamable HTTP 和 SSE 传输）。本地 STDIO 服务器无法直接连接。
- MCP 连接器在 Claude API、[Claude Platform on AWS](/docs/en/build-with-claude/claude-platform-on-aws) 和 [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry) 上可用。目前在 Amazon Bedrock 或 Vertex AI 上不可用。

## 在 Messages API 中使用 MCP 连接器

MCP 连接器使用两个组件：

1. **MCP 服务器定义**（`mcp_servers` 数组）：定义服务器连接详情（URL、认证）
2. **MCP 工具集**（`tools` 数组）：配置启用哪些工具以及如何配置

### 基本示例

此示例使用默认配置启用 MCP 服务器上的所有工具：

<CodeGroup>

```bash cURL nocheck
curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": "What tools do you have available?"}],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
      }
    ],
    "tools": [
      {
        "type": "mcp_toolset",
        "mcp_server_name": "example-mcp"
      }
    ]
  }'
```

```bash CLI nocheck
ant beta:messages create --beta mcp-client-2025-11-20 <<'YAML'
model: claude-opus-4-7
max_tokens: 1000
messages:
  - role: user
    content: What tools do you have available?
mcp_servers:
  - type: url
    url: https://example-server.modelcontextprotocol.io/sse
    name: example-mcp
    authorization_token: YOUR_TOKEN
tools:
  - type: mcp_toolset
    mcp_server_name: example-mcp
YAML
```

```python Python nocheck hidelines={1..2}
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What tools do you have available?"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse",
            "name": "example-mcp",
            "authorization_token": "YOUR_TOKEN",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)
```

```typescript TypeScript nocheck hidelines={1..2}
import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

const response = await anthropic.beta.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1000,
  messages: [
    {
      role: "user",
      content: "What tools do you have available?"
    }
  ],
  mcp_servers: [
    {
      type: "url",
      url: "https://example-server.modelcontextprotocol.io/sse",
      name: "example-mcp",
      authorization_token: "YOUR_TOKEN"
    }
  ],
  tools: [
    {
      type: "mcp_toolset",
      mcp_server_name: "example-mcp"
    }
  ],
  betas: ["mcp-client-2025-11-20"]
});

console.log(response);
```

```csharp C# nocheck hidelines={1..6}
using Anthropic;
using Anthropic.Models.Beta.Messages;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_7,
    MaxTokens = 1000,
    Messages = new List<BetaMessageParam>
    {
        new() { Role = Role.User, Content = "What tools do you have available?" }
    },
    McpServers = new List<BetaRequestMcpServerUrlDefinition>
    {
        new()
        {
            Url = "https://example-server.modelcontextprotocol.io/sse",
            Name = "example-mcp",
            AuthorizationToken = "YOUR_TOKEN"
        }
    },
    Tools = new List<BetaToolUnion>
    {
        new BetaMcpToolset("example-mcp")
    },
    Betas = new List<string> { "mcp-client-2025-11-20" }
};

var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
```

```go Go nocheck hidelines={1..11,-1}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
		Model:     anthropic.ModelClaudeOpus4_7,
		MaxTokens: 1000,
		Messages: []anthropic.BetaMessageParam{
			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
		},
		MCPServers: []anthropic.BetaRequestMCPServerURLDefinitionParam{
			{
				URL:                "https://example-server.modelcontextprotocol.io/sse",
				Name:               "example-mcp",
				AuthorizationToken: anthropic.String("YOUR_TOKEN"),
			},
		},
		Tools: []anthropic.BetaToolUnionParam{
			{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
				MCPServerName: "example-mcp",
			}},
		},
		Betas: []anthropic.AnthropicBeta{
			anthropic.AnthropicBetaMCPClient2025_11_20,
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}
```

```java Java nocheck hidelines={1..2,4,6..7}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.messages.BetaMcpToolset;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_7)
        .maxTokens(1000L)
        .addUserMessage("What tools do you have available?")
        .addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
            .url("https://example-server.modelcontextprotocol.io/sse")
            .name("example-mcp")
            .authorizationToken("YOUR_TOKEN")
            .build())
        .addTool(BetaMcpToolset.builder()
            .mcpServerName("example-mcp")
            .build())
        .addBeta("mcp-client-2025-11-20")
        .build();

    BetaMessage response = client.beta().messages().create(params);
    IO.println(response);
}
```

```php PHP nocheck hidelines={1..4}
<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

$message = $client->beta->messages->create(
    maxTokens: 1000,
    messages: [
        ['role' => 'user', 'content' => 'What tools do you have available?']
    ],
    model: 'claude-opus-4-7',
    mcpServers: [
        [
            'type' => 'url',
            'url' => 'https://example-server.modelcontextprotocol.io/sse',
            'name' => 'example-mcp',
            'authorization_token' => 'YOUR_TOKEN',
        ],
    ],
    tools: [
        [
            'type' => 'mcp_toolset',
            'mcp_server_name' => 'example-mcp',
        ],
    ],
    betas: ['mcp-client-2025-11-20'],
);

echo $message;
```

```ruby Ruby nocheck hidelines={1..2}
require "anthropic"

client = Anthropic::Client.new

response = client.beta.messages.create(
  model: "claude-opus-4-7",
  max_tokens: 1000,
  messages: [
    { role: "user", content: "What tools do you have available?" }
  ],
  mcp_servers: [
    {
      type: "url",
      url: "https://example-server.modelcontextprotocol.io/sse",
      name: "example-mcp",
      authorization_token: "YOUR_TOKEN"
    }
  ],
  tools: [
    {
      type: "mcp_toolset",
      mcp_server_name: "example-mcp"
    }
  ],
  betas: ["mcp-client-2025-11-20"]
)

puts response
```
</CodeGroup>

## MCP 服务器配置

`mcp_servers` 数组中的每个 MCP 服务器定义连接详情：

```json
{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}
```

### 字段说明

| 属性 | 类型 | 必填 | 说明 |
|----------|------|----------|-------------|
| `type` | string | 是 | 目前仅支持 "url"。 |
| `url` | string | 是 | MCP 服务器的 URL。必须以 https:// 开头。 |
| `name` | string | 是 | 此 MCP 服务器的唯一标识符。必须被 `tools` 数组中的一个且仅一个 MCPToolset 引用。 |
| `authorization_token` | string | 否 | MCP 服务器需要时的 OAuth 授权令牌。参见 [MCP 规范](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)。 |

## MCP 工具集配置

MCPToolset 位于 `tools` 数组中，配置 MCP 服务器上启用哪些工具以及如何配置。

### 基本结构

```json
{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}
```

### 字段说明

| 属性 | 类型 | 必填 | 说明 |
|----------|------|----------|-------------|
| `type` | string | 是 | 必须为 "mcp_toolset"。 |
| `mcp_server_name` | string | 是 | 必须与 `mcp_servers` 数组中定义的服务器名称匹配。 |
| `default_config` | object | 否 | 应用于此工具集中所有工具的默认配置。`configs` 中的个别工具配置会覆盖这些默认值。 |
| `configs` | object | 否 | 每个工具的配置覆盖。键为工具名称，值为配置对象。 |
| `cache_control` | object | 否 | 此工具集的[提示缓存](/docs/en/build-with-claude/prompt-caching)缓存断点配置。 |

### 工具配置选项

每个工具（在 `default_config` 或 `configs` 中配置的）支持以下字段：

| 属性 | 类型 | 默认值 | 说明 |
|----------|------|---------|-------------|
| `enabled` | boolean | `true` | 是否启用此工具。 |
| `defer_loading` | boolean | `false` | 如果为 true，工具描述最初不会发送给模型。与[工具搜索工具](/docs/en/agents-and-tools/tool-use/tool-search-tool)配合使用。 |

有关 Anthropic 提供的工具的完整目录以及 `defer_loading` 等可选属性，请参阅[工具参考](/docs/en/agents-and-tools/tool-use/tool-reference)。有关在大型工具集中搜索，请参阅[工具搜索工具](/docs/en/agents-and-tools/tool-use/tool-search-tool)。

### 配置合并

配置值按以下优先级合并（从高到低）：

1. `configs` 中的工具特定设置
2. 集级别的 `default_config`
3. 系统默认值

示例：

```json
{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": false
    }
  }
}
```

结果：
- `search_events`：`enabled: false`（来自 configs），`defer_loading: true`（来自 default_config）
- 所有其他工具：`enabled: true`（系统默认值），`defer_loading: true`（来自 default_config）

## 常见配置模式

### 使用默认配置启用所有工具

最简单的模式 - 启用服务器上的所有工具：

```json
{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}
```

### 允许列表：仅启用特定工具

将 `enabled: false` 设为默认值，然后显式启用特定工具：

```json
{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false
  },
  "configs": {
    "search_events": {
      "enabled": true
    },
    "create_event": {
      "enabled": true
    }
  }
}
```

### 拒绝列表：禁用特定工具

默认启用所有工具，然后显式禁用不需要的工具：

```json
{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": {
      "enabled": false
    },
    "share_calendar_publicly": {
      "enabled": false
    }
  }
}
```

### 混合：带每工具配置的允许列表

将允许列表与每个工具的自定义配置结合：

```json
{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false,
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": true,
      "defer_loading": false
    },
    "list_events": {
      "enabled": true
    }
  }
}
```

在此示例中：
- `search_events` 已启用，`defer_loading: false`
- `list_events` 已启用，`defer_loading: true`（从 default_config 继承）
- 所有其他工具已禁用

## 验证规则

API 强制执行以下验证规则：

- **服务器必须存在**：MCPToolset 中的 `mcp_server_name` 必须与 `mcp_servers` 数组中定义的服务器匹配
- **服务器必须被使用**：`mcp_servers` 中定义的每个 MCP 服务器必须被一个且仅一个 MCPToolset 引用
- **每个服务器一个工具集**：每个 MCP 服务器只能被一个 MCPToolset 引用
- **未知工具名称**：如果 `configs` 中的工具名称在 MCP 服务器上不存在，会记录后端警告但不返回错误（MCP 服务器可能有动态工具可用性）

## 响应内容类型

当 Claude 使用 MCP 工具时，响应包含两种新的内容块类型：

### MCP 工具使用块

```json
{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}
```

### MCP 工具结果块

```json
{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}
```

## 多 MCP 服务器

您可以通过在 `mcp_servers` 中包含多个服务器定义，并在 `tools` 数组中为每个服务器提供对应的 MCPToolset 来连接到多个 MCP 服务器：

```json
{
  "model": "claude-opus-4-7",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example1.com/sse",
      "name": "mcp-server-1",
      "authorization_token": "TOKEN1"
    },
    {
      "type": "url",
      "url": "https://mcp.example2.com/sse",
      "name": "mcp-server-2",
      "authorization_token": "TOKEN2"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-1"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-2",
      "default_config": {
        "defer_loading": true
      }
    }
  ]
}
```

## 认证

对于需要 OAuth 认证的 MCP 服务器，您需要获取访问令牌。MCP 连接器 beta 支持在 MCP 服务器定义中传递 `authorization_token` 参数。API 消费者需要在进行 API 调用之前处理 OAuth 流程并获取访问令牌，并在需要时刷新令牌。

### 获取测试用访问令牌

MCP 检查器可以指导您完成获取测试用访问令牌的过程。

1. 使用以下命令运行检查器。您需要在机器上安装 Node.js。

   ```bash
   npx @modelcontextprotocol/inspector
   ```

2. 在左侧边栏中，对于"传输类型"，选择"SSE"或"Streamable HTTP"。
3. 输入 MCP 服务器的 URL。
4. 在右侧区域，点击"需要配置认证？"后的"打开认证设置"按钮。
5. 点击"快速 OAuth 流程"并在 OAuth 屏幕上授权。
6. 按照检查器的"OAuth 流程进度"部分中的步骤操作，点击"继续"直到到达"认证完成"。
7. 复制 `access_token` 值。
8. 将其粘贴到 MCP 服务器配置的 `authorization_token` 字段中。

### 使用访问令牌

使用上述任一 OAuth 流程获取访问令牌后，您可以在 MCP 服务器配置中使用它：

```json
{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}
```

有关 OAuth 流程的详细说明，请参阅 MCP 规范中的[授权部分](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)。

## 客户端 MCP 辅助工具（TypeScript）

如果您管理自己的 MCP 客户端连接（例如使用本地 stdio 服务器、MCP 提示或 MCP 资源），TypeScript SDK 提供辅助函数，可在 MCP 类型和 Claude API 类型之间进行转换。这消除了在使用 [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) 和 Anthropic SDK 时的手动转换代码。

<Note>
  这些辅助工具目前仅在 TypeScript SDK 中可用。
</Note>
<Note>
  当您有可通过 URL 访问的远程服务器且只需要工具支持时，使用 [`mcp_servers` API 参数](#在-messages-api-中使用-mcp-连接器)。当您需要本地服务器、提示、资源或对连接有更多控制时，使用客户端辅助工具。
</Note>

### 安装

安装 Anthropic SDK 和 MCP SDK：

```bash
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk
```

### 可用辅助工具

从 beta 命名空间导入辅助工具：

```typescript nocheck
import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";
```

| 辅助工具 | 说明 |
|--------|-------------|
| `mcpTools(tools, mcpClient)` | 将 MCP 工具转换为 Claude API 工具，与 `client.beta.messages.toolRunner()` 配合使用 |
| `mcpMessages(messages)` | 将 MCP 提示消息转换为 Claude API 消息格式 |
| `mcpResourceToContent(resource)` | 将 MCP 资源转换为 Claude API 内容块 |
| `mcpResourceToFile(resource)` | 将 MCP 资源转换为用于上传的文件对象 |

### 使用 MCP 工具

转换 MCP 工具以与 SDK 的[工具运行器](/docs/en/agents-and-tools/tool-use/tool-runner)配合使用，后者自动处理工具执行：

```typescript nocheck hidelines={1}
import Anthropic from "@anthropic-ai/sdk";
import { mcpTools } from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// 连接到 MCP 服务器
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// 列出工具并为 Claude API 转换
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

console.log(finalMessage);
```

### 使用 MCP 提示

将 MCP 提示消息转换为 Claude API 消息格式：

```typescript nocheck
import { mcpMessages } from "@anthropic-ai/sdk/helpers/beta/mcp";

const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

console.log(response);
```

### 使用 MCP 资源

将 MCP 资源转换为内容块以包含在消息中，或转换为文件对象以进行上传：

```typescript nocheck
import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";

// 作为消息中的内容块
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// 作为文件上传
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });
```

### 错误处理

如果 MCP 值不被 Claude API 支持，转换函数会抛出 `UnsupportedMCPValueError`。这可能发生在不支持的内容类型、MIME 类型或非 HTTP 资源链接的情况下。

## 数据保留

MCP 连接器不受 ZDR 安排覆盖。与 MCP 服务器交换的数据，包括工具定义和执行结果，根据 Anthropic 的标准数据保留策略进行保留。

有关所有功能的 ZDR 资格，请参阅 [API 和数据保留](/docs/en/manage-claude/api-and-data-retention)。

## 迁移指南

如果您正在使用已弃用的 `mcp-client-2025-04-04` beta 头，请按照本指南迁移到新版本。

### 主要变更

1. **新 beta 头**：从 `mcp-client-2025-04-04` 更改为 `mcp-client-2025-11-20`
2. **工具配置移动**：工具配置现在位于 `tools` 数组中作为 MCPToolset 对象，而非在 MCP 服务器定义中
3. **更灵活的配置**：新模式支持允许列表、拒绝列表和每工具配置

### 迁移步骤

**之前（已弃用）：**

```json
{
  "model": "claude-opus-4-7",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}
```

**之后（当前）：**

```json
{
  "model": "claude-opus-4-7",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}
```

### 常见迁移模式

| 旧模式 | 新模式 |
|-------------|-------------|
| 无 `tool_configuration`（所有工具启用） | 无 `default_config` 或 `configs` 的 MCPToolset |
| `tool_configuration.enabled: false` | 带 `default_config.enabled: false` 的 MCPToolset |
| `tool_configuration.allowed_tools: [...]` | 带 `default_config.enabled: false` 且在 `configs` 中启用特定工具的 MCPToolset |

## 弃用版本：mcp-client-2025-04-04

<Note type="warning">
  此版本已弃用。请使用前面的[迁移指南](#迁移指南)迁移到 `mcp-client-2025-11-20`。
</Note>

之前的 MCP 连接器版本将工具配置直接包含在 MCP 服务器定义中：

```json
{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}
```

### 弃用字段说明

| 属性 | 类型 | 说明 |
|----------|------|-------------|
| `tool_configuration` | object | **已弃用**：改用 `tools` 数组中的 MCPToolset |
| `tool_configuration.enabled` | boolean | **已弃用**：改用 MCPToolset 中的 `default_config.enabled` |
| `tool_configuration.allowed_tools` | array | **已弃用**：改用 MCPToolset 中 `configs` 的允许列表模式 |