60 60
61## 安装 MCP 服务器61## 安装 MCP 服务器
62 62
63MCP 服务器可以根据您的需求以多种方式进行配置：63MCP 服务器可以根据您的需求通过多种方式进行配置：
64 64
65### 选项 1：添加远程 HTTP 服务器65### 选项 1：添加远程 HTTP 服务器
66 66
67HTTP 服务器是连接到远程 MCP 服务器的推荐选项。这是云服务最广泛支持的传输方式。67HTTP 服务器是连接远程 MCP 服务器的推荐选项。这是基于云的服务中支持最广泛的传输方式。
68 68
69```bash theme={null}69```bash theme={null}
70# 基本语法70# Basic syntax
71claude mcp add --transport http <name> <url>71claude mcp add --transport http <name> <url>
72 72
73# 真实示例：连接到 Notion73# Real example: Connect to Notion
74claude mcp add --transport http notion https://mcp.notion.com/mcp74claude mcp add --transport http notion https://mcp.notion.com/mcp
75 75
76# 带有 Bearer 令牌的示例76# Example with Bearer token
77claude mcp add --transport http secure-api https://api.example.com/mcp \77claude mcp add --transport http secure-api https://api.example.com/mcp \
78 --header "Authorization: Bearer your-token"78 --header "Authorization: Bearer your-token"
79```79```
80 80
81通过 `.mcp.json`、`~/.claude.json` 或 `claude mcp add-json` 中的 JSON 配置 MCP 服务器时，`type` 字段接受 `streamable-http` 作为 `http` 的别名。MCP 规范对此传输使用名称 `streamable-http`，因此从服务器文档复制的配置无需修改即可工作。81在 `.mcp.json`、`~/.claude.json` 或 `claude mcp add-json` 中通过 JSON 配置 MCP 服务器时，`type` 字段接受 `streamable-http` 作为 `http` 的别名。MCP 规范将此传输方式命名为 `streamable-http`，因此从服务器文档中复制的配置无需修改即可使用。
82 82
83具有 `url` 但没有 `type` 的 JSON 条目是配置错误，因为 Claude Code 将没有 `type` 的条目读取为 stdio 服务器。Claude Code 跳过该服务器并报告 `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`。83包含 `url` 但没有 `type` 的 JSON 条目属于配置错误，因为 Claude Code 会将没有 `type` 的条目读取为 stdio 服务器。Claude Code 会跳过该服务器并报告 `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`。
84 84
85只有 SDK 主机应用程序（例如 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md) 应用程序或 [桌面应用](https://code.claude.com/docs/zh-CN/desktop.md)）可以注册进程内 `"type": "sdk"` 服务器。Claude Code 跳过 `.mcp.json`、`~/.claude.json` 或设置中的 `"type": "sdk"` 条目，并报告 `Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register`。85只有 SDK 宿主应用程序（例如 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md) 应用程序或[桌面应用](https://code.claude.com/docs/zh-CN/desktop.md)）才能注册进程内的 `"type": "sdk"` 服务器。Claude Code 会跳过 `.mcp.json`、`~/.claude.json` 或设置中的 `"type": "sdk"` 条目，并报告 `Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register`。
86 86
87> [!NOTE]87> [!NOTE]
88>88>
89> 在 `--output-format stream-json` 运行中，Claude Code 还会在 `system/init` 事件的 [`mcp_server_errors` 字段](https://code.claude.com/docs/zh-CN/headless#stream-responses)中报告被跳过的 `--mcp-config` 条目，以便脚本检测到该服务器从未加载。89> 在 `--output-format stream-json` 运行中，Claude Code 还会在 `system/init` 事件的 [`mcp_server_errors` 字段](https://code.claude.com/docs/zh-CN/headless#stream-responses)中报告被跳过的 `--mcp-config` 条目，以便脚本能够检测到该服务器从未加载。
90 90
91### 选项 2：添加远程 SSE 服务器91### 选项 2：添加远程 SSE 服务器
92 92
93> [!WARNING]93> [!WARNING]
94>94>
95> SSE（Server-Sent Events）传输已弃用。请在可用的地方使用 HTTP 服务器。95> SSE（Server-Sent Events）传输方式已弃用。请在可用时改用 HTTP 服务器。
96 96
97某些服务仍然仅公开 SSE 端点。使用与 [HTTP 服务器](#option-1-add-a-remote-http-server) 相同的 `claude mcp add --transport http <name> <url>` 命令添加这些。Claude Code 首先尝试 HTTP 传输，当服务器不接受时切换到 SSE。自动切换需要 Claude Code v2.1.265 或更高版本。97某些服务仍然只提供 SSE 端点。使用与 [HTTP 服务器](#option-1-add-a-remote-http-server)相同的 `claude mcp add --transport http <name> <url>` 命令添加这些服务。Claude Code 会先尝试 HTTP 传输方式，当服务器不接受时切换到 SSE。自动切换需要 Claude Code v2.1.265 或更高版本。
98 98
99在较早的版本上，或直接通过 SSE 连接，请改为传递 `--transport sse`：99在更早的版本上，或者要直接通过 SSE 连接，请改为传递 `--transport sse`：
100 100
101```bash theme={null}101```bash theme={null}
102# 基本语法102# Basic syntax
103claude mcp add --transport sse <name> <url>103claude mcp add --transport sse <name> <url>
104 104
105# 真实示例：连接到 Asana105# Real example: Connect to Asana
106claude mcp add --transport sse asana https://mcp.asana.com/sse106claude mcp add --transport sse asana https://mcp.asana.com/sse
107 107
108# 带有身份验证标头的示例108# Example with authentication header
109claude mcp add --transport sse private-api https://api.company.com/sse \109claude mcp add --transport sse private-api https://api.company.com/sse \
110 --header "X-API-Key: your-key-here"110 --header "X-API-Key: your-key-here"
111```111```
112 112
113### 选项 3：添加本地 stdio 服务器113### 选项 3：添加本地 stdio 服务器
114 114
115Stdio 服务器作为本地进程在您的机器上运行。它们非常适合需要直接系统访问或自定义脚本的工具。115Stdio 服务器以本地进程的形式在您的机器上运行。它们非常适合需要直接访问系统的工具或自定义脚本。
116 116
117Claude Code 在生成的服务器的环境中设置 `CLAUDE_PROJECT_DIR` 为项目根目录，以便您的服务器可以解析项目相对路径，而不依赖于工作目录。这与 hook 在其 `CLAUDE_PROJECT_DIR` 变量中接收的目录相同。从服务器进程内读取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。117Claude Code 会在所启动服务器的环境中将 `CLAUDE_PROJECT_DIR` 设置为项目根目录，这样您的服务器就可以解析相对于项目的路径，而无需依赖工作目录。这与 hook 在其 `CLAUDE_PROJECT_DIR` 变量中接收到的目录相同。请在服务器进程内部读取它，例如在 Node 中使用 `process.env.CLAUDE_PROJECT_DIR`，在 Python 中使用 `os.environ["CLAUDE_PROJECT_DIR"]`。
118 118
119`CLAUDE_PROJECT_DIR` 是稳定的项目根目录，在会话中添加或删除工作目录时不会更改。限制自己的文件系统访问到一组允许目录的服务器应该改为实现 MCP `roots/list` 请求。Claude Code 使用会话的启动目录加上您通过 `--add-dir`、`/add-dir` 或 `additionalDirectories` 设置授予的每个 [额外工作目录](https://code.claude.com/docs/zh-CN/permissions.md#working-directories) 来回答 `roots/list`。当该集合更改时，Claude Code 发送 `notifications/roots/list_changed`。119`CLAUDE_PROJECT_DIR` 是稳定的项目根目录，在会话中途添加或移除工作目录时不会改变。如果服务器要将自身的文件系统访问限制在一组允许的目录内，则应改为实现 MCP `roots/list` 请求。Claude Code 对 `roots/list` 的响应包含会话的启动目录，以及您通过 `--add-dir`、`/add-dir` 或 `additionalDirectories` 设置授予的每个[额外工作目录](https://code.claude.com/docs/zh-CN/permissions.md#working-directories)。当该集合发生变化时，Claude Code 会发送 `notifications/roots/list_changed`。
120 120
121此变量在服务器的环境中设置，而不是在 Claude Code 自己的环境中，因此通过项目作用域的 `.mcp.json` 条目或 `~/.claude.json` 中的本地或用户作用域服务器条目中的 `command` 或 `args` 中的 `${VAR}` 扩展来引用它需要默认值，例如 `${CLAUDE_PROJECT_DIR:-.}`。插件提供的 MCP 配置直接替换 `${CLAUDE_PROJECT_DIR}` 并且不需要默认值。121此变量设置在服务器的环境中，而不是 Claude Code 自身的环境中，因此在项目作用域 `.mcp.json` 条目或 `~/.claude.json` 中本地或用户作用域服务器条目的 `command` 或 `args` 中通过 `${VAR}` 展开引用它时，需要提供默认值，例如 `${CLAUDE_PROJECT_DIR:-.}`。插件提供的 MCP 配置会直接替换 `${CLAUDE_PROJECT_DIR}`，不需要默认值。
122 122
123```bash theme={null}123```bash theme={null}
124# 基本语法124# Basic syntax
125claude mcp add [options] <name> -- <command> [args...]125claude mcp add [options] <name> -- <command> [args...]
126 126
127# 真实示例：添加 Airtable 服务器127# Real example: Add Airtable server
128claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \128claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
129 -- npx -y airtable-mcp-server129 -- npx -y airtable-mcp-server
130```130```
131 131
132> [!NOTE]132> [!NOTE]
133>133>
134> 对于 stdio 服务器，`--`（双破折号）将 Claude 自己的选项（例如 `--transport`、`--env` 和 `--scope`）与运行服务器的命令和参数分开。`--` 之后的所有内容都原封不动地传递给服务器。134> 对于 stdio 服务器，`--`（双破折号）将 Claude 自身的选项（例如 `--transport`、`--env` 和 `--scope`）与运行服务器的命令和参数分隔开。`--` 之后的所有内容都会原样传递给服务器。
135>135>
136> 例如：136> 例如：
137>137>
138> * `claude mcp add --transport stdio myserver -- npx server` → 运行 `npx server`138> * `claude mcp add --transport stdio myserver -- npx server` → 运行 `npx server`
139> * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 使用环境中的 `KEY=value` 运行 `python server.py --port 8080`139> * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 在环境中带有 `KEY=value` 的情况下运行 `python server.py --port 8080`
140>140>
141> 没有 `--`，Claude Code 会尝试将服务器的标志（如上面的 `--port`）解析为自己的选项。141> 如果没有 `--`，Claude Code 会尝试将服务器的标志（例如上面的 `--port`）解析为其自身的选项。
142>142>
143> `--env` 接受多个 `KEY=value` 对。如果服务器名称直接跟在 `--env` 之后，CLI 会将该名称读取为另一对并拒绝它，因此在 `--env` 和服务器名称之间至少放置一个其他选项，例如 `--transport stdio`。143> `--env` 接受多个 `KEY=value` 对。如果服务器名称紧跟在 `--env` 之后，CLI 会将该名称读取为另一个键值对并拒绝它，因此请在 `--env` 和服务器名称之间至少放置一个其他选项，例如 `--transport stdio`。
144 144
145#### Claude Code 如何停止 stdio 服务器145#### Claude Code 如何停止 stdio 服务器
146 146
147当 Claude Code 断开 stdio 服务器时（例如您的会话结束时），它会向服务器进程发送信号，并短暂等待其退出，然后再强制停止它。如果您的服务器在关闭时保存状态或删除锁文件，请针对您的平台处理该信号，并在该时间内完成：147当 Claude Code 断开 stdio 服务器的连接时（例如会话结束时），它会向服务器进程发送信号，并短暂等待其退出，然后再强制停止。如果您的服务器在关闭时保存状态或删除锁文件，请处理您所在平台的信号，并在该时间内完成：
148 148
149* **在 macOS 和 Linux 上**：Claude Code 发送 `SIGINT`，如果进程在 100 毫秒后仍在运行，则发送 `SIGTERM`，再过 400 毫秒后发送 `SIGKILL`。149* **在 macOS 和 Linux 上**：Claude Code 发送 `SIGINT`，如果 100 毫秒后进程仍在运行，则发送 `SIGTERM`，再过 400 毫秒后发送 `SIGKILL`。
150* **在 Windows 上**：Claude Code 关闭服务器的 stdin，如果进程在 300 毫秒后仍在运行，则结束服务器的进程树。150* **在 Windows 上**：Claude Code 关闭服务器的 stdin，如果 300 毫秒后进程仍在运行，则结束服务器的进程树。
151 151
152在 v2.1.296 之前，Windows 上的 Claude Code 会立即结束服务器的进程树，而不先关闭 stdin 或等待。152在 v2.1.296 之前，Windows 上的 Claude Code 会立即结束服务器的进程树，既不先关闭 stdin，也不等待。
153 153
154### 选项 4：添加远程 WebSocket 服务器154### 选项 4：添加远程 WebSocket 服务器
155 155
156WebSocket 服务器保持持久的双向连接，适合主动向 Claude 推送事件的远程 MCP 服务器。当您的服务器仅响应请求时，请改用 HTTP，因为 HTTP 支持 OAuth 和 `claude mcp add --transport` 标志，而 WebSocket 都不支持。156WebSocket 服务器保持持久的双向连接，适合主动向 Claude 推送事件的远程 MCP 服务器。当您的服务器只响应请求时，请改用 HTTP，因为 HTTP 支持 OAuth 和 `claude mcp add --transport` 标志，而 WebSocket 两者都不支持。
157 157
158在 `.mcp.json` 中或使用 `claude mcp add-json` 配置 WebSocket 服务器：158在 `.mcp.json` 中或使用 `claude mcp add-json` 配置 WebSocket 服务器：
159 159
162 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'162 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'
163```163```
164 164
165`type: "ws"` 条目接受与 `http` 相同的 `url`、`headers`、`headersHelper`、`timeout` 和 `alwaysLoad` 字段。身份验证仅限标头，因此在 `headers` 中传递静态令牌或在连接时使用 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 生成一个。`claude mcp add --transport` 标志不接受 `ws`。165`type: "ws"` 条目接受与 `http` 相同的 `url`、`headers`、`headersHelper`、`timeout` 和 `alwaysLoad` 字段。身份验证仅通过请求头进行，因此请在 `headers` 中传递静态令牌，或在连接时使用 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 生成令牌。`claude mcp add --transport` 标志不接受 `ws`。
166 166
167### 从为另一个客户端编写的设置说明添加服务器167### 根据为其他客户端编写的设置说明添加服务器
168 168
169MCP 服务器不特定于 Claude Code，因此服务器的设置说明可能是为 Claude Desktop、Cursor 或另一个 MCP 客户端编写的，并且不提供 `claude mcp add` 命令。要添加服务器，请在这些说明中查找 URL、启动命令或 JSON 块：169MCP 服务器并非 Claude Code 专用，因此服务器的设置说明可能是为 Claude Desktop、Cursor 或其他 MCP 客户端编写的，并未提供 `claude mcp add` 命令。若仍要添加该服务器，请在这些说明中查找 URL、启动命令或 JSON 块：
170 170
171* **URL**，例如 `https://mcp.example.com/mcp`：服务器是远程的。171* **URL**，例如 `https://mcp.example.com/mcp`：该服务器是远程服务器。
172* **启动命令**，例如 `npx -y @example/mcp-server`：服务器在您的机器上运行。172* **启动命令**，例如 `npx -y @example/mcp-server`：该服务器在您的机器上运行。
173* **`mcpServers` JSON 块**：为另一个客户端的设置文件编写的配置。173* **`mcpServers` JSON 块**：为其他客户端的设置文件编写的配置。
174 174
175每一个都是 [安装 MCP 服务器](#installing-mcp-servers) 中四个选项之一接受的输入。找到您下面拥有的形状，将其转换为 Claude Code 接受的命令。除非您添加 `--scope project` 或 `--scope user`，否则每个命令都写入 [本地作用域](#local-scope)。175每一种都是[安装 MCP 服务器](#installing-mcp-servers)中四个选项所接受的输入之一。请在下方找到您所拥有的形式，将其转换为 Claude Code 接受的命令。除非您添加 `--scope project` 或 `--scope user`，否则每条命令都会写入[本地作用域](#local-scope)。
176 176
177#### 从 URL 添加服务器177#### 根据 URL 添加服务器
178 178
179URL 表示服务器是远程的。对于 `https://` 端点，使用 `--transport http` 添加它，或在说明说端点使用 SSE 时遵循 [选项 2](#option-2-add-a-remote-sse-server)。对于 `wss://` 端点，改为使用 [选项 4](#option-4-add-a-remote-websocket-server)，因为 `--transport` 不接受 `ws`：179URL 意味着该服务器是远程服务器。对于 `https://` 端点，使用 `--transport http` 添加；如果说明中指出该端点使用 SSE，请按照[选项 2](#option-2-add-a-remote-sse-server) 操作。对于 `wss://` 端点，请改用[选项 4](#option-4-add-a-remote-websocket-server)，因为 `--transport` 不接受 `ws`：
180 180
181```bash theme={null}181```bash theme={null}
182claude mcp add --transport http example https://mcp.example.com/mcp182claude mcp add --transport http example https://mcp.example.com/mcp
183```183```
184 184
185如果说明还提供 API 密钥或令牌标头，请使用 `--header` 传递它，如 [选项 1](#option-1-add-a-remote-http-server) 所示。185如果说明中还提供了 API 密钥或令牌请求头，请按照[选项 1](#option-1-add-a-remote-http-server) 中所示，使用 `--header` 传递。
186 186
187#### 从 `npx`、`uvx` 或二进制命令添加服务器187#### 根据 `npx`、`uvx` 或二进制命令添加服务器
188 188
189启动命令表示服务器作为本地 stdio 进程运行。将整个命令放在 `--` 之后，以便 Claude Code 将标志（如 `-y`）传递给启动服务器的命令，而不是将它们读取为自己的选项。使用 `--env` 传递说明要求的任何环境变量，在服务器名称之后和 `--` 之前：189启动命令意味着该服务器作为本地 stdio 进程运行。将整个命令放在 `--` 之后，这样 Claude Code 会将 `-y` 等标志传递给启动服务器的命令，而不是将其读取为自身的选项。使用 `--env` 传递说明中要求的任何环境变量，放在服务器名称之后、`--` 之前：
190 190
191```bash theme={null}191```bash theme={null}
192claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server192claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server
193```193```
194 194
195[选项 3](#option-3-add-a-local-stdio-server) 完整涵盖 `--` 分隔符。195[选项 3](#option-3-add-a-local-stdio-server) 完整介绍了 `--` 分隔符。
196 196
197#### 从 `mcpServers` JSON 块添加服务器197#### 根据 `mcpServers` JSON 块添加服务器
198 198
199为另一个 MCP 客户端（例如 Claude Desktop）编写的 `mcpServers` 块使用 Claude Code 读取的包装器键和条目形状。将 `mcpServers` 内的对象（而不是包装器）传递给 `claude mcp add-json`。两种条目需要先修复：199为其他 MCP 客户端（例如 Claude Desktop）编写的 `mcpServers` 块，使用的包装键和条目结构与 Claude Code 读取的相同。向 `claude mcp add-json` 传递 `mcpServers` 内部的对象，而不是包装层。有两种条目需要先修复：
200 200
201* **`url` 没有 `type`**：添加 `"type": "http"`、`"type": "sse"` 或 `"type": "ws"` 以匹配端点。Claude Code 将没有 `type` 的条目读取为 stdio 服务器，因此没有 `type` 的 `url` 条目会失败。201* **有 `url` 但没有 `type`**：添加 `"type": "http"`、`"type": "sse"` 或 `"type": "ws"` 以匹配端点。Claude Code 会将没有 `type` 的条目读取为 stdio 服务器，因此没有 `type` 的 `url` 条目会失败。
202* **键包含除字母、数字、连字符和下划线以外的字符**：选择仅使用这些字符的服务器名称。否则键就是服务器名称。202* **键包含字母、数字、连字符和下划线以外的字符**：选择仅使用这些字符的服务器名称。否则，键即为服务器名称。
203 203
204例如，此块：204例如，这个块：
205 205
206```json theme={null}206```json theme={null}
207{207{
214}214}
215```215```
216 216
217变成此命令：217会变成这条命令：
218 218
219```bash theme={null}219```bash theme={null}
220claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'220claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'
221```221```
222 222
223[从 JSON 配置添加 MCP 服务器](#add-mcp-servers-from-json-configuration) 涵盖 `add-json` 的 shell 转义和 `--scope` 标志。要与您的团队共享服务器，请改为添加 `--scope project`，或在项目根目录的 `.mcp.json` 中的 `mcpServers` 下添加条目并提交它。[项目作用域](#project-scope) 涵盖 Claude Code 如何加载和批准该文件。223[从 JSON 配置添加 MCP 服务器](#add-mcp-servers-from-json-configuration)介绍了 shell 转义以及 `add-json` 的 `--scope` 标志。若要改为与团队共享该服务器，请添加 `--scope project`，或者在项目根目录的 `.mcp.json` 中的 `mcpServers` 下添加该条目并提交。[项目作用域](#project-scope)介绍了 Claude Code 如何加载和批准该文件。
224 224
225每个 `claude mcp add` 和 `claude mcp add-json` 命令在成功时打印 `Added ...` 行。要检查 Claude Code 是否已连接，请运行 `claude mcp get <name>`；[服务器状态](#server-status) 涵盖它显示的状态和 `.mcp.json` 服务器的批准步骤。225每条 `claude mcp add` 和 `claude mcp add-json` 命令在成功时都会打印一行 `Added ...`。要检查 Claude Code 是否已连接，请运行 `claude mcp get <name>`；[服务器状态](#server-status)介绍了其显示的状态以及 `.mcp.json` 服务器的批准步骤。
226 226
227### 管理您的服务器227### 管理您的服务器
228 228
229配置后，您可以使用这些命令管理您的 MCP 服务器：229配置完成后，您可以使用以下命令管理 MCP 服务器：
230 230
231```bash theme={null}231```bash theme={null}
232# 列出所有配置的服务器232# List all configured servers
233claude mcp list233claude mcp list
234 234
235# 获取特定服务器的详细信息235# Get details for a specific server
236claude mcp get notion236claude mcp get notion
237 237
238# 删除服务器238# Remove a server
239claude mcp remove notion239claude mcp remove notion
240 240
241# （在 Claude Code 中）检查服务器状态241# (within Claude Code) Check server status
242/mcp242/mcp
243```243```
244 244
245移除远程服务器时，Claude Code 还会删除它为该服务器存储的 OAuth 令牌和客户端注册信息。Claude Code 不会在签发这些令牌的授权服务器上撤销令牌。如果授权服务器支持撤销，要撤销令牌，请在运行 `claude mcp remove <name>` 之前，先在 shell 中运行 [`claude mcp logout <name>`](#authenticate-from-the-command-line)。245当您移除远程服务器时，Claude Code 还会删除它为该服务器存储的 OAuth 令牌和客户端注册信息。Claude Code 不会在签发这些令牌的授权服务器上撤销令牌。若要在授权服务器支持撤销的情况下撤销令牌，请在 `claude mcp remove <name>` 之前，在 shell 中运行 [`claude mcp logout <name>`](#authenticate-from-the-command-line)。
246 246
247#### 服务器状态247#### 服务器状态
248 248
249`claude mcp add` 通过打印 `Added ...` 行确认成功添加，这意味着配置已写入。如果命令改为打印 `was not saved` 消息，请参阅 [MCP 服务器未保存或删除](https://code.claude.com/docs/zh-CN/errors.md#mcp-server-was-not-saved-or-removed)；对于 `may not have been saved` 消息，请参阅 [MCP 服务器可能未保存或删除](https://code.claude.com/docs/zh-CN/errors.md#mcp-server-may-not-have-been-saved-or-removed)。249`claude mcp add` 通过打印一行 `Added ...` 来确认添加成功，这表示配置已写入。如果该命令改为打印 `was not saved` 消息，请参阅 [MCP 服务器未被保存或移除](https://code.claude.com/docs/zh-CN/errors.md#mcp-server-was-not-saved-or-removed)；对于 `may not have been saved` 消息，请参阅 [MCP 服务器可能未被保存或移除](https://code.claude.com/docs/zh-CN/errors.md#mcp-server-may-not-have-been-saved-or-removed)。
250 250
251`claude mcp list` 在它列出的每个服务器旁边显示健康状态，例如 `✔ Connected`、`! Needs authentication` 或 `✘ Failed to connect`。失败状态意味着 Claude Code 无法连接到该服务器，而不是列表命令失败。251`claude mcp list` 会在列出的每个服务器旁显示健康状态，例如 `✔ Connected`、`! Needs authentication` 或 `✘ Failed to connect`。失败状态表示 Claude Code 无法连接到该服务器，而不是 list 命令执行失败。
252 252
253此列表中的状态报告配置决策而不是连接尝试，因此 Claude Code 在不连接到服务器的情况下打印它们：253此列表中的状态反映的是配置决定，而非连接尝试，因此 Claude Code 会在不连接服务器的情况下打印它们：
254 254
255* ``⏸ Pending approval (run `claude` to approve)``：来自 `.mcp.json`、您尚未批准的项目作用域服务器。Claude Code 会在 `claude mcp list` 和 `claude mcp get <name>` 中都显示此状态。以交互方式运行 `claude` 以审查并批准它。255* ``⏸ Pending approval (run `claude` to approve)``：来自 `.mcp.json`、您尚未批准的项目作用域服务器。Claude Code 会在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。以交互方式运行 `claude` 来审查并批准它。
256* `✘ Rejected (see disabledMcpjsonServers in settings)`：由 [`disabledMcpjsonServers`](https://code.claude.com/docs/zh-CN/settings-reference#disabledmcpjsonservers) 条目拒绝的 `.mcp.json` 服务器。Claude Code 仅在 `claude mcp get <name>` 中显示它。256* `✘ Rejected (see disabledMcpjsonServers in settings)`：被 [`disabledMcpjsonServers`](https://code.claude.com/docs/zh-CN/settings-reference#disabledmcpjsonservers) 条目拒绝的 `.mcp.json` 服务器。Claude Code 仅在 `claude mcp get <name>` 中显示它。
257* `⊘ Disabled for this project (re-enable via /mcp)`：项目的 [`disabledMcpServers`](#disable-a-server-without-removing-it) 列表命名的服务器。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。从 `/mcp` 面板重新打开服务器。257* `⊘ Disabled for this project (re-enable via /mcp)`：项目的 [`disabledMcpServers`](#disable-a-server-without-removing-it) 列表中指明的服务器。Claude Code 会在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。从 `/mcp` 面板重新启用该服务器。
258* `✘ Blocked by enterprise managed policy`：被您组织的某项策略拒绝的服务器。Claude Code 会在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。被[托管 MCP 配置](https://code.claude.com/docs/zh-CN/managed-mcp.md#how-restrictions-appear-to-users)中的允许列表、拒绝列表或其他限制阻止的服务器，会在这两个命令中都被隐藏，而不是以此状态显示。请询问您的管理员是哪项策略阻止了该服务器。258* `✘ Blocked by enterprise managed policy`：被您组织的某项策略拒绝的服务器。Claude Code 会在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。被[托管 MCP 配置](https://code.claude.com/docs/zh-CN/managed-mcp.md#how-restrictions-appear-to-users)中的允许列表、拒绝列表或其他限制阻止的服务器会在这两个命令中被隐藏，而不是以此状态显示。请询问您的管理员是哪项策略阻止了该服务器。
259 259
260#### 项目服务器批准和工作区信任260#### 项目服务器批准与工作区信任
261 261
262`claude mcp list` 和 `claude mcp get` 仅从未签入仓库的设置文件中读取 `.mcp.json` 批准，直到您通过在其中运行 `claude` 并接受工作区信任对话框来信任工作区。克隆的仓库无法批准自己的服务器：提交到项目的 `.claude/settings.json` 的 [`enableAllProjectMcpServers`](https://code.claude.com/docs/zh-CN/settings-reference#enableallprojectmcpservers) 或 [`enabledMcpjsonServers`](https://code.claude.com/docs/zh-CN/settings-reference#enabledmcpjsonservers) 在不受信任的文件夹中被忽略，服务器保持在 `⏸ Pending approval` 而不是被连接和健康检查。262在您通过在工作区中运行 `claude` 并接受工作区信任对话框来信任该工作区之前，`claude mcp list` 和 `claude mcp get` 只会从未签入仓库的设置文件中读取 `.mcp.json` 批准。克隆的仓库无法批准其自身的服务器：在不受信任的文件夹中，提交到项目 `.claude/settings.json` 中的 [`enableAllProjectMcpServers`](https://code.claude.com/docs/zh-CN/settings-reference#enableallprojectmcpservers) 或 [`enabledMcpjsonServers`](https://code.claude.com/docs/zh-CN/settings-reference#enabledmcpjsonservers) 会被忽略，服务器将保持 `⏸ Pending approval` 状态，而不会被连接和进行健康检查。
263 263
264这些来源的批准仍然适用于不受信任的文件夹：264来自以下来源的批准在不受信任的文件夹中仍然有效：
265 265
266* 您的用户 `~/.claude/settings.json`266* 您的用户 `~/.claude/settings.json`
267* 托管设置267* 托管设置
268* 使用 `--settings` 传递的设置268* 通过 `--settings` 传递的设置
269 269
270Claude Code 也应用来自未跟踪的 `.claude/settings.local.json` 的批准，但它运行 git 来检查文件是否被跟踪，并且仅在 [受信任的文件夹](https://code.claude.com/docs/zh-CN/permissions.md#project-allow-rules-and-workspace-trust) 中运行该检查。在您从未信任的文件夹中，Claude Code 等待信任对话框后才应用文件的批准，除非该文件夹是您自己的配置主目录：您的主目录，或其 `.claude` 您已设置为 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-CN/env-vars) 的目录。在 v2.1.207 之前，Claude Code 即使在您从未信任的文件夹中也应用来自未跟踪的 `.claude/settings.local.json` 的批准。270Claude Code 也会应用来自未跟踪的 `.claude/settings.local.json` 的批准，但它会运行 git 来检查该文件是否被跟踪，并且只在[受信任的文件夹](https://code.claude.com/docs/zh-CN/permissions.md#project-allow-rules-and-workspace-trust)中运行该检查。在您从未信任过的文件夹中，Claude Code 会等待信任对话框之后再应用该文件的批准，除非该文件夹是您自己的配置主目录：您的主目录，或者其 `.claude` 被您设置为 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-CN/env-vars) 的目录。在 v2.1.207 之前，即使在您从未信任过的文件夹中，Claude Code 也会应用来自未跟踪的 `.claude/settings.local.json` 的批准。
271 271
272任何设置文件中的 `disabledMcpjsonServers` 条目仍然拒绝服务器。272任何设置文件中的 `disabledMcpjsonServers` 条目仍会拒绝该服务器。
273 273
274#### 服务器状态详情274#### 服务器状态详情
275 275
276在 `/mcp` 中（包括服务器的菜单）和 [`/plugin`](https://code.claude.com/docs/zh-CN/plugins/install) 管理器中，您之前使用过的远程 HTTP 或 SSE 服务器可以显示 `cached` 状态，例如 `cached 2h ago · connects on first use · 5 tools`。Claude Code 从发现缓存加载了服务器的工具列表，该缓存保存在上一个会话中，而不是在启动时连接，Claude Code 在 Claude 首次调用服务器的工具之一时连接服务器。工具从您的第一条消息开始可用，因此您无需执行任何操作。发现缓存及其 `cached` 状态需要 Claude Code v2.1.221 或更高版本。276在 `/mcp`（包括其中的服务器菜单）以及 [`/plugin`](https://code.claude.com/docs/zh-CN/plugins/install) 管理器中，您以前使用过的远程 HTTP 或 SSE 服务器可能显示 `cached` 状态，例如 `cached 2h ago · connects on first use · 5 tools`。Claude Code 从其发现缓存（保存于之前的会话中）加载了该服务器的工具列表，而不是在启动时连接，并且 Claude Code 会在 Claude 首次调用该服务器的某个工具时连接该服务器。这些工具从您的第一条消息起即可使用，因此您无需执行任何操作。发现缓存及其 `cached` 状态需要 Claude Code v2.1.221 或更高版本。
277 277
278发现缓存默认关闭，除非逐步推出已为您的帐户启用它。设置 [`MCP_DISCOVERY_CACHE=1`](https://code.claude.com/docs/zh-CN/env-vars) 打开它，或设置为 `0` 即使推出已启用它也保持关闭。在 v2.1.238 之前，缓存默认打开。278除非逐步推出已为您的账户启用发现缓存，否则它默认处于关闭状态。设置 [`MCP_DISCOVERY_CACHE=1`](https://code.claude.com/docs/zh-CN/env-vars) 以启用它，或设置为 `0` 以在推出已启用它的情况下仍保持关闭。在 v2.1.238 之前，该缓存默认开启。
279 279
280当您从 `/mcp` 中的服务器菜单选择 **Disable** 或 **Clear authentication** 时，Claude Code 也会丢弃该服务器的缓存条目。**Reconnect** 在已连接或失败的服务器上也会丢弃它；在 `cached` 服务器上，**Reconnect** 会立即连接服务器并保留条目。丢弃条目后，Claude Code 下次连接到服务器时，会从服务器而不是从缓存获取工具列表。280当您在 `/mcp` 中从服务器菜单选择 **Disable** 或 **Clear authentication** 时，Claude Code 也会丢弃该服务器的缓存条目。对于已连接或失败的服务器，**Reconnect** 同样会丢弃它；对于 `cached` 服务器，**Reconnect** 会立即连接服务器并保留该条目。丢弃条目后，Claude Code 下次连接该服务器时，会从服务器而不是缓存获取工具列表。
281 281
282##### 连接失败与未配置的服务器282##### 连接失败与未配置的服务器
283 283
284当服务器状态为 `✘ Failed to connect` 时，`claude mcp list` 会在该状态行后附加失败详情，而 `claude mcp get <name>` 会在 `Issue:` 行中显示它。详情包括 HTTP 状态或错误代码，以及服务器返回的任何错误文本。`/mcp` 中服务器的详情视图会在其 `Issue:` 行中包含同样由服务器报告的文本。284当服务器状态为 `✘ Failed to connect` 时，`claude mcp list` 会将失败详情附加到该状态行，`claude mcp get <name>` 会在 `Issue:` 行中显示它。详情包括 HTTP 状态或错误代码，以及服务器返回的任何错误文本。`/mcp` 中该服务器的详情视图在其 `Issue:` 行中包含相同的服务器报告文本。
285 285
286Claude Code 会从这些详情中删除类似凭据的文本，并且绝不包含展开后的服务器 URL，因为它可能携带机密信息。Claude Code 不会在 `✘ Connection error` 状态后附加任何详情，因为它在那里打印的异常文本可能嵌入该 URL。286Claude Code 会从此详情中删去类似凭据的文本，并且从不包含展开后的服务器 URL，因为其中可能携带机密信息。Claude Code 不会在 `✘ Connection error` 状态后附加详情，因为它在那里打印的异常文本可能嵌入该 URL。
287 287
288当您从 `/mcp` 完成身份验证且连接仍然因 HTTP 状态或传输错误代码失败时，Claude Code 在尝试后打印的消息中添加该代码和服务器 URL 的来源。来源是方案和主机，加上 URL 命名的端口（如果有），例如 `https://mcp.example.com`。288当您从 `/mcp` 完成身份验证后，连接仍因 HTTP 状态或传输错误代码而失败时，Claude Code 会将该代码和服务器 URL 的源添加到尝试后打印的消息中。源是协议和主机，如果 URL 中指定了端口则还包括端口，例如 `https://mcp.example.com`。
289 289
290* 路径和查询永远不会出现在该消息中。290* 路径和查询字符串永远不会出现在该消息中。
291* 对于本地、项目或用户 [作用域](#mcp-installation-scopes) 中的服务器或托管 MCP 配置中的服务器，来源显示该配置中写入的主机，因此主机中的 `${VAR}` 引用在消息中不会展开。291* 对于本地、项目或用户[作用域](#mcp-installation-scopes)中的服务器，或托管 MCP 配置中的服务器，源显示的是该配置中所写的主机，因此主机中的 `${VAR}` 引用不会在消息中展开。
292* 对于没有状态或错误代码的失败，Claude Code 显示错误文本而不显示来源。292* 对于没有状态或错误代码的失败，Claude Code 显示错误文本而不显示源。
293 293
294配置为空 `url` 的远程服务器在 `/mcp`、`claude mcp list` 和 [`/plugin`](https://code.claude.com/docs/zh-CN/plugins/install) 管理器中显示为 `not configured`，Claude Code 不尝试连接到它。插件可以包含这样的占位符条目，用于您稍后配置的连接器，因此 Claude Code 不将其报告为错误或设置问题。`/mcp` 中的服务器详情视图显示 `No URL configured for this server`；设置条目的 `url` 以连接它。294配置中 `url` 为空的远程服务器会在 `/mcp`、`claude mcp list` 和 [`/plugin`](https://code.claude.com/docs/zh-CN/plugins/install) 管理器中显示为 `not configured`，并且 Claude Code 不会尝试连接它。插件可以为您稍后配置的连接器包含此类占位条目，因此 Claude Code 不会将其报告为错误或设置问题。`/mcp` 中该服务器的详情视图显示 `No URL configured for this server`；设置该条目的 `url` 即可连接它。
295 295
296#### 配置警告296#### 配置警告
297 297
298Claude Code 警告以下配置问题。每个条目说明 Claude Code 检查什么以及如何清除警告：298Claude Code 会对以下配置问题发出警告。每个条目都说明了 Claude Code 检查的内容以及如何消除警告：
299 299
300* **隐藏的空格**：当 MCP 配置值携带隐藏的前导或尾随空格时，Claude Code 发出警告，这通常来自粘贴带有尾随换行符的令牌。Claude Code 检查 `command`、`url`、每个 `args` 条目以及 `env` 和 `headers` 下的值和键名称。Claude Code 在 `claude mcp list` 输出和 `/mcp` 中显示警告，命名受影响的字段而不回显其值，例如 `Leading or trailing whitespace in: headers.Authorization`。Claude Code 不修剪空格并完全按照写入的方式使用值，因此请编辑配置以删除它。300* **隐藏的空白字符**：当 MCP 配置值带有隐藏的前导或尾随空白字符时，Claude Code 会发出警告，这通常来自粘贴带有尾随换行符的令牌。Claude Code 会检查 `command`、`url`、每个 `args` 条目，以及 `env` 和 `headers` 下的值和键名。Claude Code 会在 `claude mcp list` 输出和 `/mcp` 中显示警告，指明受影响的字段而不回显其值，例如 `Leading or trailing whitespace in: headers.Authorization`。Claude Code 不会修剪空白字符，而是完全按原样使用这些值，因此请编辑配置以删除它们。
301* **在多个作用域中使用相同名称**：如果您在多个 [作用域](#mcp-installation-scopes) 中定义相同的服务器名称，具有不同的端点，Claude Code 在 `claude mcp list` 输出和 `/mcp` 中警告冲突。Claude Code 按端点存储 OAuth 登录，因此当您在一个项目中对加载的定义进行身份验证时，您仍然需要在加载不同定义的项目中单独登录。保留您想要的端点并使用 `claude mcp remove <name> --scope <scope>` 删除其他端点。在警告中，Claude Code 按您的配置中所写的形式引用每个作用域的端点，[`${VAR}` 引用](#environment-variable-expansion-in-mcp-json) 保持未展开，因此它永远不显示已解析的值，例如 API 密钥。301* **多个作用域中的同名服务器**：如果您在多个[作用域](#mcp-installation-scopes)中定义了同名但端点不同的服务器，Claude Code 会在 `claude mcp list` 输出和 `/mcp` 中警告该冲突。Claude Code 按端点存储 OAuth 登录信息，因此当您对在某个项目中加载的定义进行身份验证后，在加载不同定义的项目中仍需单独登录。保留您需要的端点，并使用 `claude mcp remove <name> --scope <scope>` 移除其他端点。在警告中，Claude Code 按配置中所写的内容引用每个作用域的端点，[`${VAR}` 引用](#environment-variable-expansion-in-mcp-json)不会展开，因此绝不会显示诸如 API 密钥之类的解析值。
302* **保留名称**：Claude Code 保留其内置服务器的名称，包括 `workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview` 和 `Claude Browser`。如果您的配置定义具有保留名称的服务器，Claude Code 在加载时跳过它并显示警告，要求您重命名它。`claude mcp add` 拒绝保留名称并出现错误。`Claude Preview` 和 `Claude Browser` 都命名 [Claude Code 桌面应用的预览窗格](https://code.claude.com/docs/zh-CN/desktop.md#preview-your-app) 使用的内置服务器。302* **保留名称**：Claude Code 保留其内置服务器的名称，包括 `workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview` 和 `Claude Browser`。如果您的配置定义了使用保留名称的服务器，Claude Code 会在加载时跳过它，并显示一条要求您重命名的警告。`claude mcp add` 会以错误拒绝保留名称。`Claude Preview` 和 `Claude Browser` 都指代 [Claude Code 桌面应用的预览窗格](https://code.claude.com/docs/zh-CN/desktop.md#preview-your-app)所使用的内置服务器。
303* **缺少环境变量**：如果服务器配置中的 [`${VAR}` 引用](#environment-variable-expansion-in-mcp-json) 命名未设置且没有 `:-default` 的变量，Claude Code 在 `claude mcp list` 输出和 `/mcp` 中警告，命名变量，并仍然使用 `${VAR}` 文本未展开加载服务器。设置变量或添加 `${VAR:-default}` 备用值。在远程服务器的 `url` 和 `headers` 中，某些凭据变量 [读取为空](#credential-variables-that-read-as-empty) 而不显示警告。303* **缺少环境变量**：如果服务器配置中的 [`${VAR}` 引用](#environment-variable-expansion-in-mcp-json)指向一个未设置且没有 `:-default` 的变量，Claude Code 会在 `claude mcp list` 输出和 `/mcp` 中发出警告并指明该变量，同时仍以未展开的 `${VAR}` 文本加载该服务器。请设置该变量或添加 `${VAR:-default}` 备用值。在远程服务器的 `url` 和 `headers` 中，某些凭据变量则会[读取为空](#credential-variables-that-read-as-empty)，且不发出警告。
304 304
305#### 工具可用性305#### 工具可用性
306 306
307`/mcp` 面板在每个连接的服务器旁边显示工具计数，并标记声称工具能力但不公开工具的服务器。307`/mcp` 面板会在每个已连接服务器旁显示工具数量，并标记那些声明了工具能力但未公开任何工具的服务器。
308 308
309##### 云端会话中的工具数量309##### 云端会话中的工具数量
310 310
311在[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)中，诸如 `3 of 13 tools available` 之类的计数表示 Claude 无法使用另外 10 个工具。请检查以下原因（以及其他可能的原因）：311在[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)中，诸如 `3 of 13 tools available` 的计数意味着 Claude 无法使用其余 10 个工具。请检查以下原因（包括但不限于）：
312 312
313* **仓库 `.claude/settings.json` 中的拒绝规则指定了该工具或其整个服务器**：如果[您的会话会读取该文件](https://code.claude.com/docs/zh-CN/settings.md#settings-in-cloud-sessions)，请移除该[规则](https://code.claude.com/docs/zh-CN/permissions.md#mcp)313* **仓库 `.claude/settings.json` 中的拒绝规则指明了该工具或其整个服务器**：如果[您的会话读取该文件](https://code.claude.com/docs/zh-CN/settings.md#settings-in-cloud-sessions)，请移除该[规则](https://code.claude.com/docs/zh-CN/permissions.md#mcp)
314* **工具的完整名称超过 128 个字符**：按照[名称过长的处理步骤](https://code.claude.com/docs/zh-CN/errors.md#mcp-tool-name-over-128-characters)操作314* **工具的完整名称超过 128 个字符**：请按照[名称过长的处理步骤](https://code.claude.com/docs/zh-CN/errors.md#mcp-tool-name-over-128-characters)操作
315* **服务器是为其自身界面而非为 Claude 列出该工具**：如果您维护该服务器，请将 `model` 添加到该工具的 `_meta.ui.visibility` 中，以便将该工具提供给 Claude。否则，无需修复任何内容。315* **服务器为其自身界面而非为 Claude 列出该工具**：如果您维护该服务器，请将 `model` 添加到该工具的 `_meta.ui.visibility` 中，以便将该工具提供给 Claude。否则，无需修复任何内容。
316 316
317##### 来自仍在连接中的服务器的工具317##### 来自仍在连接中的服务器的工具
318 318
319如果您的请求需要来自仍在后台连接的服务器的工具，Claude 会在继续之前等待该服务器。等待的方式取决于您的配置：319如果您的请求需要来自仍在后台连接的服务器的工具，Claude 会等待该服务器后再继续。等待的方式取决于您的配置：
320 320
321* **使用 [工具搜索](#scale-with-mcp-tool-search)（默认）**：等待发生在 `ToolSearch` 调用内。321* **使用[工具搜索](#scale-with-mcp-tool-search)（默认）时**：等待发生在 `ToolSearch` 调用内部。
322* **不使用工具搜索**：Claude 改为使用 `WaitForMcpServers` 工具。不使用工具搜索的配置包括 `ENABLE_TOOL_SEARCH=false`，以及 Google Cloud 的 Agent Platform 上早于 Claude Opus 4.5、Claude Sonnet 4.5 和 Claude Haiku 4.5 的模型。对于 `ANTHROPIC_BASE_URL` 网关，请参阅 [通过 LLM 网关使用工具搜索](#tool-search-through-a-gateway)。322* **不使用工具搜索时**：Claude 改用 `WaitForMcpServers` 工具。不使用工具搜索的配置包括 `ENABLE_TOOL_SEARCH=false`，以及在 Google Cloud 的 Agent Platform 上使用早于 Claude Opus 4.5、Claude Sonnet 4.5 和 Claude Haiku 4.5 的模型。对于 `ANTHROPIC_BASE_URL` 网关，请参阅[通过 LLM 网关使用工具搜索](#tool-search-through-a-gateway)。
323* **在 Microsoft Foundry [部署托管在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**：Claude 在工具搜索路径上启动而不是使用 `WaitForMcpServers`，因为 Claude Code 仅从 API 发现部署的服务器端拒绝。Claude Code 将该部署切换到 [前期加载](#scale-with-mcp-tool-search) 后，来自完成连接的服务器的工具在 Claude 的下一个请求中变为可用。323* **在 Microsoft Foundry [托管于 Azure 的部署](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)上**：Claude 从工具搜索路径开始，而不是使用 `WaitForMcpServers`，因为 Claude Code 只能从 API 发现该部署在服务器端的拒绝。在 Claude Code 将该部署切换为[预先加载](#scale-with-mcp-tool-search)后，来自完成连接的服务器的工具会在 Claude 的下一次请求中可用。
324 324
325启用工具搜索后，当服务器在 Claude 工作时完成连接时，Claude Code 在同一轮次的下一个请求中将服务器的工具名称列出给 Claude。Claude 然后可以搜索和调用这些工具，而无需等待您的下一条消息。325启用工具搜索后，当某个服务器在 Claude 工作期间完成连接时，Claude Code 会在同一轮次中 Claude 的下一次请求里向 Claude 列出该服务器的工具名称。Claude 随后无需等待您的下一条消息，即可搜索并调用这些工具。
326 326
327恢复会话后，Claude 可以在工具的 MCP 服务器仍在连接时调用已保存对话中的工具。当服务器处于首次连接尝试时，Claude Code 会将该调用保留最多 10 秒，并在工具可用后运行它。如果服务器未能及时连接，或者已在 [失败尝试后重试](#automatic-reconnection)，调用会失败并返回 `No such tool available` [工具错误](https://code.claude.com/docs/zh-CN/errors.md#no-such-tool-available)。327恢复会话后，Claude 可能会在某个工具的 MCP 服务器仍在连接时调用已保存对话中的该工具。当服务器处于首次连接尝试期间，Claude Code 会将该调用保持最多 10 秒，并在工具可用后运行它。如果服务器未能及时连接，或者它已经在[失败尝试后重试](#automatic-reconnection)，该调用会以 `No such tool available` [工具错误](https://code.claude.com/docs/zh-CN/errors.md#no-such-tool-available)失败。
328 328
329### 禁用服务器而不删除它329### 禁用服务器而不移除它
330 330
331在 `/mcp` 面板中切换服务器关闭，以停止 Claude Code 连接到它，而不丢失其配置。Claude Code 仍然在 `/mcp` 中列出服务器，标记为禁用。331在 `/mcp` 面板中关闭某个服务器，即可阻止 Claude Code 连接它，同时不丢失其配置。Claude Code 仍会在 `/mcp` 中列出该服务器，并标记为已禁用。
332 332
333当您切换服务器时，Claude Code 在 `~/.claude.json` 中按项目记录您的选择，在两个涵盖不相交服务器集的列表之一中：333当您切换服务器时，Claude Code 会按项目将您的选择记录在 `~/.claude.json` 中两个列表之一里，这两个列表涵盖互不相交的服务器集合：
334 334
335* `disabledMcpServers`：用户配置的服务器、插件服务器、您的组织 [通过托管设置提供](https://code.claude.com/docs/zh-CN/managed-mcp.md#provide-servers-through-managed-settings) 的服务器、Claude Code [自己获取](#how-connectors-reach-claude-code) 的 claude.ai 连接器以及默认打开的内置服务器的选择退出列表。Claude Code 不连接您在此处列出的服务器。当您使用 [禁用 claude.ai 连接器](#disable-claude-ai-connectors) 中描述的按项目 `/mcp` 切换禁用 claude.ai 连接器时，Claude Code 在此列表下使用其显示名称（例如 `claude.ai Slack`）写入它。335* `disabledMcpServers`：一个选择退出列表，适用于用户配置的服务器、插件服务器、您的组织[通过托管设置提供的服务器](https://code.claude.com/docs/zh-CN/managed-mcp.md#provide-servers-through-managed-settings)、Claude Code [自行获取的](#how-connectors-reach-claude-code) claude.ai 连接器，以及默认开启的内置服务器。Claude Code 不会连接您在此处列出的服务器。当您使用[禁用 claude.ai 连接器](#disable-claude-ai-connectors)中所述的按项目 `/mcp` 开关禁用某个 claude.ai 连接器时，Claude Code 会以其显示名称将其写入此列表，例如 `claude.ai Slack`。
336* `enabledMcpServers`：默认关闭的内置服务器（例如 `computer-use`）的选择加入列表。Claude Code 仅当您在此处列出它时才连接默认关闭的服务器。336* `enabledMcpServers`：一个选择加入列表，适用于默认关闭的内置服务器，例如 `computer-use`。只有当您在此处列出默认关闭的服务器时，Claude Code 才会连接它。
337 337
338Claude Code 为每个服务器查询恰好两个列表之一，因此两个列表都不会覆盖另一个。如果您将常规服务器添加到 `enabledMcpServers`，或将默认关闭的内置服务器添加到 `disabledMcpServers`，Claude Code 会忽略该条目。338Claude Code 对每个服务器只参考这两个列表中的一个，因此两个列表都不会覆盖另一个。如果您将常规服务器添加到 `enabledMcpServers`，或将默认关闭的内置服务器添加到 `disabledMcpServers`，Claude Code 会忽略该条目。
339 339
340`disabledMcpServers` 和 `enabledMcpServers` 与 [`enabledMcpjsonServers`](https://code.claude.com/docs/zh-CN/settings-reference#enabledmcpjsonservers) 和 [`disabledMcpjsonServers`](https://code.claude.com/docs/zh-CN/settings-reference#disabledmcpjsonservers) 无关，后者控制项目的 `.mcp.json` 文件中定义的服务器的批准。340`disabledMcpServers` 和 `enabledMcpServers` 与 [`enabledMcpjsonServers`](https://code.claude.com/docs/zh-CN/settings-reference#enabledmcpjsonservers) 和 [`disabledMcpjsonServers`](https://code.claude.com/docs/zh-CN/settings-reference#disabledmcpjsonservers) 无关，后两者控制对项目 `.mcp.json` 文件中所定义服务器的批准。
341 341
342### MCP 客户端运行时342### MCP 客户端运行时
343 343
344Claude Code 通过两个客户端运行时之一连接到 MCP 服务器。v1 运行时基于 MCP TypeScript SDK 1.x。v2 运行时是 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 上的相同代码，它添加了 MCP 协议修订版 2026-07-28。本页的其余部分适用于两个运行时，除非某个部分指明 v2 运行时。344Claude Code 通过两种客户端运行时之一连接到 MCP 服务器。v1 运行时基于 MCP TypeScript SDK 1.x 构建。v2 运行时是基于 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 的相同代码，增加了 MCP 协议修订版 2026-07-28。除非某个章节明确指出 v2 运行时，否则本页其余内容同时适用于两种运行时。
345 345
346Claude Code 在每次启动时选择一个运行时，并在您退出前保持它。在 [获取功能标志](https://code.claude.com/docs/zh-CN/env-vars.md#features-that-need-feature-flag-fetching) 的会话中，它在 Claude Code v2.1.232 或更高版本上使用 v2 运行时。346Claude Code 每次启动时选择一种运行时，并在退出前一直使用它。在[获取功能标志](https://code.claude.com/docs/zh-CN/env-vars.md#features-that-need-feature-flag-fetching)的会话中，Claude Code v2.1.232 或更高版本使用 v2 运行时。
347 347
348在不获取功能标志的会话中，Claude Code 在 Claude Code v2.1.274 或更高版本上默认使用 v2 运行时：348在不获取功能标志的会话中，Claude Code v2.1.274 或更高版本默认使用 v2 运行时：
349 349
350* Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的会话，除非嵌入 Claude Code 的主机平台设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/zh-CN/env-vars)350* 在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的会话，除非嵌入 Claude Code 的宿主平台设置了 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/zh-CN/env-vars)
351* 通过 [Claude 应用网关](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 登录的会话351* 通过 [Claude 应用网关](https://code.claude.com/docs/zh-CN/claude-apps-gateway)登录的会话
352* 您关闭遥测或功能标志获取的会话，例如使用 `DISABLE_TELEMETRY`352* 您关闭了遥测或功能标志获取的会话，例如使用 `DISABLE_TELEMETRY`
353 353
354在 v2 上，Claude Code 还会：354在 v2 上，Claude Code 还会：
355 355
356* 询问 HTTP、stdio 和 claude.ai 连接器服务器是否支持较新的修订版，并与支持的服务器一起使用它。这包括云端会话和 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 会话的连接器。Claude Code 与 v1 一样连接到其他所有服务器。356* 询问 HTTP、stdio 和 claude.ai 连接器服务器是否支持较新的修订版，并对支持的服务器使用该修订版。这包括云端会话和 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 会话的连接器。Claude Code 以与 v1 相同的方式连接所有其他服务器。
357* 通过 [它保持打开的流](#notification-streams-on-the-v2-runtime) 从使用较新修订版的服务器接收 `list_changed` 通知。357* 通过[其保持打开的流](#notification-streams-on-the-v2-runtime)接收来自使用较新修订版的服务器的 `list_changed` 通知。
358* 不注册在较新修订版上连接的 [频道](#push-messages-with-channels) 服务器，因为该修订版无法携带频道消息。358* 不注册以较新修订版连接的[频道](#push-messages-with-channels)服务器，因为该修订版无法传递频道消息。
359* 当授权响应指明意外的发行者时，使 [MCP OAuth 登录](#authenticate-with-remote-mcp-servers) 失败。359* 当授权响应指明了意外的颁发者时，使 [MCP OAuth 登录](#authenticate-with-remote-mcp-servers)失败。
360* 仅将 [MCP OAuth](#authenticate-with-remote-mcp-servers) 凭据发送到通过 HTTPS 或在 `localhost`、`127.0.0.1` 或 `::1` 上提供的令牌端点。对于令牌端点在其他任何地方为纯 `http://` 的服务器（例如本地网络上的设备），登录失败。请参阅 [拒绝向非 https 令牌端点发送凭据](https://code.claude.com/docs/zh-CN/errors.md#refusing-to-send-credentials-to-non-https-token-endpoint)。360* 仅将 [MCP OAuth](#authenticate-with-remote-mcp-servers) 凭据发送到通过 HTTPS 提供服务的令牌端点，或位于 `localhost`、`127.0.0.1` 或 `::1` 的令牌端点。对于令牌端点在其他任何位置使用纯 `http://` 的服务器（例如您本地网络上的设备），登录会失败。请参阅 [Refusing to send credentials to non-https token endpoint](https://code.claude.com/docs/zh-CN/errors.md#refusing-to-send-credentials-to-non-https-token-endpoint)。
361 361
362Anthropic 可以通过 Claude Code 获取的功能标志，让特定服务器保持使用较早的协议，或不使用该流。要自行选择运行时，请将 [`MCP_SDK_GENERATION`](https://code.claude.com/docs/zh-CN/env-vars) 设置为 `v1` 或 `v2`。362Anthropic 可以通过 Claude Code 获取的功能标志，让特定服务器保持使用较早的协议，或不使用该流。若要自行选择运行时，请将 [`MCP_SDK_GENERATION`](https://code.claude.com/docs/zh-CN/env-vars) 设置为 `v1` 或 `v2`。
363 363
364要决定 Claude Code 是否向服务器询问较新的修订版，请将 [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/zh-CN/env-vars) 设置为 `auto` 或 `legacy`。如果未设置该变量，Claude Code 可能会在 7 天内跳过对某个 stdio 服务器的询问，例如在服务器被询问时退出之后。要让已升级的服务器更早被询问，请设置 `auto`。364若要决定 Claude Code 是否向服务器询问较新的修订版，请将 [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/zh-CN/env-vars) 设置为 `auto` 或 `legacy`。未设置该变量时，Claude Code 可能会在 7 天内跳过询问某个 stdio 服务器，例如在该服务器被询问时退出之后。若要让已升级的服务器更早被询问，请设置为 `auto`。
365 365
366### 动态工具更新366### 动态工具更新
367 367
368MCP 服务器可以在连接期间更改其提供的工具、提示词或资源，并发送 `list_changed` 通知。收到通知时：368MCP 服务器可以在连接期间更改其提供的工具、提示词或资源，并发送 `list_changed` 通知。当收到通知时：
369 369
370* **在交互式终端会话中**，Claude Code 从该服务器获取更新后的列表，因此您无需重新连接它。370* **在交互式终端会话中**，Claude Code 会从该服务器获取更新后的列表，因此您无需重新连接它。
371* **在使用 `-p` 标志的 [非交互模式](https://code.claude.com/docs/zh-CN/headless.md) 和 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 中**，Claude Code 在收到这些通知时仅刷新工具列表。371* **在使用 `-p` 标志的[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)以及 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 中**，Claude Code 收到这些通知时只刷新工具列表。
372 372
373如果刷新请求失败，Claude Code 保留服务器之前发现的工具、提示词和资源，直到稍后的刷新成功。373如果刷新请求失败，Claude Code 会保留该服务器先前发现的工具、提示词和资源，直到后续刷新成功。
374 374
375#### v2 运行时上的通知流375#### v2 运行时上的通知流
376 376
377在 [v2 运行时](#mcp-client-runtimes) 上，Claude Code 通过它保持打开的流从使用较新协议修订版的服务器接收 `list_changed` 通知。当流关闭时，Claude Code 重新打开它，有两个限制：377在 [v2 运行时](#mcp-client-runtimes)上，Claude Code 通过其保持打开的流，接收来自使用较新协议修订版的服务器的 `list_changed` 通知。当流关闭时，Claude Code 会重新打开它，但有两个限制：
378 378
379* **流在 10 秒内再次关闭**：Claude Code 最多重新打开三次，然后停止该连接。379* **流在 10 秒内再次关闭**：Claude Code 最多重新打开三次，然后对该连接停止重新打开。
380* **流保持打开超过 10 秒，然后关闭**，连接到无服务器主机的流通常如此：在一小时内五次重新打开后，Claude Code 在下一次之前等待约六小时。380* **流保持打开超过 10 秒后关闭**（连接到无服务器主机的流通常如此）：在一小时内重新打开五次后，Claude Code 会等待约六小时再进行下一次。
381 381
382在流重新打开之前，您保留服务器最后获取的工具、提示词和资源。要更快地获取其更改，请从 `/mcp` 重新连接服务器。382在流重新打开之前，您将保留该服务器最后获取的工具、提示词和资源。若要更快获取其更改，请从 `/mcp` 重新连接该服务器。
383 383
384### 自动重新连接384### 自动重新连接
385 385
386Claude Code 重新连接在会话中途断开的远程服务器，并在瞬时错误后重试 HTTP 或 SSE 服务器的首次连接。对于 stdio 服务器，请参阅 [退出或无法启动的 stdio 服务器](#stdio-servers-that-exit-or-fail-to-start)。386Claude Code 会重新连接在会话中途断开的远程服务器，并在出现暂时性错误后重试 HTTP 或 SSE 服务器的首次连接。对于 stdio 服务器，请参阅[退出或启动失败的 stdio 服务器](#stdio-servers-that-exit-or-fail-to-start)。
387 387
388#### 远程服务器的会话中途断开388#### 远程服务器在会话中途断开
389 389
390Claude Code 首先使用指数退避尝试重新连接断开的远程服务器，最多五次，从一秒延迟开始，每次加倍：390Claude Code 首先会以指数退避方式尝试重新连接断开的远程服务器，最多五次，初始延迟为一秒，每次加倍：
391 391
392* **在交互式会话中**：`/mcp` 在 Claude Code 重新连接时显示服务器为待处理。在五次失败尝试后，Claude Code 将服务器标记为失败，或在服务器需要再次授权时标记为需要身份验证。当它将服务器标记为失败时，您会看到 `MCP server "<name>" disconnected · open /mcp to reconnect` 通知。您可以从 `/mcp` 手动重试。392* **在交互式会话中**：Claude Code 重新连接期间，`/mcp` 会将该服务器显示为待定状态。五次尝试失败后，Claude Code 会将该服务器标记为失败，或在服务器需要重新授权时标记为需要身份验证。当它将服务器标记为失败时，您会看到 `MCP server "<name>" disconnected · open /mcp to reconnect` 通知。您可以从 `/mcp` 手动重试。
393* **在 [`claude -p`](https://code.claude.com/docs/zh-CN/headless) 运行和 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 会话中**：Claude Code 进行相同的五次尝试，没有 `/mcp` 面板显示这些尝试。如果五次尝试全部失败，运行会在没有该服务器工具的情况下继续：393* **在 [`claude -p`](https://code.claude.com/docs/zh-CN/headless) 运行和 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 会话中**：Claude Code 进行同样的五次尝试，但没有 `/mcp` 面板来显示它们。如果五次都失败，运行会在没有该服务器工具的情况下继续：
394 * **在瞬时错误（例如 5xx 响应或超时）之后**：Claude Code 在后台继续重试 HTTP 或 SSE 服务器。重试最多持续约半小时，当某次重试连接成功时，服务器的工具会再次可用。在此之前，Agent SDK 会话报告 [状态](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md#error-handling) `failed`，您的代码可以 [重新连接服务器](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md#error-handling)。要在 `claude -p` 中重新连接它，请重新开始运行。394 * **在暂时性错误（例如 5xx 响应或超时）之后**：Claude Code 会在后台持续重试 HTTP 或 SSE 服务器。重试最多持续约半小时，当某次连接成功时，该服务器的工具会重新可用。在此之前，Agent SDK 会话会报告[状态](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md#error-handling) `failed`，您的代码可以[重新连接该服务器](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md#error-handling)。若要在 `claude -p` 中重新连接它，请重新开始运行。
395 * **当服务器 [需要您重新登录](#authenticate-with-remote-mcp-servers) 时**：Claude Code 停止重试，Agent SDK 会话将服务器的状态报告为 `needs-auth`。在您的 shell 中使用 [`claude mcp login <name>`](#authenticate-from-the-command-line) 登录。然后重新开始运行，或者在 Agent SDK 会话中改为 [重新连接服务器](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md#error-handling)。395 * **当服务器[需要您重新登录](#authenticate-with-remote-mcp-servers)时**：Claude Code 停止重试，Agent SDK 会话会将该服务器的状态报告为 `needs-auth`。在 shell 中使用 [`claude mcp login <name>`](#authenticate-from-the-command-line) 登录。然后重新开始运行，或者在 Agent SDK 会话中改为[重新连接该服务器](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md#error-handling)。
396 396
397#### 失败的首次连接397#### 首次连接失败
398 398
399当 HTTP 或 SSE 服务器的首次连接因瞬时错误（例如 5xx 响应、连接被拒绝或超时）失败时，Claude Code 最多重试三次。如果连接仍然失败，Claude Code 将服务器标记为失败。399当 HTTP 或 SSE 服务器的首次连接因暂时性错误（例如 5xx 响应、连接被拒绝或超时）而失败时，Claude Code 最多重试三次。如果连接仍然失败，Claude Code 会将该服务器标记为失败。
400 400
401这些重试在以下情况下不适用：401在以下情况下不会进行这些重试：
402 402
403* stdio 服务器的首次连接。要再次尝试，请参阅 [退出或无法启动的 stdio 服务器](#stdio-servers-that-exit-or-fail-to-start)403* stdio 服务器的首次连接。若要再次尝试，请参阅[退出或启动失败的 stdio 服务器](#stdio-servers-that-exit-or-fail-to-start)
404* WebSocket 服务器的首次连接。要在交互式终端会话中再次尝试，请从 `/mcp` 中该服务器的菜单选择 **Reconnect**404* WebSocket 服务器的首次连接。若要在交互式终端会话中再次尝试，请在 `/mcp` 中从该服务器的菜单选择 **Reconnect**
405* 身份验证或未找到错误，因为它需要配置更改来解决。当 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 是服务器唯一的 `Authorization` 标头来源时，Claude Code 仍然重试身份验证错误，因为它在每次尝试时重新运行助手并可以获取新凭据405* 身份验证错误或未找到错误，因为需要更改配置才能解决。当 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 是该服务器 `Authorization` 请求头的唯一来源时，Claude Code 仍会重试身份验证错误，因为它在每次尝试时都会重新运行该 helper，并可能获取到新的凭据
406 406
407#### 退出或无法启动的 stdio 服务器407#### 退出或启动失败的 stdio 服务器
408 408
409要重新启动 stdio 服务器，请阅读与其所发生情况相符的列。根据您运行 Claude Code 的方式找到对应的行：交互式会话、`claude -p` 运行或 Agent SDK 会话。409若要重新启动 stdio 服务器，请阅读与其遭遇情况相对应的列。根据您运行 Claude Code 的方式找到对应的行：交互式会话、`claude -p` 运行或 Agent SDK 会话。
410 410
411| 您运行 Claude Code 的方式 | 服务器进程在会话中途退出 | 服务器的首次连接失败 |411| 您运行 Claude Code 的方式 | 服务器进程在会话中途退出 | 服务器首次连接失败 |
412| - | - | - |412| - | - | - |
413| 交互式会话 | Claude Code 将服务器标记为失败。要重新启动它，请从 `/mcp` 中该服务器的菜单选择 **Reconnect** | Claude Code 将服务器标记为失败。要重新启动它，请从 `/mcp` 中该服务器的菜单选择 **Reconnect** |413| 交互式会话 | Claude Code 将该服务器标记为失败。若要重新启动它，请在 `/mcp` 中从该服务器的菜单选择 **Reconnect** | Claude Code 将该服务器标记为失败。若要重新启动它，请在 `/mcp` 中从该服务器的菜单选择 **Reconnect** |
414| `claude -p` 运行 | Claude Code 在 Claude 下次调用该服务器的某个工具时重新启动服务器，调用会在服务器连接后运行 | 运行会在没有该服务器工具的情况下继续。要让 Claude Code 再次尝试连接，请重新开始运行。当插件提供该服务器时，新的运行会在失败后 15 分钟内跳过连接，因此请先等待这段时间，或 [更早重试](https://code.claude.com/docs/zh-CN/errors.md#skipping-connection-recent-failure-cached) |414| `claude -p` 运行 | Claude Code 会在 Claude 下次调用该服务器的某个工具时重新启动该服务器，并在服务器连接后运行该调用 | 运行会在没有该服务器工具的情况下继续。若要让 Claude Code 再次尝试连接，请重新开始运行。当服务器由插件提供时，新的运行会在失败后 15 分钟内跳过连接，因此请先等待这段时间，或[更早重试](https://code.claude.com/docs/zh-CN/errors.md#skipping-connection-recent-failure-cached) |
415| Agent SDK 会话 | Claude Code 在 Claude 下次调用该服务器的某个工具时重新启动服务器，调用会在服务器连接后运行 | 会话会在没有该服务器工具的情况下继续。您的代码可以 [重新连接服务器](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md#error-handling) |415| Agent SDK 会话 | Claude Code 会在 Claude 下次调用该服务器的某个工具时重新启动该服务器，并在服务器连接后运行该调用 | 会话会在没有该服务器工具的情况下继续。您的代码可以[重新连接该服务器](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md#error-handling) |
416 416
417#### 失败的发现请求417#### 发现请求失败
418 418
419服务器连接后，Claude Code 向其发送能力发现请求，例如 `tools/list`、`prompts/list` 和 `resources/list`。Claude Code 在瞬时网络或服务器错误后最多重试这些请求三次，短退避。它不重试身份验证错误、4xx 响应或请求超时。419服务器连接后，Claude Code 会向其发送能力发现请求，例如 `tools/list`、`prompts/list` 和 `resources/list`。在出现暂时性网络或服务器错误后，Claude Code 会以短暂退避方式重试这些请求，最多三次。它不会重试身份验证错误、4xx 响应或请求超时。
420 420
421#### 自行重试失败的服务器421#### 自行重试失败的服务器
422 422
423要重试每个失败或需要身份验证的服务器，请在交互式终端会话中的 Claude Code 输入框运行 `/mcp reconnect all`。这需要 Claude Code v2.1.284 或更高版本。较早的版本会打印 `MCP server "all" not found`。423若要重试所有失败或需要身份验证的服务器，请在交互式终端会话中于 Claude Code 提示符处运行 `/mcp reconnect all`。这需要 Claude Code v2.1.284 或更高版本。更早的版本会打印 `MCP server "all" not found`。
424 424
425#### Claude 如何了解服务器失败425#### Claude 如何得知服务器失败
426 426
427Claude Code 是否告诉 Claude 配置的服务器未能连接取决于 [工具搜索](#scale-with-mcp-tool-search)，默认打开：427Claude Code 是否将连接失败的已配置服务器告知 Claude，取决于默认开启的[工具搜索](#scale-with-mcp-tool-search)：
428 428
429* 使用工具搜索，Claude Code 告诉 Claude 哪个服务器失败及其连接错误，因此 Claude 在其回复中报告连接失败。Claude Code 在找不到匹配工具的 `ToolSearch` 结果中包含相同的信息。429* 使用工具搜索时，Claude Code 会告诉 Claude 哪个服务器失败及其连接错误，因此 Claude 会在其回复中报告连接失败。Claude Code 还会在未找到匹配工具的 `ToolSearch` 结果中包含相同的信息。
430* 在任何 [不使用工具搜索的配置](#configure-tool-search) 中，Claude Code 不向 Claude 报告失败的服务器连接。430* 在任何[不使用工具搜索的配置](#configure-tool-search)中，Claude Code 不会向 Claude 报告失败的服务器连接。
431 431
432### 使用频道推送消息432### 使用频道推送消息
433 433
434MCP 服务器也可以直接将消息推送到您的会话中，以便 Claude 可以对外部事件（如 CI 结果、监控警报或聊天消息）做出反应。要启用此功能，您的服务器声明 `claude/channel` 能力，您在启动时使用 `--channels` 标志选择加入。请参阅 [频道](https://code.claude.com/docs/zh-CN/channels.md) 以使用官方支持的频道，或 [频道参考](https://code.claude.com/docs/zh-CN/channels-reference.md) 以构建您自己的。434MCP 服务器还可以将消息直接推送到您的会话中，以便 Claude 能够对 CI 结果、监控告警或聊天消息等外部事件做出反应。要启用此功能，您的服务器需声明 `claude/channel` 能力，并且您需要在启动时使用 `--channels` 标志选择加入。请参阅[频道](https://code.claude.com/docs/zh-CN/channels.md)以使用官方支持的频道，或参阅[频道参考](https://code.claude.com/docs/zh-CN/channels-reference.md)以构建您自己的频道。
435 435
436在 [v2 运行时](#mcp-client-runtimes) 上，协商 MCP 协议修订版 2026-07-28 的频道服务器无法传递频道消息，因此 Claude Code 不将其注册为频道。不支持该修订版的频道服务器会在较早的握手上连接，并像以前一样注册。436在 [v2 运行时](#mcp-client-runtimes)上，协商使用 MCP 协议修订版 2026-07-28 的频道服务器无法传递频道消息，因此 Claude Code 不会将其注册为频道。不支持该修订版的频道服务器会使用较早的握手方式连接，并像以前一样注册。
437 437
438Claude Code 默认会向 stdio 服务器询问该修订版。要将 stdio 频道服务器保持在较早的握手上，请将 [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/zh-CN/env-vars) 设置为 `legacy`，这会将所有服务器都保持在较早的握手上。438Claude Code 默认会向 stdio 服务器询问该修订版。若要让 stdio 频道服务器保持使用较早的握手方式，请将 [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/zh-CN/env-vars) 设置为 `legacy`，这会让所有服务器都保持使用较早的握手方式。
439 439
440> [!TIP]440> [!TIP]
441>441>
443>443>
444> * 使用 `-s` 或 `--scope` 标志指定配置的存储位置：444> * 使用 `-s` 或 `--scope` 标志指定配置的存储位置：
445> * `local`（默认）：仅在当前项目中对您可用445> * `local`（默认）：仅在当前项目中对您可用
446> * `project`：通过 `.mcp.json` 文件与项目中的每个人共享446> * `project`：通过 `.mcp.json` 文件与项目中的所有人共享
447> * `user`：在所有项目中对您可用447> * `user`：在所有项目中对您可用
448> * 使用 `-e` 或 `--env` 标志设置环境变量（例如 `-e KEY=value`）448> * 使用 `-e` 或 `--env` 标志设置环境变量（例如 `-e KEY=value`）
449> * `--transport` 和 `--header` 标志也接受 `-t` 和 `-H` 短形式449> * `--transport` 和 `--header` 标志也接受 `-t` 和 `-H` 简写形式
450> * 使用 `MCP_TIMEOUT` 环境变量配置 MCP 服务器启动超时（例如 `MCP_TIMEOUT=10000 claude` 设置 10 秒超时）450> * 使用 `MCP_TIMEOUT` 环境变量配置 MCP 服务器启动超时时间（例如，`MCP_TIMEOUT=10000 claude` 设置 10 秒的超时时间）
451> * 通过在该服务器的 `.mcp.json` 条目中添加 `timeout` 字段（以毫秒为单位）来设置按服务器工具执行超时，例如 `"timeout": 600000` 表示十分钟。这仅对该服务器覆盖 `MCP_TOOL_TIMEOUT` 环境变量451> * 通过在服务器的 `.mcp.json` 条目中添加以毫秒为单位的 `timeout` 字段来设置单个服务器的工具执行超时时间，例如 `"timeout": 600000` 表示十分钟。这仅对该服务器覆盖 `MCP_TOOL_TIMEOUT` 环境变量
452> * 当 MCP 工具输出超过 10,000 个 token 时，Claude Code 显示警告，默认限制输出为 25,000 个 token。要更改 token 限制，请设置 `MAX_MCP_OUTPUT_TOKENS` 环境变量，例如 `MAX_MCP_OUTPUT_TOKENS=50000`。警告阈值是固定的。除非服务器提高了某个工具自身的限制，否则超过 50,000 个字符的成功文本结果会被保存到文件中，不受此变量影响。请参阅 [MCP 输出限制和警告](#mcp-output-limits-and-warnings)452> * 当 MCP 工具输出超过 10,000 个 token 时，Claude Code 会显示警告，并默认将输出限制为 25,000 个 token。若要更改 token 限制，请设置 `MAX_MCP_OUTPUT_TOKENS` 环境变量，例如 `MAX_MCP_OUTPUT_TOKENS=50000`。警告阈值是固定的。除非服务器提高了某个工具自身的限制，否则超过 50,000 个字符的成功文本结果会保存到文件中，不受此变量影响。请参阅 [MCP 输出限制和警告](#mcp-output-limits-and-warnings)
453> * 使用 `/mcp` 与需要 OAuth 2.0 身份验证的远程服务器进行身份验证453> * 使用 `/mcp` 对需要 OAuth 2.0 身份验证的远程服务器进行身份验证
454 454
455### MCP 工具调用的时间限制455### MCP 工具调用的时间限制
456 456
457要限制 MCP 工具调用可以运行的时长：457若要限制 MCP 工具调用可以运行的时长：
458 458
459* **按服务器**：在该服务器的配置条目中添加以毫秒为单位的 `timeout` 字段459* **按服务器**：在该服务器的配置条目中添加以毫秒为单位的 `timeout` 字段
460* **跨服务器**：设置 [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/zh-CN/env-vars)460* **跨服务器**：设置 [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/zh-CN/env-vars)
461 461
462按服务器的 `timeout` 是每个工具调用的硬性墙钟时间限制，来自服务器的进度通知不会延长它。低于 1000 的值被忽略并回退到 `MCP_TOOL_TIMEOUT`，或在该变量未设置时回退到其约 28 小时的默认值。对于 HTTP、SSE 或 [claude.ai 连接器](https://code.claude.com/docs/zh-CN/mcp.md#use-mcp-servers-from-claude-ai) 服务器，还有第二个按请求计时器，覆盖每个请求直到服务器的第一个响应字节。Claude Code 将该计时器设置为三个值中最大的：60 秒、适用于服务器的工具超时和 `MCP_TIMEOUT`。未设置的 `MCP_TOOL_TIMEOUT` 的 28 小时默认值不参与该比较，低于 60 秒的值不会缩短计时器。Stdio 和 WebSocket 服务器没有按请求计时器。462按服务器设置的 `timeout` 是每次工具调用的硬性挂钟时间限制，服务器发送的进度通知不会延长它。低于 1000 的值会被忽略，并回退到 `MCP_TOOL_TIMEOUT`，或在该变量未设置时回退到其约 28 小时的默认值。对于 HTTP、SSE 或 [claude.ai 连接器](https://code.claude.com/docs/zh-CN/mcp.md#use-mcp-servers-from-claude-ai)服务器，还有第二个按请求计时的计时器，覆盖每个请求直到服务器的第一个响应字节。Claude Code 将该计时器设置为以下三个值中的最大值：60 秒、适用于该服务器的工具超时时间，以及 `MCP_TIMEOUT`。未设置 `MCP_TOOL_TIMEOUT` 时的 28 小时默认值不参与该比较，低于 60 秒的值也不会缩短该计时器。Stdio 和 WebSocket 服务器没有按请求计时的计时器。
463 463
464至少 1000 的按服务器 `timeout` 也充当下面描述的空闲超时的下限：Claude Code 永远不会早于按服务器 `timeout` 因空闲而中止该服务器的工具调用。464至少为 1000 的按服务器 `timeout` 还会作为下文所述空闲超时的下限：Claude Code 绝不会在早于按服务器 `timeout` 的时间因空闲而中止该服务器的工具调用。
465 465
466对 MCP 服务器的工具调用，如果在空闲窗口内既没有响应也没有进度通知，会以错误中止，而不是等待墙钟时间限制。空闲超时适用于除 IDE 服务器和 SDK 进程内服务器外的每种服务器类型。空闲窗口对 HTTP、SSE、WebSocket 和 [claude.ai 连接器](#use-mcp-servers-from-claude-ai) 服务器默认为五分钟，对 stdio 服务器默认为 30 分钟。466如果对 MCP 服务器的工具调用在空闲窗口期内没有发送任何响应和进度通知，则会以错误中止，而不是等待挂钟时间限制。空闲超时适用于除 IDE 服务器和 SDK 进程内服务器之外的所有服务器类型。对于 HTTP、SSE、WebSocket 和 [claude.ai 连接器](#use-mcp-servers-from-claude-ai)服务器，空闲窗口默认为五分钟；对于 stdio 服务器，默认为 30 分钟。
467 467
468设置 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/zh-CN/env-vars) 环境变量（以毫秒为单位）来更改空闲窗口，或将其设置为 `0` 以禁用检查。468以毫秒为单位设置 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/zh-CN/env-vars) 环境变量以更改空闲窗口，或将其设置为 `0` 以禁用该检查。
469 469
470这些超时限制调用可以运行多长时间，但不一定是它阻塞会话多长时间：运行超过两分钟的主对话调用会先移到后台任务。请参阅 [长工具调用的自动后台处理](#automatic-backgrounding-of-long-tool-calls)。470这些超时限制的是调用可以运行的时长，而不一定是它阻塞会话的时长：运行超过两分钟的主对话调用会先转为后台任务。请参阅[长时间工具调用的自动后台化](#automatic-backgrounding-of-long-tool-calls)。
471 471
472### 长工具调用的自动后台处理472### 长时间工具调用的自动后台化
473 473
474如果某个后台调用在 [`/tasks`](https://code.claude.com/docs/zh-CN/commands#all-commands) 中的详情视图显示 `runs on the server; survives exiting this session`，请参阅[在服务器上运行的 MCP 任务](#mcp-tasks-that-run-on-the-server)。474如果后台调用在 [`/tasks`](https://code.claude.com/docs/zh-CN/commands#all-commands) 中的详情视图显示 `runs on the server; survives exiting this session`，请参阅[在服务器上运行的 MCP 任务](#mcp-tasks-that-run-on-the-server)。
475 475
476主对话中的 MCP 工具调用在两分钟后仍在运行时会移到后台任务，而不是阻塞会话。Claude 立即收到任务 ID 并继续工作，结果在调用完成时作为任务通知到达。476主对话中的 MCP 工具调用如果在两分钟后仍在运行，会转为后台任务，而不是阻塞会话。Claude 会立即收到任务 ID 并继续工作，调用结束时结果会以任务通知的形式到达。
477 477
478任务出现在 [`/tasks`](https://code.claude.com/docs/zh-CN/commands#all-commands) 中，您也可以在其中停止它，退出会话后它不会保留。任务的条目显示服务器报告的最新进度。如果您停止任务，Claude Code 会取消调用并告知 Claude 不会有结果返回。停止并不保证服务器停止：服务器可能已经完成了部分工作，或者仍可能完成它。478该任务会出现在 [`/tasks`](https://code.claude.com/docs/zh-CN/commands#all-commands) 中，您也可以在那里停止它，并且它不会在退出会话后保留。任务条目显示服务器报告的最新进度。如果您停止该任务，Claude Code 会取消调用并告知 Claude 不会有结果。停止并不保证服务器会停止：它可能已经完成了部分工作，或者仍可能完成它。
479 479
480调用在后台运行时，每次调用的限制仍然适用：由按服务器 `timeout` 或 [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/zh-CN/env-vars) 设置的墙钟时间限制，以及由 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/zh-CN/env-vars) 设置的空闲超时。480调用在后台运行期间，每次调用的限制仍然适用：由按服务器 `timeout` 或 [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/zh-CN/env-vars) 设置的挂钟时间限制，以及由 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/zh-CN/env-vars) 设置的空闲超时。
481 481
482要更改或关闭自动后台化：482若要更改或关闭自动后台化：
483 483
484* 设置以毫秒为单位的 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/zh-CN/env-vars) 环境变量以更改阈值，或设置为 `0` 以关闭自动后台化。设置为 `0` 时，Claude 在交互式会话中也会[等待 MCP 任务](#make-claude-wait-for-the-result-of-an-mcp-task)484* 以毫秒为单位设置 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/zh-CN/env-vars) 环境变量以更改阈值，或将其设置为 `0` 以关闭自动后台化。设置为 `0` 时，Claude 在交互式会话中还会[等待 MCP 任务](#make-claude-wait-for-the-result-of-an-mcp-task)
485* 将 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/zh-CN/env-vars) 设置为 `1`，以关闭自动后台化和[后台命令](https://code.claude.com/docs/zh-CN/tools-reference.md#background-commands)485* 将 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/zh-CN/env-vars) 设置为 `1` 以关闭自动后台化和[后台命令](https://code.claude.com/docs/zh-CN/tools-reference.md#background-commands)
486 486
487某些调用永远不会移到后台：487某些调用永远不会转入后台：
488 488
489* 来自 [子代理](https://code.claude.com/docs/zh-CN/sub-agents.md) 的调用；Claude Code 仅后台处理主对话调用489* 来自[子代理](https://code.claude.com/docs/zh-CN/sub-agents.md)的调用；Claude Code 只将主对话调用转入后台
490* 对 IDE 服务器的调用490* 对 IDE 服务器的调用
491* [非交互模式](https://code.claude.com/docs/zh-CN/headless.md) 中的调用，除非 `CLAUDE_AUTO_BACKGROUND_TASKS` 设置为 `1`，因为一次性运行可能在结果到达前结束491* [非交互模式](https://code.claude.com/docs/zh-CN/headless.md)中的调用，除非 `CLAUDE_AUTO_BACKGROUND_TASKS` 设置为 `1`，因为一次性运行可能在结果到达之前就结束
492 492
493等待已打开的 [引出对话框](#respond-to-mcp-elicitation-requests) 的调用在对话框打开期间不会后台处理；服务器是在等待您的输入，而不是运行缓慢，因此 Claude Code 将移动推迟到对话框关闭。493在打开的[引导对话框](#respond-to-mcp-elicitation-requests)上等待的调用在对话框打开期间不会转入后台；服务器是在等待您的输入，而不是运行缓慢，因此 Claude Code 会将转移推迟到对话框关闭之后。
494 494
495### 在服务器上运行的 MCP 任务495### 在服务器上运行的 MCP 任务
496 496
497MCP 任务是指 MCP 服务器使用 [MCP tasks 扩展](https://modelcontextprotocol.io/extensions/tasks/overview)自行运行的长时间作业，例如报告导出或构建。服务器接受该作业后，Claude 的工具调用即返回，因此 Claude 会继续工作，除非您[让 Claude 等待](#make-claude-wait-for-the-result-of-an-mcp-task)。作业结束时，会话记录中会注明这一点，Claude 会获得结果。您可以向 Claude 询问结果。497MCP 任务是由 MCP 服务器使用 [MCP tasks 扩展](https://modelcontextprotocol.io/extensions/tasks/overview)自行运行的长时间作业，例如报告导出或构建。服务器接受作业后，Claude 的工具调用即返回，因此除非您[让 Claude 等待](#make-claude-wait-for-the-result-of-an-mcp-task)，否则 Claude 会继续工作。作业结束时，会话记录中会说明这一点，并且 Claude 会获得结果。您可以向 Claude 询问结果。
498 498
499在此期间，页脚会显示诸如 `1 MCP task` 的计数，Claude Code 会通过向服务器检查任务状态来跟踪该任务。远程服务器上的任务在您退出后会继续运行。要再次跟踪它，请[恢复同一会话](#exit-clear-or-resume-while-an-mcp-task-runs)。499与此同时，底部栏会显示诸如 `1 MCP task` 的计数，Claude Code 通过向服务器检查状态来跟踪该任务。远程服务器上的任务在您退出后仍会继续运行。若要再次跟踪它，请[恢复同一会话](#exit-clear-or-resume-while-an-mcp-task-runs)。
500 500
501> [!NOTE]501> [!NOTE]
502>502>
503> MCP 任务在 Claude Code CLI 中处于公开测试版阶段，需要 Claude Code v2.1.304 或更高版本。[调用成为 MCP 任务的条件](#requirements-for-mcp-tasks)列出了可以使用该功能的会话和服务器。503> MCP 任务在 Claude Code CLI 中处于公开测试版阶段，需要 Claude Code v2.1.304 或更高版本。[调用成为 MCP 任务的条件](#requirements-for-mcp-tasks)列出了支持它的会话和服务器。
504 504
505#### 停止 MCP 任务或获取其结果505#### 停止 MCP 任务或获取其结果
506 506
507要停止正在运行的任务，请在 [`/tasks`](https://code.claude.com/docs/zh-CN/commands#all-commands) 中选择它并按 `x`，或者让 Claude 停止它。Claude Code 会停止跟踪该任务并请求服务器取消它，但服务器仍可能完成它。请先从 `/mcp` 重新连接已断开的服务器，否则不会发出取消请求，Claude Code 会忘记该任务且无法再次跟踪它。按 `Esc` 不会停止后台任务。507若要停止正在运行的任务，请在 [`/tasks`](https://code.claude.com/docs/zh-CN/commands#all-commands) 中选择它并按 `x`，或者让 Claude 来停止。Claude Code 会停止跟踪该任务并请求服务器取消它，但服务器仍可能完成它。请先从 `/mcp` 重新连接已断开的服务器，否则取消请求不会发出，Claude Code 会遗忘该任务且无法再次跟踪它。按 `Esc` 不会停止后台任务。
508 508
509任务结束时，会话记录中会出现类似这样的一行：509任务结束时，会话记录中会出现如下一行：
510 510
511```text theme={null}511```text theme={null}
512MCP task <server task id> (<server>/<tool>) completed.512MCP task <server task id> (<server>/<tool>) completed.
513```513```
514 514
515结果会发送给 Claude，而不是写入会话记录，因此请向 Claude 询问结果。如果结果到达时 Claude 处于空闲状态，Claude 会主动开始处理它。515结果会发送给 Claude，而不会进入会话记录，因此请向 Claude 询问结果。如果结果到达时 Claude 处于空闲状态，Claude 会主动开始处理它。
516 516
517#### 回答来自 MCP 任务的问题517#### 回答来自 MCP 任务的问题
518 518
519正在运行的任务可以打开 [elicitation 对话框](#respond-to-mcp-elicitation-requests)向您请求输入。在 `/tasks` 打开期间，该对话框会保持隐藏，因此请关闭 `/tasks` 以作答。拒绝或按 `Esc` 也是对服务器的一种回答，服务器随后会决定任务是否继续。519正在运行的任务可以打开[引导对话框](#respond-to-mcp-elicitation-requests)来请求您输入。`/tasks` 打开期间，该对话框保持隐藏，因此请关闭 `/tasks` 以进行回答。拒绝或按 `Esc` 也是对服务器的一种回答，服务器随后决定任务是否继续。
520 520
521在[非交互](https://code.claude.com/docs/zh-CN/headless.md)会话中，对于请求输入的任务，Claude Code 会请求服务器取消它，而不会运行您的 [`Elicitation` hook](https://code.claude.com/docs/zh-CN/hooks#elicitation)，也不会调用 Agent SDK 的 `onElicitation` 回调。521在[非交互](https://code.claude.com/docs/zh-CN/headless.md)会话中，Claude Code 会请求服务器取消请求输入的任务，而不会运行您的 [`Elicitation` hook](https://code.claude.com/docs/zh-CN/hooks#elicitation)，也不会调用 Agent SDK 的 `onElicitation` 回调。
522 522
523#### 在 MCP 任务运行时退出、清除或恢复523#### MCP 任务运行期间退出、清除或恢复
524 524
525远程服务器上的任务在您退出后会继续运行。stdio 服务器的进程会在 Claude Code 退出时停止，尽管其任务在 `/tasks` 中显示 `runs on the server; survives exiting this session`。除非该服务器的文档说明工作会在进程结束后继续，否则请先让这些任务完成，或在 `/tasks` 中停止它们。525远程服务器上的任务在您退出后仍会继续运行。stdio 服务器的进程会在 Claude Code 退出时停止，尽管其任务在 `/tasks` 中显示 `runs on the server; survives exiting this session`。除非该服务器的文档说明工作会在进程结束后继续，否则请先让这些任务完成，或在 `/tasks` 中停止它们。
526 526
527| 情况 | 任务会怎样 | 您可以做什么 |527| 情况 | 任务会怎样 | 您可以做什么 |
528| - | - | - |528| - | - | - |
529| 您运行 `/clear` 或 `/branch`，或 `/resume` 另一个会话 | 在 Claude Code 保持打开期间，结果会送达您当前的对话 | 退出后，使用 `claude --resume` 恢复任务启动时所在的会话 |529| 您运行 `/clear` 或 `/branch`，或 `/resume` 到另一个会话 | 只要 Claude Code 保持打开，结果就会到达您当前的对话中 | 退出后，使用 `claude --resume` 恢复任务启动时所在的会话 |
530| 您退出 Claude Code | 任何退出选项都不会取消远程服务器的任务，即使退出对话框将其列在 `The following will stop when you exit:` 下 | 先在 `/tasks` 中停止它，或稍后恢复同一会话 |530| 您退出 Claude Code | 没有任何退出选项会取消远程服务器的任务，即使退出对话框将其列在 `The following will stop when you exit:` 下 | 先在 `/tasks` 中停止它，或稍后恢复同一会话 |
531| 您以交互方式返回任务所在的会话：`claude --resume`、`claude --continue` 或 `/resume` | 服务器连接后，Claude Code 会再次跟踪该任务；如果任务在此期间已完成且服务器仍知道它，Claude 会获得结果 | 保持服务器的名称和连接设置不变 |531| 您以交互方式返回任务所在的会话：`claude --resume`、`claude --continue` 或 `/resume` | 服务器连接后，Claude Code 会再次跟踪该任务；如果任务在此期间已完成且服务器仍记得它，Claude 会获得结果 | 保持服务器的名称和连接设置不变 |
532| 您在一次性 `claude -p "<prompt>"` 运行中使用 `--resume` 或 `--continue` 恢复任务所在的会话 | 该运行不会跟踪该任务 | 以交互方式恢复，或使用 `--input-format stream-json` 恢复 |532| 您在一次性 `claude -p "<prompt>"` 运行中使用 `--resume` 或 `--continue` 恢复任务所在的会话 | 该运行不会跟踪该任务 | 以交互方式恢复，或使用 `--input-format stream-json` 恢复 |
533| 您启动新会话或使用 `--fork-session` | 新会话不会跟踪该任务 | 恢复启动该任务的会话 |533| 您启动新会话或使用 `--fork-session` | 新会话不会跟踪该任务 | 恢复启动该任务的会话 |
534 534
537只有当以下所有条件都满足时，工具调用才会成为 MCP 任务：537只有当以下所有条件都满足时，工具调用才会成为 MCP 任务：
538 538
539* 服务器支持任务539* 服务器支持任务
540* 服务器是以[协议修订版 2026-07-28](#mcp-client-runtimes) 连接的 HTTP、stdio 或 claude.ai 连接器服务器。设置 [`MCP_SDK_GENERATION=v1` 或 `MCP_PROTOCOL_NEGOTIATION=legacy`](https://code.claude.com/docs/zh-CN/env-vars) 会排除这一情况540* 服务器是以[协议修订版 2026-07-28](#mcp-client-runtimes) 连接的 HTTP、stdio 或 claude.ai 连接器服务器。设置 [`MCP_SDK_GENERATION=v1` 或 `MCP_PROTOCOL_NEGOTIATION=legacy`](https://code.claude.com/docs/zh-CN/env-vars) 会排除这种情况
541* 会话会[获取功能标志](https://code.claude.com/docs/zh-CN/env-vars.md#features-that-need-feature-flag-fetching)，因此不能在 Amazon Bedrock 等第三方提供商上，也不能关闭遥测或标志获取541* 会话[获取功能标志](https://code.claude.com/docs/zh-CN/env-vars.md#features-that-need-feature-flag-fetching)，因此不能是 Amazon Bedrock 等第三方提供商，也不能关闭遥测或标志获取
542* Anthropic 已为您的会话类型启用了 MCP 任务。在 v2.1.304 或更高版本上，这包括终端 CLI 会话、[Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 会话和 [GitHub Actions](https://code.claude.com/docs/zh-CN/github-actions.md) 运行。其他使用入口（例如 [VS Code 扩展](https://code.claude.com/docs/zh-CN/vs-code.md)和[桌面应用](https://code.claude.com/docs/zh-CN/desktop.md)）没有 MCP 任务542* Anthropic 已为您这类会话启用 MCP 任务。在 v2.1.304 或更高版本上，这涵盖终端 CLI 会话、[Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 会话和 [GitHub Actions](https://code.claude.com/docs/zh-CN/github-actions.md) 运行。其他使用入口（例如 [VS Code 扩展](https://code.claude.com/docs/zh-CN/vs-code.md)和[桌面应用](https://code.claude.com/docs/zh-CN/desktop.md)）没有 MCP 任务
543* 调用来自主对话，而不是来自[子代理](https://code.claude.com/docs/zh-CN/sub-agents.md)543* 调用来自主对话，而不是来自[子代理](https://code.claude.com/docs/zh-CN/sub-agents.md)
544* 会话是交互式的，或者 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 会话或读取 `--input-format stream-json` 的 `claude -p` 运行满足：544* 会话是交互式的，或者 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 会话或读取 `--input-format stream-json` 的 `claude -p` 运行满足：
545 * [`CLAUDE_AUTO_BACKGROUND_TASKS`](https://code.claude.com/docs/zh-CN/env-vars) 为 `1`545 * [`CLAUDE_AUTO_BACKGROUND_TASKS`](https://code.claude.com/docs/zh-CN/env-vars) 为 `1`
552 552
553#### MCP 任务的状态消息553#### MCP 任务的状态消息
554 554
555这些消息出现在任务的 `/tasks` 条目或其结束时的会话记录行中，表示 Claude Code 无法连接到服务器或任务。当 `/tasks` 中显示其中一条消息时，作业可能仍在运行：Claude Code 不会干预它并会继续检查。`300s` 消息和配置相关消息即使在恢复联系后也会保留在条目上。555这些消息出现在任务的 `/tasks` 条目或其结束时的会话记录行中，表示 Claude Code 无法联系到服务器或该任务。当其中某条消息显示在 `/tasks` 中时，作业可能仍在运行：Claude Code 不会干预它，并会持续检查。`300s` 消息和配置相关消息即使在恢复联系后也会保留在条目上。
556 556
557| 消息 | 发生了什么 | 您可以做什么 |557| 消息 | 发生了什么 | 您可以做什么 |
558| - | - | - |558| - | - | - |
559| `reconnecting…` | 自恢复以来服务器尚未应答，或状态检查没有得到应答 | 如果一直显示，请从 `/mcp` 重新连接 |559| `reconnecting…` | 自恢复以来服务器尚未应答，或状态检查没有得到应答 | 如果一直显示，请从 `/mcp` 重新连接 |
560| `needs a sign-in to <server>` | 服务器拒绝了状态检查 | 从 `/mcp` 登录 |560| `needs a sign-in to <server>` | 服务器拒绝了状态检查 | 从 `/mcp` 登录 |
561| `status requests come back with errors; retrying…` | 服务器或其前面的代理以错误应答状态检查 | 等待 Claude Code 重试 |561| `status requests come back with errors; retrying…` | 服务器或其前面的代理以错误应答状态检查 | 在 Claude Code 重试期间等待 |
562| `server '<name>' did not reconnect within 300s` | 五分钟内没有得到应答的检查，例如连接中断或服务器被禁用 | 从 `/mcp` 重新连接 |562| `server '<name>' did not reconnect within 300s` | 五分钟内没有得到应答的检查，例如连接中断或服务器被禁用 | 从 `/mcp` 重新连接 |
563| `server '<name>' asked for a sign-in, and none was accepted within 300s` | 五分钟后服务器仍要求登录 | 从 `/mcp` 登录 |563| `server '<name>' asked for a sign-in, and none was accepted within 300s` | 五分钟后服务器仍要求登录 | 从 `/mcp` 登录 |
564| `status requests to server '<name>' came back with errors, and none succeeded in 300s` | 五分钟内都是错误应答 | 检查服务器自身的健康状况或日志 |564| `status requests to server '<name>' came back with errors, and none succeeded in 300s` | 五分钟内都是错误应答 | 检查服务器自身的健康状况或日志 |
565| `server '<name>' is not configured in this session; the task may still be running on it` | 会话中没有该名称的服务器，例如它已被移除、重命名或未包含在 `--mcp-config` 中，或者某个 claude.ai 连接器仍在加载 | 以相同名称恢复该服务器，然后再次恢复会话。对于正在加载的连接器，无需操作：连接器出现后 Claude Code 会跟踪该任务 |565| `server '<name>' is not configured in this session; the task may still be running on it` | 会话中没有该名称的服务器，例如它被移除、重命名或未包含在 `--mcp-config` 中，或者某个 claude.ai 连接器仍在加载 | 以相同名称恢复该服务器，然后再次恢复会话。对于正在加载的连接器，无需操作：它出现后 Claude Code 会跟踪该任务 |
566| 以 `server '<name>' was reconfigured to a different transport since this task was created` 开头的消息 | 存在该名称的服务器，但其连接设置自任务开始后已更改，例如 URL、command、args、env、headers 或 timeout | 恢复之前的设置，然后再次恢复会话 |566| 以 `server '<name>' was reconfigured to a different transport since this task was created` 开头的消息 | 存在该名称的服务器，但其连接设置自任务开始以来已更改，例如其 URL、command、args、env、headers 或 timeout | 恢复先前的设置，然后再次恢复会话 |
567| `the server rejected this task's id; asking again…` | 服务器表示不认识该任务 ID。Claude Code 会继续询问最多五分钟 | 等待：如果服务器再次识别该 ID，消息会消失，否则会出现 `outcome unknown.` 行 |567| `the server rejected this task's id; asking again…` | 服务器表示不认识该任务 ID。Claude Code 会持续询问最多五分钟 | 等待：如果服务器再次识别该 ID，消息会清除；否则随后会出现 `outcome unknown.` 行 |
568| 以 `outcome unknown.` 结尾的会话记录行，其中一种形式为 `expired on the server: outcome unknown.` | 服务器拒绝了该 ID 或以其他永久性错误拒绝，Claude Code 已停止跟踪该任务 | 第二次调用可能会重复执行该工作。再次调用该工具之前，请从服务器了解已完成的内容，例如让 Claude 使用该服务器的其他工具 |568| 以 `outcome unknown.` 结尾的会话记录行，其中一种形式为 `expired on the server: outcome unknown.` | 服务器拒绝了该 ID 或以其他永久性错误拒绝，Claude Code 已停止跟踪该任务 | 第二次调用可能会重复执行工作。在再次调用该工具之前，请从服务器了解已完成了什么，例如让 Claude 使用该服务器的其他工具 |
569 569
570#### MCP 任务的时间限制570#### MCP 任务的时间限制
571 571
572默认情况下，后台任务没有 Claude Code 时间限制。[工具调用时间限制](#time-limits-on-mcp-tool-calls)（包括挂钟时间限制和空闲超时）在服务器以任务应答该调用之前适用。如果您[让 Claude 等待](#make-claude-wait-for-the-result-of-an-mcp-task)，这些限制会在整个任务期间适用。得到应答的状态检查会计为空闲超时中的活动。572默认情况下，后台任务没有 Claude Code 时间限制。[工具调用时间限制](#time-limits-on-mcp-tool-calls)（包括挂钟时间限制和空闲超时）在服务器以任务应答调用之前适用。如果您[让 Claude 等待](#make-claude-wait-for-the-result-of-an-mcp-task)，这些限制会适用于整个任务。得到应答的状态检查会计为空闲超时的活动。
573 573
574#### 让 Claude 等待 MCP 任务的结果574#### 让 Claude 等待 MCP 任务的结果
575 575
576要在交互式会话中让 Claude 等待任务的结果，请设置以下两个环境变量之一，例如在 [`settings.json`](https://code.claude.com/docs/zh-CN/settings) 的 `env` 块中：576若要让 Claude 在交互式会话中等待任务结果，请设置以下两个环境变量之一，例如在 [`settings.json`](https://code.claude.com/docs/zh-CN/settings) 的 `env` 块中设置：
577 577
578* **[`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/zh-CN/env-vars) 设置为 `0`**：Claude 会等待每个 MCP 工具调用直到调用结束578* **[`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/zh-CN/env-vars) 设置为 `0`**：Claude 会等待每个 MCP 工具调用直到调用结束
579* **[`CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`](https://code.claude.com/docs/zh-CN/env-vars) 设置为 `1`**：Claude 会等待任务的结果。当[自动后台化](#automatic-backgrounding-of-long-tool-calls)开启时，它默认会在两分钟后转移该调用，因此短任务会就地完成，长任务不会阻塞您。被转移的调用是普通后台调用，而不是 MCP 任务。它不会在退出会话后保留579* **[`CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`](https://code.claude.com/docs/zh-CN/env-vars) 设置为 `1`**：Claude 会等待任务的结果。当[自动后台化](#automatic-backgrounding-of-long-tool-calls)开启时，默认会在两分钟后转移该调用，因此短任务会就地完成，而长任务不会阻塞您。被转移的调用是普通后台调用，而不是 MCP 任务。它不会在退出会话后保留
580 580
581Claude 等待期间，按 `Esc` 或达到[挂钟时间限制或空闲超时](#time-limits-on-mcp-tasks)会结束该调用，Claude Code 会请求服务器取消该任务。581在 Claude 等待期间，按 `Esc` 或达到[挂钟时间限制或空闲超时](#time-limits-on-mcp-tasks)会结束调用，并且 Claude Code 会请求服务器取消该任务。
582 582
583如果您将 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 设置为 `1` 或以 [bare 模式](https://code.claude.com/docs/zh-CN/headless.md#start-faster-with-bare-mode)启动，仅凭这一点并不会让 Claude 等待 MCP 任务。以下示例将 `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` 设置为 `0`，因此 Claude 会等待每个 MCP 工具调用：583如果您将 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 设置为 `1` 或以 [bare 模式](https://code.claude.com/docs/zh-CN/headless.md#start-faster-with-bare-mode)启动，仅凭这一点并不会让 Claude 等待 MCP 任务。以下示例将 `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` 设置为 `0`，因此 Claude 会等待每个 MCP 工具调用：
584 584
590}590}
591```591```
592 592
593### 面向服务器开发者的 MCP 任务593### 面向服务器作者的 MCP 任务
594 594
595如果您构建 MCP 服务器，可以用任务来应答长时间运行的 `tools/call`。[MCP tasks 扩展](https://modelcontextprotocol.io/extensions/tasks/overview)定义了您要发送的消息。在[协议修订版 2026-07-28](#mcp-client-runtimes) 连接上，每个请求都会在 `params._meta["io.modelcontextprotocol/clientCapabilities"]` 中携带 Claude Code 的客户端能力，其中 `extensions` 下包含 `"io.modelcontextprotocol/tasks": {}`。[无法成为任务](#requirements-for-mcp-tasks)的 `tools/call` 请求会省略该扩展。595如果您构建 MCP 服务器，可以用任务来应答长时间运行的 `tools/call`。[MCP tasks 扩展](https://modelcontextprotocol.io/extensions/tasks/overview)定义了您需要发送的消息。在[协议修订版 2026-07-28](#mcp-client-runtimes) 连接上，每个请求都会在 `params._meta["io.modelcontextprotocol/clientCapabilities"]` 处携带 Claude Code 的客户端能力，其中 `extensions` 下包含 `"io.modelcontextprotocol/tasks": {}`。[无法成为任务](#requirements-for-mcp-tasks)的 `tools/call` 请求会省略该扩展。
596 596
597#### 以任务应答调用597#### 以任务应答调用
598 598
599只有在请求携带该扩展时才用任务应答，否则调用会以工具错误 `Unsupported result type 'task' for tools/call` 失败。如果您的应答没有 `taskId` 或没有有效的 `status`，调用也会以同样的方式失败。任务对象是您的 `tools/call` 响应的 JSON-RPC `result`，不需要 `content` 数组，此处还包含可选的 `statusMessage` 和 `pollIntervalMs`：599仅当请求携带该扩展时才以任务应答，否则调用会以工具错误 `Unsupported result type 'task' for tools/call` 失败。如果您的应答没有 `taskId` 或没有有效的 `status`，调用也会以同样方式失败。任务对象是您 `tools/call` 响应的 JSON-RPC `result`，不需要 `content` 数组，此处还包含可选的 `statusMessage` 和 `pollIntervalMs`：
600 600
601```json theme={null}601```json theme={null}
602{602{
613 613
614| 字段 | Claude Code 如何处理 |614| 字段 | Claude Code 如何处理 |
615| - | - |615| - | - |
616| `resultType` | 设置为 `"task"` 以将该应答标记为任务。如果没有它，Claude Code 会将该应答视为普通结果 |616| `resultType` | 将其设置为 `"task"` 以将应答标记为任务。缺少它时，Claude Code 会将应答读取为普通结果 |
617| `taskId` | 必需。最多 128 个不含空格的可打印 ASCII 字符，否则 Claude 会收到以 `MCP server "<name>" returned a malformed task handle for tool "<tool>"` 开头的工具错误。请确保该 ID 在不同连接间都能被应答，因为恢复后 Claude Code 会在新连接上询问它 |617| `taskId` | 必需。最多 128 个不含空格的可打印 ASCII 字符，否则 Claude 会收到以 `MCP server "<name>" returned a malformed task handle for tool "<tool>"` 开头的工具错误。请确保该 ID 可以跨连接应答，因为恢复后 Claude Code 会在新连接上询问它 |
618| `status` | 必需。取值为 `working`、`input_required`、`completed`、`failed` 或 `cancelled` 之一。其他值会产生 `Unsupported result type` 错误 |618| `status` | 必需。取值为 `working`、`input_required`、`completed`、`failed` 或 `cancelled` 之一。其他值会导致 `Unsupported result type` 错误 |
619| `createdAt`、`lastUpdatedAt`、`ttlMs` | 任务扩展要求提供，`ttlMs` 可以为 `null`。Claude Code 不会因为任务的 `ttlMs` 已过而丢弃该任务 |619| `createdAt`、`lastUpdatedAt`、`ttlMs` | tasks 扩展要求提供，`ttlMs` 可以为 `null`。Claude Code 不会因为任务的 `ttlMs` 已过而丢弃该任务 |
620| `pollIntervalMs` | 可选。`tasks/get` 请求之间的毫秒数，限制在 250 到 30000 之间。当该字段缺失或为 `null` 时，Claude Code 使用 2000，并会从每个 `tasks/get` 响应中重新读取该值 |620| `pollIntervalMs` | 可选。`tasks/get` 请求之间的毫秒数，限制在 250 到 30000 之间。字段缺失或为 `null` 时，Claude Code 使用 2000，并从每个 `tasks/get` 响应中重新读取该值 |
621| `statusMessage` | 可选。`/tasks` 显示的是您最新的 `tasks/get` 响应中的值，而不是这第一个应答中的值，省略该字段的响应会清除它。[来自 Claude Code 的状态消息](#status-messages-on-an-mcp-task)可能会取代它 |621| `statusMessage` | 可选。`/tasks` 显示的是您最新 `tasks/get` 响应中的值，而不是这第一个值，省略该字段的响应会清除它。[来自 Claude Code 的状态消息](#status-messages-on-an-mcp-task)可能会取代它 |
622 622
623Claude Code 接受省略 `createdAt`、`lastUpdatedAt` 或 `ttlMs`，或将 `pollIntervalMs` 设置为 `null` 的任务应答。在 v2.1.317 之前，调用会改为以 `Unsupported result type` 错误失败。要同时兼容这些版本，请发送任务扩展要求的三个字段，并将 `pollIntervalMs` 作为数字发送或完全不发送。623Claude Code 接受省略 `createdAt`、`lastUpdatedAt` 或 `ttlMs`，或将 `pollIntervalMs` 设置为 `null` 的任务应答。在 v2.1.317 之前，此类调用会以 `Unsupported result type` 错误失败。若要同时兼容这些版本，请发送 tasks 扩展要求的三个字段，并将 `pollIntervalMs` 作为数字发送或完全不发送。
624 624
625在 HTTP 或 claude.ai 连接器服务器上，任务应答必须在[按请求的计时器](#time-limits-on-mcp-tool-calls)内开始，因此请先接受作业并应答，然后再执行工作。625在 HTTP 或 claude.ai 连接器服务器上，任务应答必须在[按请求计时的计时器](#time-limits-on-mcp-tool-calls)内开始，因此请先接受作业并应答，然后再执行工作。
626 626
627#### 报告状态、结果和问题627#### 报告状态、结果和问题
628 628
629在任务应答之后，Claude Code 会立即发送带有 `{ "taskId": ... }` 的 `tasks/get`，然后每个轮询间隔重复一次。tasks 扩展要求您的响应携带 `"resultType": "complete"`，以及 `taskId`、`status`、`createdAt`、`lastUpdatedAt` 和 `ttlMs`。`ttlMs` 可以为 `null`，`statusMessage` 和 `pollIntervalMs` 是可选的。以下示例报告构建已完成：629任务应答之后，Claude Code 会立即发送带有 `{ "taskId": ... }` 的 `tasks/get`，然后每个轮询间隔重复一次。tasks 扩展要求您的响应携带 `"resultType": "complete"` 以及 `taskId`、`status`、`createdAt`、`lastUpdatedAt` 和 `ttlMs`。`ttlMs` 可以为 `null`，`statusMessage` 和 `pollIntervalMs` 是可选的。以下示例报告构建已完成：
630 630
631```json theme={null}631```json theme={null}
632{632{
645| 状态、方法或响应 | Claude Code 如何处理 |645| 状态、方法或响应 | Claude Code 如何处理 |
646| - | - |646| - | - |
647| `working` | 继续轮询 |647| `working` | 继续轮询 |
648| `completed` | 将顶层 `result` 对象中的普通 `tools/call` 结果交给 Claude。其中的 `isError: true` 会被报告为失败 |648| `completed` | 将顶层 `result` 对象中的常规 `tools/call` 结果提供给 Claude。其中的 `isError: true` 会被报告为失败 |
649| `failed` | 将顶层 `error` 对象 `{ code, message, data }` 的 `message` 告知 Claude，tasks 扩展要求失败的任务包含该对象。如果没有该 `message`，Claude 会改为收到 `statusMessage`，否则收到 `Task failed` |649| `failed` | 将顶层 `error` 对象 `{ code, message, data }` 的 `message` 告知 Claude，tasks 扩展要求失败的任务提供该对象。如果缺少该 `message`，Claude 会收到 `statusMessage`，否则收到 `Task failed` |
650| `cancelled` | 将 `statusMessage` 告知 Claude，否则告知 `Task was cancelled by the server` |650| `cancelled` | 将 `statusMessage` 告知 Claude，否则告知 `Task was cancelled by the server` |
651| `input_required` | 读取 `inputRequests`，这是一个将您选择的键映射到 `{ method, params }` 的对象。Claude Code 会通过带有 `{ taskId, inputResponses }` 的 `tasks/update` 对每个键应答一次，其中 `inputResponses` 将相同的键映射到该请求的结果。每个任务超过 16 个的键会被忽略 |651| `input_required` | 读取 `inputRequests`，这是一个将您选择的键映射到 `{ method, params }` 的对象。Claude Code 通过带有 `{ taskId, inputResponses }` 的 `tasks/update` 对每个键应答一次，其中 `inputResponses` 将相同的键映射到该请求的结果。每个任务超过 16 个的键会被忽略 |
652| `inputRequests` 中的方法 | `elicitation/create` 仅在交互式终端会话中处理，`roots/list` 在所有地方都会处理。当 Claude Code 无法处理某个请求时，它会请求服务器取消该任务 |652| `inputRequests` 中的方法 | `elicitation/create` 仅在交互式终端会话中提供，`roots/list` 在所有场景中提供。当 Claude Code 无法处理某个请求时，它会请求服务器取消该任务 |
653| 其他 `status` 值 | Claude Code 会请求服务器取消该任务，并将其作为失败报告给 Claude |653| 其他 `status` 值 | Claude Code 请求服务器取消该任务，并将其作为失败报告给 Claude |
654| JSON-RPC 错误 `-32602` | 视为未知的任务 ID。对于后台任务，Claude Code 会继续询问最多五分钟，然后将结果作为未知报告给 Claude |654| JSON-RPC 错误 `-32602` | 被读取为未知任务 ID。对于后台任务，Claude Code 会持续询问最多五分钟，然后将结果作为未知报告给 Claude |
655| `tasks/cancel` | 例如，在服务器已连接时 Claude 或用户停止该任务时发送。退出时不发送 |655| `tasks/cancel` | 例如在服务器已连接时 Claude 或用户停止任务时发送。退出时不发送 |
656| `tasks/result`、`tasks/list`、`notifications/tasks` | 不使用，因此请将结果放在您的 `tasks/get` 响应中 |656| `tasks/result`、`tasks/list`、`notifications/tasks` | 不使用，因此请将结果放在您的 `tasks/get` 响应中 |
657 657
658### 插件提供的 MCP 服务器658### 插件提供的 MCP 服务器
659 659
660[插件](https://code.claude.com/docs/zh-CN/plugins/overview.md) 可以捆绑 MCP 服务器，在您启用插件时提供工具和集成。660[插件](https://code.claude.com/docs/zh-CN/plugins/overview.md)可以捆绑 MCP 服务器，在您启用插件时提供工具和集成。
661 661
662**插件 MCP 服务器如何工作**：662**插件 MCP 服务器的工作原理**：
663 663
664* 插件在插件根目录的 `.mcp.json` 中或内联在 `plugin.json` 中定义 MCP 服务器664* 插件在插件根目录的 `.mcp.json` 中定义 MCP 服务器，或在 `plugin.json` 中内联定义
665* 当您启用插件时，Claude Code 自动启动其 MCP 服务器665* 启用插件时，Claude Code 会自动启动其 MCP 服务器
666* Claude Code 将插件 MCP 工具与手动配置的 MCP 工具一起提供666* Claude Code 会将插件 MCP 工具与手动配置的 MCP 工具一并提供
667* 您通过安装或卸载插件来添加和删除插件服务器，而不是使用 `/mcp` 命令。您仍然可以在 `/mcp` 中 [切换已安装的插件服务器关闭](#disable-a-server-without-removing-it)，这会停止 Claude Code 连接到它而不删除插件667* 插件服务器通过安装或卸载插件来添加和移除，而不是通过 `/mcp` 命令。您仍然可以在 `/mcp` 中[关闭已安装的插件服务器](#disable-a-server-without-removing-it)，这会让 Claude Code 停止连接该服务器，而不会移除插件
668 668
669**示例插件 MCP 配置**：669**插件 MCP 配置示例**：
670 670
671在插件根目录的 `.mcp.json` 中：671在插件根目录的 `.mcp.json` 中：
672 672
684}684}
685```685```
686 686
687或内联在 `plugin.json` 中：687或在 `plugin.json` 中内联：
688 688
689```json theme={null}689```json theme={null}
690{690{
700 700
701**插件 MCP 功能**：701**插件 MCP 功能**：
702 702
703* **自动生命周期**：服务器在这些时间点连接和断开：703* **自动生命周期**：服务器在以下时间点连接和断开：
704 * 在会话启动时，Claude Code 自动连接已启用插件的服务器。在 `/mcp` 中，您之前使用过的远程（HTTP 或 SSE）插件服务器可能改为显示 [`cached` 状态](#server-status-detail)；Claude Code 在 Claude 首次调用其工具之一时连接它。当 stdio 插件服务器的连接在不到 15 分钟前失败时，Claude Code 会 [跳过该连接](https://code.claude.com/docs/zh-CN/errors.md#skipping-connection-recent-failure-cached)704 * 会话启动时，Claude Code 会自动连接已启用插件的服务器。在 `/mcp` 中，您以前使用过的远程（HTTP 或 SSE）插件服务器可能会显示 [`cached` 状态](#server-status-detail)；Claude Code 会在 Claude 首次调用其某个工具时连接它。如果 stdio 插件服务器的连接在不到 15 分钟前失败过，Claude Code 会[跳过该连接](https://code.claude.com/docs/zh-CN/errors.md#skipping-connection-recent-failure-cached)
705 * 如果您在会话期间启用或禁用插件，Claude Code 在更改生效时连接或断开其 MCP 服务器。[在不重新启动的情况下应用插件更改](https://code.claude.com/docs/zh-CN/plugins/cli-reference.md#reload-plugins) 说明了生效时间。在没有交互式终端的会话中，`/reload-plugins` 不连接或断开插件 MCP 服务器；这些更改在您的下一个会话中生效705 * 如果您在会话期间启用或禁用插件，Claude Code 会在更改生效时连接或断开其 MCP 服务器。[无需重启即可应用插件更改](https://code.claude.com/docs/zh-CN/plugins/cli-reference.md#reload-plugins)说明了更改何时生效。在没有交互式终端的会话中，`/reload-plugins` 不会连接或断开插件 MCP 服务器；这些更改将在您的下一个会话中生效
706 * 当您重新加载时，Claude Code 保留配置未更改的插件服务器的实时连接，当您从 Agent SDK [替换会话的 MCP 服务器列表](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#mcpsetserversresult) 而未列出它们时也是如此706 * 重新加载时，Claude Code 会保留配置未更改的插件服务器的活动连接；当您从 Agent SDK [替换会话的 MCP 服务器列表](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#mcpsetserversresult)而未指明这些服务器时，也会这样处理
707 * 当您在 v2.1.246 或更高版本上 [使用 `/cd` 移动会话](https://code.claude.com/docs/zh-CN/permissions#move-the-session-to-another-directory) 时，Claude Code 连接新目录的设置所启用插件的服务器，并断开不再启用的插件的服务器，因此您无需在移动后运行 `/reload-plugins`707 * 在 v2.1.246 或更高版本中，当您[使用 `/cd` 移动会话](https://code.claude.com/docs/zh-CN/permissions#move-the-session-to-another-directory)时，Claude Code 会连接新目录的设置所启用的插件的服务器，并断开不再启用的插件的服务器，因此移动后无需运行 `/reload-plugins`
708 * 在 [云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md) 中，对尚未连接的插件服务器的 MCP 调用（例如空闲会话唤醒后）会按需启动服务器并等待它连接708 * 在[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)中，对尚未连接的插件服务器发起的 MCP 调用（例如在空闲会话刚唤醒后）会按需启动该服务器并等待其连接
709* **路径占位符**：`${CLAUDE_PLUGIN_ROOT}` 解析为插件的安装目录，`${CLAUDE_PLUGIN_DATA}` 解析为其 [持久状态](https://code.claude.com/docs/zh-CN/plugins/components.md#path-variables-and-persistent-data) 目录，`${CLAUDE_PROJECT_DIR}` 解析为稳定的项目根目录。替换适用于：709* **路径占位符**：`${CLAUDE_PLUGIN_ROOT}` 解析为插件的安装目录，`${CLAUDE_PLUGIN_DATA}` 解析为其[持久状态](https://code.claude.com/docs/zh-CN/plugins/components.md#path-variables-and-persistent-data)目录，`${CLAUDE_PROJECT_DIR}` 解析为稳定的项目根目录。替换适用于：
710 * `stdio` 服务器：`command`、`args`、`env`710 * `stdio` 服务器：`command`、`args`、`env`
711 * `http`、`sse` 和 `ws` 服务器：`url`、`headers` 和 `headersHelper`711 * `http`、`sse` 和 `ws` 服务器：`url`、`headers` 和 `headersHelper`
712* **用户环境访问**：访问与手动配置的服务器相同的环境变量712* **用户环境访问**：可访问与手动配置的服务器相同的环境变量
713* **多种传输类型**：支持 stdio、SSE、HTTP 和 WebSocket 传输，尽管传输支持可能因服务器而异713* **多种传输类型**：支持 stdio、SSE、HTTP 和 WebSocket 传输，但传输支持可能因服务器而异
714 714
715插件服务器在 `/mcp` 中出现，并带有表明它们来自插件的指示器。715插件服务器会在 `/mcp` 中显示，并带有表明其来自插件的标识。
716 716
717`claude mcp get` 会隐藏为插件的 stdio 或 WebSocket 服务器配置的值，因为这些值可能携带凭据：717`claude mcp get` 会隐藏为插件的 stdio 或 WebSocket 服务器配置的值，因为这些值可能包含凭据：
718 718
719* **stdio 服务器**：它打印 `Command: stdio`、空的 `Args:` 行，并将每个环境变量显示为 `NAME=[REDACTED]`719* **stdio 服务器**：输出 `Command: stdio`、一个空的 `Args:` 行，并将每个环境变量显示为 `NAME=[REDACTED]`
720* **WebSocket 服务器**：它打印 `URL: ws`，并将每个标头显示为 `<name>: [REDACTED]`，`claude mcp list` 则显示 `ws` 来代替 URL720* **WebSocket 服务器**：输出 `URL: ws`，并将每个标头显示为 `<name>: [REDACTED]`，而 `claude mcp list` 会显示 `ws` 来代替 URL
721 721
722要查看插件配置了什么，请 [在磁盘上找到插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#find-plugins-on-disk) 并阅读其 `.mcp.json` 或 `plugin.json`。722要查看插件配置的内容，请[在磁盘上找到插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#find-plugins-on-disk)并阅读其 `.mcp.json` 或 `plugin.json`。
723 723
724**插件 MCP 工具名称**：724**插件 MCP 工具名称**：
725 725
726来自插件捆绑的 MCP 服务器的工具在其可调用名称中包含插件名称和服务器键。完整形式是 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`，其中 `A-Z`、`a-z`、`0-9`、`_` 和 `-` 之外的任何字符都被替换为 `_`。对于名为 `my-plugin` 的插件中捆绑的 `database-tools` 服务器，`query` 工具的可调用名称为：726来自插件捆绑的 MCP 服务器的工具，其可调用名称中同时包含插件名称和服务器键。完整形式为 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`，其中 `A-Z`、`a-z`、`0-9`、`_` 和 `-` 之外的任何字符都会被替换为 `_`。对于捆绑在名为 `my-plugin` 的插件中的 `database-tools` 服务器，`query` 工具的可调用名称为：
727 727
728```728```
729mcp__plugin_my-plugin_database-tools__query729mcp__plugin_my-plugin_database-tools__query
730```730```
731 731
732在 [权限规则](https://code.claude.com/docs/zh-CN/permissions.md)、skill 的 `allowed-tools` 列表、[子代理的 `tools` 字段](https://code.claude.com/docs/zh-CN/sub-agents#available-tools) 或 [hook 匹配器](https://code.claude.com/docs/zh-CN/hooks.md#match-mcp-tools) 中引用工具时使用此完整名称。针对裸服务器键编写的 hook 匹配器（例如 `mcp__database-tools__.*`）永远不会为插件捆绑的服务器触发。732在[权限规则](https://code.claude.com/docs/zh-CN/permissions.md)、skill 的 `allowed-tools` 列表、[子代理的 `tools` 字段](https://code.claude.com/docs/zh-CN/sub-agents#available-tools)或 [hook 匹配器](https://code.claude.com/docs/zh-CN/hooks.md#match-mcp-tools)中引用该工具时，请使用此完整名称。针对裸服务器键编写的 hook 匹配器（例如 `mcp__database-tools__.*`）永远不会对插件捆绑的服务器触发。
733 733
734服务器本身以限定名称 `plugin:<plugin-name>:<server-name>` 注册，例如 `plugin:my-plugin:database-tools`。在需要配置的服务器名称的地方使用该名称，例如 [`mcp_tool` hook 的 `server` 字段](https://code.claude.com/docs/zh-CN/hooks#mcp-tool-hook-fields)。734服务器本身以限定名称 `plugin:<plugin-name>:<server-name>` 注册，例如 `plugin:my-plugin:database-tools`。在需要已配置服务器名称的地方使用该名称，例如 [`mcp_tool` hook 的 `server` 字段](https://code.claude.com/docs/zh-CN/hooks#mcp-tool-hook-fields)。
735 735
736有关使用插件捆绑 MCP 服务器的详细信息，请参阅 [插件组件参考](https://code.claude.com/docs/zh-CN/plugins/components.md#mcp-servers)。736有关在插件中捆绑 MCP 服务器的详细信息，请参阅[插件组件参考](https://code.claude.com/docs/zh-CN/plugins/components.md#mcp-servers)。
737 737
738## MCP 安装作用域738## MCP 安装作用域
739 739
1800* **Claude Opus 4.5、Sonnet 4.5、Haiku 4.5 及更高版本**：工具搜索默认开启，与 Anthropic API 上相同。1800* **Claude Opus 4.5、Sonnet 4.5、Haiku 4.5 及更高版本**：工具搜索默认开启，与 Anthropic API 上相同。
1801* **早期 Agent Platform 模型**：Claude Code 预先加载所有 MCP 工具，因为它们的服务堆栈拒绝所需的 beta 标头。`ENABLE_TOOL_SEARCH=true` 不会覆盖此设置。1801* **早期 Agent Platform 模型**：Claude Code 预先加载所有 MCP 工具，因为它们的服务堆栈拒绝所需的 beta 标头。`ENABLE_TOOL_SEARCH=true` 不会覆盖此设置。
1802 1802
1803在 v2.1.221 之前，Claude Code 在 Google Cloud 的 Agent Platform 上为所有模型禁用工具搜索，除非您设置 `ENABLE_TOOL_SEARCH=true`。
1804
1805使用 `ENABLE_TOOL_SEARCH` 环境变量控制工具搜索行为：1803使用 `ENABLE_TOOL_SEARCH` 环境变量控制工具搜索行为：
1806 1804
1807| 值 | 行为 |1805| 值 | 行为 |
