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 token 的範例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-TW/agent-sdk/mcp.md) 應用程式或 [桌面應用程式](https://code.claude.com/docs/zh-TW/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-TW/agent-sdk/mcp.md) 應用程式或[桌面應用程式](https://code.claude.com/docs/zh-TW/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在 `--output-format stream-json` 執行中，Claude Code 也會在 `system/init` 事件的 [`mcp_server_errors` 欄位](https://code.claude.com/docs/zh-TW/headless#stream-responses)中報告跳過的 `--mcp-config` 項目，以便指令碼可以偵測伺服器從未載入。這需要 Claude Code v2.1.219 或更新版本。87在 `--output-format stream-json` 執行中，Claude Code 也會在 `system/init` 事件的 [`mcp_server_errors` 欄位](https://code.claude.com/docs/zh-TW/headless#stream-responses)中回報被略過的 `--mcp-config` 項目，讓指令碼能偵測到該伺服器從未載入。這需要 Claude Code v2.1.219 或更新版本。
88 88
89### 選項 2：新增遠端 SSE 伺服器89### 選項 2：新增遠端 SSE 伺服器
90 90
91> [!WARNING]91> [!WARNING]
92>92>
93> SSE (Server-Sent Events) 傳輸已棄用。請改用 HTTP 伺服器（如果可用）。93> SSE（Server-Sent Events）傳輸方式已棄用。若可行，請改用 HTTP 伺服器。
94 94
95某些服務仍然只公開 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 或更新版本。95有些服務仍只提供 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 或更新版本。
96 96
97在較早版本上，或直接透過 SSE 連接，請改為傳遞 `--transport sse`：97若使用較早的版本，或要直接透過 SSE 連線，請改為傳入 `--transport sse`：
98 98
99```bash theme={null}99```bash theme={null}
100# 基本語法100# Basic syntax
101claude mcp add --transport sse <name> <url>101claude mcp add --transport sse <name> <url>
102 102
103# 實際範例：連接到 Asana103# Real example: Connect to Asana
104claude mcp add --transport sse asana https://mcp.asana.com/sse104claude mcp add --transport sse asana https://mcp.asana.com/sse
105 105
106# 使用驗證標頭的範例106# Example with authentication header
107claude mcp add --transport sse private-api https://api.company.com/sse \107claude mcp add --transport sse private-api https://api.company.com/sse \
108 --header "X-API-Key: your-key-here"108 --header "X-API-Key: your-key-here"
109```109```
110 110
111### 選項 3：新增本機 stdio 伺服器111### 選項 3：新增本機 stdio 伺服器
112 112
113Stdio 伺服器在您的機器上作為本機程序執行。它們非常適合需要直接系統存取或自訂指令碼的工具。113Stdio 伺服器以本機程序的形式在您的電腦上執行。它們非常適合需要直接存取系統的工具或自訂指令碼。
114 114
115Claude Code 在生成的伺服器環境中設定 `CLAUDE_PROJECT_DIR` 為專案根目錄，因此您的伺服器可以解析專案相對路徑，而無需依賴工作目錄。這是 hook 在其 `CLAUDE_PROJECT_DIR` 變數中接收的相同目錄。從伺服器程序內部讀取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。115Claude Code 會在所啟動伺服器的環境中將 `CLAUDE_PROJECT_DIR` 設為專案根目錄，讓您的伺服器能解析相對於專案的路徑，而不必依賴工作目錄。這與 hook 在其 `CLAUDE_PROJECT_DIR` 變數中收到的目錄相同。請在伺服器程序內讀取它，例如在 Node 中使用 `process.env.CLAUDE_PROJECT_DIR`，或在 Python 中使用 `os.environ["CLAUDE_PROJECT_DIR"]`。
116 116
117`CLAUDE_PROJECT_DIR` 是穩定的專案根目錄，在您於工作階段中途新增或移除工作目錄時不會變更。限制自身檔案系統存取到一組允許目錄的伺服器應改為實作 MCP `roots/list` 請求。Claude Code 使用工作階段的啟動目錄加上您透過 `--add-dir`、`/add-dir` 或 `additionalDirectories` 設定授予的每個 [額外工作目錄](https://code.claude.com/docs/zh-TW/permissions.md#working-directories)來回答 `roots/list`。當該集合變更時，Claude Code 會傳送 `notifications/roots/list_changed`。117`CLAUDE_PROJECT_DIR` 是固定的專案根目錄，在工作階段中途新增或移除工作目錄時不會改變。若伺服器要將自身的檔案系統存取限制在一組允許的目錄內，應改為實作 MCP `roots/list` 請求。Claude Code 會以工作階段的啟動目錄，加上您透過 `--add-dir`、`/add-dir` 或 `additionalDirectories` 設定授予的每個[額外工作目錄](https://code.claude.com/docs/zh-TW/permissions.md#working-directories)來回應 `roots/list`。當該集合變更時，Claude Code 會傳送 `notifications/roots/list_changed`。
118 118
119此變數設定在伺服器的環境中，而不是在 Claude Code 自身的環境中，因此在專案範圍的 `.mcp.json` 項目或 `~/.claude.json` 中的本機或使用者範圍伺服器項目的 `command` 或 `args` 中透過 `${VAR}` 擴展參考它需要預設值，例如 `${CLAUDE_PROJECT_DIR:-.}`。外掛提供的 MCP 設定直接替換 `${CLAUDE_PROJECT_DIR}`，不需要預設值。119此變數設定在伺服器的環境中，而非 Claude Code 本身的環境中，因此若要在專案範圍 `.mcp.json` 項目，或 `~/.claude.json` 中本機或使用者範圍伺服器項目的 `command` 或 `args` 中透過 `${VAR}` 展開來參照它，需要提供預設值，例如 `${CLAUDE_PROJECT_DIR:-.}`。外掛提供的 MCP 設定會直接替換 `${CLAUDE_PROJECT_DIR}`，不需要預設值。
120 120
121```bash theme={null}121```bash theme={null}
122# 基本語法122# Basic syntax
123claude mcp add [options] <name> -- <command> [args...]123claude mcp add [options] <name> -- <command> [args...]
124 124
125# 實際範例：新增 Airtable 伺服器125# Real example: Add Airtable server
126claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \126claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
127 -- npx -y airtable-mcp-server127 -- npx -y airtable-mcp-server
128```128```
129 129
130> [!NOTE]130> [!NOTE]
131>131>
132> 對於 stdio 伺服器，`--`（雙破折號）分隔 Claude 自身的選項（例如 `--transport`、`--env` 和 `--scope`）與執行伺服器的命令和引數。`--` 之後的所有內容都會原封不動地傳遞給伺服器。132> 對於 stdio 伺服器，`--`（雙破折號）會將 Claude 本身的選項（例如 `--transport`、`--env` 和 `--scope`）與執行伺服器的命令和引數分隔開來。`--` 之後的所有內容都會原封不動地傳遞給伺服器。
133>133>
134> 例如：134> 例如：
135>135>
136> * `claude mcp add --transport stdio myserver -- npx server` → 執行 `npx server`136> * `claude mcp add --transport stdio myserver -- npx server` → 執行 `npx server`
137> * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 執行 `python server.py --port 8080`，環境中有 `KEY=value`137> * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 在環境中帶有 `KEY=value` 的情況下執行 `python server.py --port 8080`
138>138>
139> 沒有 `--`，Claude Code 會嘗試將伺服器的旗標（例如上面的 `--port`）解析為自身的選項。139> 若沒有 `--`，Claude Code 會嘗試將伺服器的旗標（例如上方的 `--port`）當作自己的選項來解析。
140>140>
141> `--env` 接受多個 `KEY=value` 對。如果伺服器名稱直接跟在 `--env` 之後，CLI 會將名稱讀取為另一對並拒絕它，因此請在 `--env` 和伺服器名稱之間放置至少一個其他選項，例如 `--transport stdio`。141> `--env` 接受多個 `KEY=value` 配對。若伺服器名稱直接接在 `--env` 之後，CLI 會將該名稱讀取為另一個配對並予以拒絕，因此請在 `--env` 與伺服器名稱之間至少放置一個其他選項，例如 `--transport stdio`。
142 142
143#### Claude Code 如何停止 stdio 伺服器143#### Claude Code 如何停止 stdio 伺服器
144 144
145當 Claude Code 中斷與 stdio 伺服器的連接時（例如在您的工作階段結束時），它會向伺服器程序傳送訊號，並短暫等待其退出，然後才強制停止它。如果您的伺服器在關閉時儲存狀態或移除鎖定檔案，請處理您平台的訊號，並在該時間內完成：145當 Claude Code 中斷與 stdio 伺服器的連線時（例如工作階段結束時），它會向伺服器程序發送訊號，並短暫等待其結束，然後才強制停止。若您的伺服器會在關閉時儲存狀態或移除鎖定檔案，請處理您平台的訊號，並在該時間內完成：
146 146
147* **在 macOS 和 Linux 上**：Claude Code 傳送 `SIGINT`，如果程序在 100 毫秒後仍在執行，則傳送 `SIGTERM`，再過 400 毫秒後傳送 `SIGKILL`。147* **在 macOS 和 Linux 上**：Claude Code 會傳送 `SIGINT`，若 100 毫秒後程序仍在執行則傳送 `SIGTERM`，再過 400 毫秒後傳送 `SIGKILL`。
148* **在 Windows 上**：Claude Code 關閉伺服器的 stdin，如果程序在 300 毫秒後仍在執行，則結束伺服器的程序樹。148* **在 Windows 上**：Claude Code 會關閉伺服器的 stdin，若 300 毫秒後程序仍在執行，則結束伺服器的程序樹。
149 149
150在 v2.1.296 之前，Windows 上的 Claude Code 會立即結束伺服器的程序樹，不會先關閉 stdin 或等待。150在 v2.1.296 之前，Windows 上的 Claude Code 會立即結束伺服器的程序樹，而不會先關閉 stdin 或等待。
151 151
152### 選項 4：新增遠端 WebSocket 伺服器152### 選項 4：新增遠端 WebSocket 伺服器
153 153
154WebSocket 伺服器保持持久雙向連接，適合遠端 MCP 伺服器主動向 Claude 推送事件。當您的伺服器只回應請求時，請改用 HTTP，因為 HTTP 支援 OAuth 和 `claude mcp add --transport` 旗標，而 WebSocket 都不支援。154WebSocket 伺服器會維持持久的雙向連線，適合會主動向 Claude 推送事件的遠端 MCP 伺服器。若您的伺服器只回應請求，請改用 HTTP，因為 HTTP 支援 OAuth 和 `claude mcp add --transport` 旗標，而 WebSocket 兩者皆不支援。
155 155
156在 `.mcp.json` 中或使用 `claude mcp add-json` 設定 WebSocket 伺服器：156請在 `.mcp.json` 中或使用 `claude mcp add-json` 設定 WebSocket 伺服器：
157 157
158```bash theme={null}158```bash theme={null}
159claude mcp add-json events-server \159claude mcp add-json events-server \
160 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'160 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'
161```161```
162 162
163`type: "ws"` 項目接受與 `http` 相同的 `url`、`headers`、`headersHelper`、`timeout` 和 `alwaysLoad` 欄位。身分驗證僅限標頭，因此在 `headers` 中傳遞靜態 token 或在連接時使用 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 產生 token。`claude mcp add --transport` 旗標不接受 `ws`。163`type: "ws"` 項目接受與 `http` 相同的 `url`、`headers`、`headersHelper`、`timeout` 和 `alwaysLoad` 欄位。身分驗證僅透過標頭進行，因此請在 `headers` 中傳入靜態 token，或在連線時使用 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 產生 token。`claude mcp add --transport` 旗標不接受 `ws`。
164 164
165### 從為另一個用戶端編寫的設定指示新增伺服器165### 從為其他用戶端撰寫的設定說明新增伺服器
166 166
167MCP 伺服器不是 Claude Code 特有的，因此伺服器的設定指示可能是為 Claude Desktop、Cursor 或另一個 MCP 用戶端編寫的，並且不提供 `claude mcp add` 命令。若要新增伺服器，請在這些指示中尋找 URL、啟動命令或 JSON 區塊：167MCP 伺服器並非 Claude Code 專屬，因此伺服器的設定說明可能是為 Claude Desktop、Cursor 或其他 MCP 用戶端撰寫，且未提供 `claude mcp add` 命令。若仍要新增該伺服器，請在這些說明中尋找 URL、啟動命令或 JSON 區塊：
168 168
169* **URL**（例如 `https://mcp.example.com/mcp`）：伺服器是遠端的。169* **URL**，例如 `https://mcp.example.com/mcp`：伺服器位於遠端。
170* **啟動命令**（例如 `npx -y @example/mcp-server`）：伺服器在您的機器上執行。170* **啟動命令**，例如 `npx -y @example/mcp-server`：伺服器在您的電腦上執行。
171* **`mcpServers` JSON 區塊**：為另一個用戶端的設定檔編寫的設定。171* **`mcpServers` JSON 區塊**：為其他用戶端的設定檔撰寫的設定。
172 172
173每一個都是 [安裝 MCP 伺服器](#installing-mcp-servers)中四個選項之一接受的輸入。在下面找到您擁有的形狀，將其轉換為 Claude Code 接受的命令。除非您新增 `--scope project` 或 `--scope user`，否則每個命令都會寫入 [本機範圍](#local-scope)。173每一種都是[安裝 MCP 伺服器](#installing-mcp-servers)中四個選項所接受的輸入之一。請在下方找到您所擁有的形式，將其轉換為 Claude Code 接受的命令。除非您加上 `--scope project` 或 `--scope user`，否則每個命令都會寫入[本機範圍](#local-scope)。
174 174
175#### 從 URL 新增伺服器175#### 從 URL 新增伺服器
176 176
177URL 表示伺服器是遠端的。對於 `https://` 端點，使用 `--transport http` 新增它，或在指示說端點使用 SSE 時遵循 [選項 2](#option-2-add-a-remote-sse-server)。對於 `wss://` 端點，改為使用 [選項 4](#option-4-add-a-remote-websocket-server)，因為 `--transport` 不接受 `ws`：177URL 表示伺服器位於遠端。對於 `https://` 端點，請使用 `--transport http` 新增；若說明指出端點使用 SSE，則依照[選項 2](#option-2-add-a-remote-sse-server) 操作。對於 `wss://` 端點，請改用[選項 4](#option-4-add-a-remote-websocket-server)，因為 `--transport` 不接受 `ws`：
178 178
179```bash theme={null}179```bash theme={null}
180claude mcp add --transport http example https://mcp.example.com/mcp180claude mcp add --transport http example https://mcp.example.com/mcp
181```181```
182 182
183如果指示也提供 API 金鑰或 token 標頭，請使用 `--header` 傳遞它，如 [選項 1](#option-1-add-a-remote-http-server)所示。183若說明還提供了 API 金鑰或 token 標頭，請如[選項 1](#option-1-add-a-remote-http-server) 所示，使用 `--header` 傳入。
184 184
185#### 從 `npx`、`uvx` 或二進位命令新增伺服器185#### 從 `npx`、`uvx` 或二進位檔命令新增伺服器
186 186
187啟動命令表示伺服器作為本機 stdio 程序執行。將整個命令放在 `--` 之後，以便 Claude Code 將旗標（例如 `-y`）傳遞給啟動伺服器的命令，而不是將其讀取為自身的選項。使用 `--env` 傳遞指示要求的任何環境變數，在伺服器名稱之後和 `--` 之前：187啟動命令表示伺服器以本機 stdio 程序的形式執行。請將整個命令放在 `--` 之後，讓 Claude Code 將 `-y` 等旗標傳遞給啟動伺服器的命令，而不是將其讀取為自己的選項。請在伺服器名稱之後、`--` 之前，使用 `--env` 傳入說明要求的任何環境變數：
188 188
189```bash theme={null}189```bash theme={null}
190claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server190claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server
191```191```
192 192
193[選項 3](#option-3-add-a-local-stdio-server)完整涵蓋 `--` 分隔符。193[選項 3](#option-3-add-a-local-stdio-server) 完整說明了 `--` 分隔符號。
194 194
195#### 從 `mcpServers` JSON 區塊新增伺服器195#### 從 `mcpServers` JSON 區塊新增伺服器
196 196
197為另一個 MCP 用戶端（例如 Claude Desktop）編寫的 `mcpServers` 區塊使用 Claude Code 讀取的包裝器金鑰和項目形狀。將 `mcpServers` 內的物件傳遞給 `claude mcp add-json`，而不是包裝器。兩個項目需要先修復：197為其他 MCP 用戶端（例如 Claude Desktop）撰寫的 `mcpServers` 區塊，使用的是 Claude Code 可讀取的包裝鍵與項目形式。請將 `mcpServers` 內部的物件（而非包裝層）傳給 `claude mcp add-json`。有兩種項目需要先修正：
198 198
199* **`url` 沒有 `type`**：新增 `"type": "http"`、`"type": "sse"` 或 `"type": "ws"` 以符合端點。Claude Code 將沒有 `type` 的項目讀取為 stdio 伺服器，因此沒有 `type` 的 `url` 項目會失敗。199* **有 `url` 但沒有 `type`**：依端點加上 `"type": "http"`、`"type": "sse"` 或 `"type": "ws"`。Claude Code 會將沒有 `type` 的項目視為 stdio 伺服器，因此沒有 `type` 的 `url` 項目會失敗。
200* **金鑰包含字母、數字、連字號和底線以外的字元**：選擇僅使用這些字元的伺服器名稱。否則金鑰是伺服器名稱。200* **鍵包含字母、數字、連字號和底線以外的字元**：請選擇只使用這些字元的伺服器名稱。否則，該鍵即為伺服器名稱。
201 201
202例如，此區塊：202例如，這個區塊：
203 203
204```json theme={null}204```json theme={null}
205{205{
212}212}
213```213```
214 214
215變成此命令：215會變成這個命令：
216 216
217```bash theme={null}217```bash theme={null}
218claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'218claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'
219```219```
220 220
221[從 JSON 設定新增 MCP 伺服器](#add-mcp-servers-from-json-configuration)涵蓋 `add-json` 的 shell 逃逸和 `--scope` 旗標。若要與您的團隊共享伺服器，請改為新增 `--scope project`，或在您的專案根目錄的 `.mcp.json` 下的 `mcpServers` 下新增項目並提交它。[專案範圍](#project-scope)涵蓋 Claude Code 如何載入和核准該檔案。221[從 JSON 設定新增 MCP 伺服器](#add-mcp-servers-from-json-configuration)說明了 shell 跳脫處理以及 `add-json` 的 `--scope` 旗標。若要改為與團隊共用該伺服器，請加上 `--scope project`，或將該項目新增至專案根目錄中 `.mcp.json` 的 `mcpServers` 下並提交。[專案範圍](#project-scope)說明了 Claude Code 如何載入及核准該檔案。
222 222
223每個 `claude mcp add` 和 `claude mcp add-json` 命令在成功時列印 `Added ...` 行。若要檢查 Claude Code 是否已連接，請執行 `claude mcp get <name>`；[伺服器狀態](#server-status)涵蓋它顯示的狀態和 `.mcp.json` 伺服器的核准步驟。223每個 `claude mcp add` 和 `claude mcp add-json` 命令成功時都會印出一行 `Added ...`。若要確認 Claude Code 已連線，請執行 `claude mcp get <name>`；[伺服器狀態](#server-status)說明了它所顯示的狀態，以及 `.mcp.json` 伺服器的核准步驟。
224 224
225### 管理您的伺服器225### 管理您的伺服器
226 226
227設定後，您可以使用這些命令管理您的 MCP 伺服器：227設定完成後，您可以使用以下命令管理 MCP 伺服器：
228 228
229```bash theme={null}229```bash theme={null}
230# 列出所有已設定的伺服器230# List all configured servers
231claude mcp list231claude mcp list
232 232
233# 取得特定伺服器的詳細資訊233# Get details for a specific server
234claude mcp get notion234claude mcp get notion
235 235
236# 移除伺服器236# Remove a server
237claude mcp remove notion237claude mcp remove notion
238 238
239# （在 Claude Code 內）檢查伺服器狀態239# (within Claude Code) Check server status
240/mcp240/mcp
241```241```
242 242
243移除遠端伺服器時，Claude Code 也會刪除為該伺服器儲存的 OAuth token 和用戶端註冊。243移除遠端伺服器時，Claude Code 也會刪除它為該伺服器儲存的 OAuth token 和用戶端註冊資訊。
244 244
245#### 伺服器狀態245#### 伺服器狀態
246 246
247`claude mcp add` 透過列印 `Added ...` 行確認成功新增，這表示設定已寫入。如果命令改為列印 `was not saved` 訊息，請參閱 [MCP 伺服器未儲存或移除](https://code.claude.com/docs/zh-TW/errors.md#mcp-server-was-not-saved-or-removed)；對於 `may not have been saved` 訊息，請參閱 [MCP 伺服器可能未儲存或移除](https://code.claude.com/docs/zh-TW/errors.md#mcp-server-may-not-have-been-saved-or-removed)。247`claude mcp add` 會印出一行 `Added ...` 以確認新增成功，這表示設定已寫入。若命令改為印出 `was not saved` 訊息，請參閱 [MCP server was not saved or removed](https://code.claude.com/docs/zh-TW/errors.md#mcp-server-was-not-saved-or-removed)；若為 `may not have been saved` 訊息，請參閱 [MCP server may not have been saved or removed](https://code.claude.com/docs/zh-TW/errors.md#mcp-server-may-not-have-been-saved-or-removed)。
248 248
249`claude mcp list` 在它列出的每個伺服器旁邊顯示健康狀態，例如 `✔ Connected`、`! Needs authentication` 或 `✘ Failed to connect`。失敗狀態表示 Claude Code 無法連接到該伺服器，而不是列表命令失敗。249`claude mcp list` 會在列出的每個伺服器旁顯示健康狀態，例如 `✔ Connected`、`! Needs authentication` 或 `✘ Failed to connect`。失敗狀態表示 Claude Code 無法連線至該伺服器，而不是 list 命令失敗。
250 250
251此列表中的狀態報告設定決定而不是連接嘗試，因此 Claude Code 在不連接到伺服器的情況下列印它們：251以下清單中的狀態回報的是設定上的決定，而非連線嘗試，因此 Claude Code 會在不連線至伺服器的情況下印出它們：
252 252
253* ``⏸ Pending approval (run `claude` to approve)``：來自 `.mcp.json`、您尚未核准的專案範圍伺服器。Claude Code 會在 `claude mcp list` 和 `claude mcp get <name>` 中都顯示它。請以互動方式執行 `claude` 來檢閱並核准它。253* ``⏸ Pending approval (run `claude` to approve)``：來自 `.mcp.json`、您尚未核准的專案範圍伺服器。Claude Code 會在 `claude mcp list` 和 `claude mcp get <name>` 中都顯示它。請以互動方式執行 `claude` 來檢閱並核准它。
254* `✘ Rejected (see disabledMcpjsonServers in settings)`：由 [`disabledMcpjsonServers`](https://code.claude.com/docs/zh-TW/settings-reference#disabledmcpjsonservers) 項目拒絕的 `.mcp.json` 伺服器。Claude Code 只在 `claude mcp get <name>` 中顯示它。254* `✘ Rejected (see disabledMcpjsonServers in settings)`：被 [`disabledMcpjsonServers`](https://code.claude.com/docs/zh-TW/settings-reference#disabledmcpjsonservers) 項目拒絕的 `.mcp.json` 伺服器。Claude Code 只會在 `claude mcp get <name>` 中顯示它。
255* `⊘ 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` 面板重新開啟伺服器。255* `⊘ 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` 面板重新啟用該伺服器。
256 256
257#### 專案伺服器核准和工作區信任257#### 專案伺服器核准與工作區信任
258 258
259`claude mcp list` 和 `claude mcp get` 只從未簽入儲存庫的設定檔讀取 `.mcp.json` 核准，直到您透過在工作區中執行 `claude` 並接受工作區信任對話來信任工作區。複製的儲存庫無法核准自身的伺服器：提交到專案的 `.claude/settings.json` 的 [`enableAllProjectMcpServers`](https://code.claude.com/docs/zh-TW/settings-reference#enableallprojectmcpservers) 或 [`enabledMcpjsonServers`](https://code.claude.com/docs/zh-TW/settings-reference#enabledmcpjsonservers) 在不受信任的資料夾中被忽略，伺服器保持在 `⏸ Pending approval` 而不是被連接和健康檢查。259在您於工作區中執行 `claude` 並接受工作區信任對話框以信任該工作區之前，`claude mcp list` 和 `claude mcp get` 只會從未簽入儲存庫的設定檔讀取 `.mcp.json` 核准。複製下來的儲存庫無法核准自己的伺服器：在未受信任的資料夾中，提交至專案 `.claude/settings.json` 的 [`enableAllProjectMcpServers`](https://code.claude.com/docs/zh-TW/settings-reference#enableallprojectmcpservers) 或 [`enabledMcpjsonServers`](https://code.claude.com/docs/zh-TW/settings-reference#enabledmcpjsonservers) 會被忽略，伺服器會停留在 `⏸ Pending approval`，而不會被連線並進行健康檢查。
260 260
261這些來源的核准在不受信任的資料夾中仍然適用：261來自以下來源的核准在未受信任的資料夾中仍然適用：
262 262
263* 您的使用者 `~/.claude/settings.json`263* 您的使用者 `~/.claude/settings.json`
264* 受管設定264* 受管設定
265* 使用 `--settings` 傳遞的設定265* 透過 `--settings` 傳入的設定
266 266
267Claude Code 也應用來自未追蹤 `.claude/settings.local.json` 的核准，但它執行 git 來檢查檔案是否被追蹤，並且只在 [受信任的資料夾](https://code.claude.com/docs/zh-TW/permissions.md#project-allow-rules-and-workspace-trust)中執行該檢查。在您從未信任的資料夾中，Claude Code 會等待信任對話，然後才應用檔案的核准，除非資料夾是您自己的設定主目錄：您的家目錄，或其 `.claude` 您已設定為 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-TW/env-vars) 的目錄。在 v2.1.207 之前，Claude Code 即使在您從未信任的資料夾中也應用來自未追蹤 `.claude/settings.local.json` 的核准。267Claude Code 也會套用來自未追蹤的 `.claude/settings.local.json` 的核准，但它會執行 git 來檢查該檔案是否被追蹤，而且只會在[受信任的資料夾](https://code.claude.com/docs/zh-TW/permissions.md#project-allow-rules-and-workspace-trust)中執行該檢查。在您從未信任過的資料夾中，Claude Code 會等待信任對話框後才套用該檔案的核准，除非該資料夾是您自己的設定主目錄：也就是您的家目錄，或其 `.claude` 已被您設為 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-TW/env-vars) 的目錄。在 v2.1.207 之前，即使在您從未信任過的資料夾中，Claude Code 也會套用來自未追蹤的 `.claude/settings.local.json` 的核准。
268 268
269任何設定檔中的 `disabledMcpjsonServers` 項目仍然拒絕伺服器。269任何設定檔中的 `disabledMcpjsonServers` 項目仍會拒絕該伺服器。
270 270
271#### 伺服器狀態詳細資訊271#### 伺服器狀態詳細資訊
272 272
273在 `/mcp` 中（包括伺服器的選單）和 [`/plugin`](https://code.claude.com/docs/zh-TW/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 或更新版本。273在 `/mcp`（包括其中的伺服器選單）以及 [`/plugin`](https://code.claude.com/docs/zh-TW/plugins/install) 管理器中，您先前使用過的遠端 HTTP 或 SSE 伺服器可能會顯示 `cached` 狀態，例如 `cached 2h ago · connects on first use · 5 tools`。Claude Code 是從先前工作階段儲存的探索快取中載入伺服器的工具清單，而非在啟動時連線，並會在 Claude 第一次呼叫該伺服器的某個工具時連線該伺服器。這些工具從您的第一則訊息開始就可使用，因此您無需執行任何操作。探索快取及其 `cached` 狀態需要 Claude Code v2.1.221 或更新版本。
274 274
275發現快取預設關閉，除非逐步推出已為您的帳戶啟用它。設定 [`MCP_DISCOVERY_CACHE=1`](https://code.claude.com/docs/zh-TW/env-vars) 以開啟它，或設定 `0` 以在推出啟用它時保持關閉。在 v2.1.238 之前，快取預設開啟。275除非逐步推出已為您的帳戶啟用，否則探索快取預設為關閉。設定 [`MCP_DISCOVERY_CACHE=1`](https://code.claude.com/docs/zh-TW/env-vars) 可將其開啟，或設為 `0` 以在推出已啟用時仍保持關閉。在 v2.1.238 之前，快取預設為開啟。
276 276
277當您從 `/mcp` 中的伺服器選單選擇 **Disable** 或 **Clear authentication** 時，Claude Code 也會捨棄該伺服器的快取項目。**Reconnect** 在已連接或失敗的伺服器上也會捨棄它；在 `cached` 伺服器上，**Reconnect** 現在連接伺服器並保留項目。Claude Code 在捨棄項目後下次連接到伺服器時，它會從伺服器而不是從快取中擷取工具列表。277當您從 `/mcp` 中伺服器的選單選取 **Disable** 或 **Clear authentication** 時，Claude Code 也會捨棄該伺服器的快取項目。對已連線或失敗的伺服器，**Reconnect** 也會捨棄它；對 `cached` 伺服器，**Reconnect** 會立即連線伺服器並保留該項目。捨棄項目後，Claude Code 下次連線至該伺服器時，會從伺服器而非快取擷取工具清單。
278 278
279當伺服器的狀態為 `✘ Failed to connect` 時，`claude mcp list` 將失敗詳細資訊附加到該狀態行，`claude mcp get <name>` 在 `Issue:` 行上顯示它：HTTP 狀態或錯誤代碼，加上伺服器傳回的任何錯誤文字。伺服器在 `/mcp` 中的詳細檢視在其 `Issue:` 列中包含相同的伺服器報告文字。Claude Code 從此詳細資訊中編輯類似憑證的文字，並且永遠不包括擴展的伺服器 URL，它可能攜帶機密。Claude Code 不會將詳細資訊附加到 `✘ Connection error` 狀態，因為它會列印的異常文字可以嵌入該 URL。在 v2.1.219 之前，兩個命令都只顯示裸露的失敗狀態，沒有狀態代碼或伺服器的錯誤文字。279當伺服器的狀態為 `✘ Failed to connect` 時，`claude mcp list` 會在該狀態行後附加失敗詳細資訊，而 `claude mcp get <name>` 會在 `Issue:` 行中顯示它：HTTP 狀態或錯誤代碼，以及伺服器傳回的任何錯誤文字。`/mcp` 中伺服器的詳細資訊檢視也會在其 `Issue:` 列中包含相同的伺服器回報文字。Claude Code 會從這些詳細資訊中遮蔽類似憑證的文字，且絕不包含展開後的伺服器 URL，因為其中可能帶有機密資訊。Claude Code 不會在 `✘ Connection error` 狀態後附加詳細資訊，因為它在該處會印出的例外文字可能內嵌該 URL。在 v2.1.219 之前，這兩個命令只顯示單純的失敗狀態，不含狀態碼或伺服器的錯誤文字。
280 280
281當您從 `/mcp` 完成身分驗證且連接仍然因 HTTP 狀態或傳輸錯誤代碼而失敗時，Claude Code 會在嘗試後列印的訊息中新增該代碼和伺服器 URL 的來源。來源是方案和主機，加上 URL 命名的連接埠（例如 `https://mcp.example.com`）。281當您從 `/mcp` 完成身分驗證，但連線仍因 HTTP 狀態或傳輸錯誤代碼而失敗時，Claude Code 會在嘗試後印出的訊息中加入該代碼以及伺服器 URL 的來源。來源是指通訊協定與主機，若 URL 有指定連接埠則加上連接埠，例如 `https://mcp.example.com`。
282 282
283* 路徑和查詢永遠不會出現在該訊息中。283* 該訊息中絕不會出現路徑與查詢字串。
284* 對於本機、專案或使用者 [範圍](#mcp-installation-scopes)中的伺服器或受管 MCP 設定，來源顯示該設定中寫入的主機，因此主機中的 `${VAR}` 參考在訊息中不會展開。284* 對於本機、專案或使用者[範圍](#mcp-installation-scopes)中或受管 MCP 設定中的伺服器，來源會顯示該設定中所寫的主機，因此主機中的 `${VAR}` 參照不會在訊息中展開。
285* 對於沒有狀態或錯誤代碼的失敗，Claude Code 顯示錯誤文字而不顯示來源。285* 對於沒有狀態或錯誤代碼的失敗，Claude Code 會顯示錯誤文字，但不含來源。
286 286
287設定為空 `url` 的遠端伺服器在 `/mcp`、`claude mcp list` 和 [`/plugin`](https://code.claude.com/docs/zh-TW/plugins/install) 管理員中顯示為 `not configured`，Claude Code 不會嘗試連接到它。外掛可以包含此類佔位符項目，用於您稍後設定的連接器，因此 Claude Code 不會將其報告為錯誤或設定問題。伺服器在 `/mcp` 中的詳細檢視讀取 `No URL configured for this server`；設定項目的 `url` 以連接它。287設定中 `url` 為空的遠端伺服器，在 `/mcp`、`claude mcp list` 和 [`/plugin`](https://code.claude.com/docs/zh-TW/plugins/install) 管理器中會顯示為 `not configured`，且 Claude Code 不會嘗試連線至它。外掛可以為您稍後設定的連接器加入這類預留項目，因此 Claude Code 不會將其回報為錯誤或設定問題。`/mcp` 中該伺服器的詳細資訊檢視會顯示 `No URL configured for this server`；請設定該項目的 `url` 以進行連線。
288 288
289#### 設定警告289#### 設定警告
290 290
291Claude Code 警告下面的設定問題。每個項目說明 Claude Code 檢查的內容以及如何清除警告：291Claude Code 會針對以下設定問題發出警告。每個項目都說明了 Claude Code 檢查的內容以及如何清除警告：
292 292
293* **隱藏空白**：當 MCP 設定值攜帶隱藏的前導或尾隨空白時，Claude Code 會發出警告，這通常來自貼上帶有尾隨換行符的 token。Claude Code 檢查 `command`、`url`、每個 `args` 項目以及 `env` 和 `headers` 下的值和金鑰名稱。Claude Code 在 `claude mcp list` 輸出和 `/mcp` 中顯示警告，命名受影響的欄位而不回顯其值，例如 `Leading or trailing whitespace in: headers.Authorization`。Claude Code 不會修剪空白並完全按照寫入的方式使用值，因此編輯設定以移除它。293* **隱藏的空白字元**：當 MCP 設定值帶有隱藏的前導或尾隨空白字元時，Claude Code 會發出警告，這通常來自貼上帶有尾隨換行字元的 token。Claude Code 會檢查 `command`、`url`、每個 `args` 項目，以及 `env` 和 `headers` 下的值與鍵名稱。Claude Code 會在 `claude mcp list` 輸出和 `/mcp` 中顯示警告，列出受影響的欄位但不顯示其值，例如 `Leading or trailing whitespace in: headers.Authorization`。Claude Code 不會修剪空白字元，而是完全依照所寫的內容使用這些值，因此請編輯設定將其移除。
294* **在多個範圍中使用相同名稱**：如果您在多個 [範圍](#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 金鑰。294* **同一名稱存在於多個範圍**：若您在多個[範圍](#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 金鑰等已解析的值。
295* **保留名稱**：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-TW/desktop.md#preview-your-app)使用的內建伺服器。295* **保留名稱**：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-TW/desktop.md#preview-your-app)所使用的內建伺服器。
296* **遺漏環境變數**：如果伺服器設定中的 [`${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)，沒有警告。296* **缺少環境變數**：若伺服器設定中的 [`${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)，且不會發出警告。
297 297
298#### 工具可用性298#### 工具可用性
299 299
300`/mcp` 面板在每個已連接伺服器旁邊顯示工具計數，並標記宣傳工具功能但不公開工具的伺服器。300`/mcp` 面板會在每個已連線伺服器旁顯示工具數量，並標示出宣告具備工具能力但未公開任何工具的伺服器。
301 301
302如果您的請求需要仍在背景連接的伺服器中的工具，Claude 會在繼續之前等待該伺服器。等待的方式取決於您的設定：302若您的請求需要來自仍在背景連線中的伺服器的工具，Claude 會等待該伺服器後再繼續。等待的方式取決於您的設定：
303 303
304* **使用 [工具搜尋](#scale-with-mcp-tool-search)（預設）**：等待發生在 `ToolSearch` 呼叫內。304* **使用[工具搜尋](#scale-with-mcp-tool-search)（預設）**：等待發生在 `ToolSearch` 呼叫內。
305* **沒有工具搜尋**：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)。305* **不使用工具搜尋**：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)。
306* **在 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 的下一個請求上變得可用。306* **在 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 的下一個請求中變為可用。
307 307
308啟用工具搜尋後，當伺服器在 Claude 工作時完成連接時，Claude Code 在同一回合中的下一個請求上將伺服器的工具名稱列出給 Claude。Claude 然後可以搜尋並呼叫這些工具，而無需等待您的下一條訊息。308啟用工具搜尋時，若伺服器在 Claude 工作期間完成連線，Claude Code 會在同一回合中 Claude 的下一個請求裡，向 Claude 列出該伺服器的工具名稱。Claude 隨後即可搜尋並呼叫這些工具，而無需等待您的下一則訊息。
309 309
310恢復工作階段後，Claude 可以在工具的 MCP 伺服器仍在連接時呼叫已儲存對話中的工具。當伺服器正在進行首次連接嘗試時，Claude Code 會保留該呼叫最多 10 秒，並在工具可用後執行它。如果伺服器未及時連接，或它已在 [失敗嘗試後重試](#automatic-reconnection)，該呼叫會以 `No such tool available` [工具錯誤](https://code.claude.com/docs/zh-TW/errors.md#no-such-tool-available)失敗。310在您恢復工作階段後，Claude 可能會在某工具的 MCP 伺服器仍在連線時，呼叫已儲存對話中的該工具。當伺服器正在進行第一次連線嘗試時，Claude Code 會將呼叫保留最多 10 秒，並在工具可用時執行它。若伺服器未及時連線，或已在[失敗嘗試後重試中](#automatic-reconnection)，該呼叫會以 `No such tool available` [工具錯誤](https://code.claude.com/docs/zh-TW/errors.md#no-such-tool-available)失敗。
311 311
312### 在不移除的情況下停用伺服器312### 停用伺服器而不移除它
313 313
314在 `/mcp` 面板中切換伺服器關閉，以停止 Claude Code 連接到它，而不會失去其設定。Claude Code 仍然在 `/mcp` 中列出伺服器，標記為已停用。314在 `/mcp` 面板中關閉伺服器，可阻止 Claude Code 連線至該伺服器，而不會遺失其設定。Claude Code 仍會在 `/mcp` 中列出該伺服器，並標示為已停用。
315 315
316當您切換伺服器時，Claude Code 在 `~/.claude.json` 中按專案記錄您的選擇，在兩個涵蓋不相交伺服器集合的列表之一中：316當您切換伺服器時，Claude Code 會依專案將您的選擇記錄在 `~/.claude.json` 中的兩個清單之一，這兩個清單涵蓋互不重疊的伺服器集合：
317 317
318* `disabledMcpServers`：使用者設定伺服器、外掛伺服器、您的組織 [透過受管設定提供](https://code.claude.com/docs/zh-TW/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`。318* `disabledMcpServers`：選擇退出清單，適用於使用者設定的伺服器、外掛伺服器、您的組織[透過受管設定提供的伺服器](https://code.claude.com/docs/zh-TW/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`。
319* `enabledMcpServers`：預設關閉的內建伺服器（例如 `computer-use`）的選擇加入列表。Claude Code 只在您在此列出時連接預設關閉的伺服器。319* `enabledMcpServers`：選擇加入清單，適用於預設關閉的內建伺服器，例如 `computer-use`。Claude Code 只有在您將預設關閉的伺服器列在此處時才會連線至它。
320 320
321Claude Code 為每個伺服器查詢恰好兩個列表之一，因此兩個列表都不會覆寫另一個。如果您將常規伺服器新增到 `enabledMcpServers`，或將預設關閉的內建伺服器新增到 `disabledMcpServers`，Claude Code 會忽略該項目。321Claude Code 對每個伺服器只會查閱兩個清單中的其中一個，因此任一清單都不會覆寫另一個。若您將一般伺服器加入 `enabledMcpServers`，或將預設關閉的內建伺服器加入 `disabledMcpServers`，Claude Code 會忽略該項目。
322 322
323`disabledMcpServers` 和 `enabledMcpServers` 與 [`enabledMcpjsonServers`](https://code.claude.com/docs/zh-TW/settings-reference#enabledmcpjsonservers) 和 [`disabledMcpjsonServers`](https://code.claude.com/docs/zh-TW/settings-reference#disabledmcpjsonservers) 無關，它們控制專案的 `.mcp.json` 檔案中定義的伺服器的核准。323`disabledMcpServers` 和 `enabledMcpServers` 與 [`enabledMcpjsonServers`](https://code.claude.com/docs/zh-TW/settings-reference#enabledmcpjsonservers) 及 [`disabledMcpjsonServers`](https://code.claude.com/docs/zh-TW/settings-reference#disabledmcpjsonservers) 無關，後兩者控制的是專案 `.mcp.json` 檔案中所定義伺服器的核准。
324 324
325### MCP 用戶端執行時325### MCP 用戶端執行環境
326 326
327Claude 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 執行時。327Claude 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 執行環境。
328 328
329Claude Code 每次啟動時選擇執行時，並保持到您退出。在 [擷取功能旗標](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)的工作階段中，它在 Claude Code v2.1.232 或更新版本上使用 v2 執行時。329Claude Code 每次啟動時都會選擇一種執行環境，並持續使用直到您結束。在會[擷取功能旗標](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)的工作階段中，Claude Code v2.1.232 或更新版本會使用 v2 執行環境。
330 330
331在不擷取功能旗標的工作階段中，Claude Code 在 Claude Code v2.1.274 或更新版本上預設使用 v2 執行時：331在不擷取功能旗標的工作階段中，Claude Code v2.1.274 或更新版本預設使用 v2 執行環境：
332 332
333* 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-TW/env-vars)333* 在 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-TW/env-vars)
334* 透過 [Claude 應用程式閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)登入的工作階段334* 透過 [Claude apps 閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)登入的工作階段
335* 您關閉遙測或功能旗標擷取的工作階段，例如使用 `DISABLE_TELEMETRY`335* 您關閉遙測或功能旗標擷取的工作階段，例如使用 `DISABLE_TELEMETRY`
336 336
337在 v2 上，Claude Code 也：337在 v2 上，Claude Code 還會：
338 338
339* 詢問 HTTP、stdio 和 claude.ai 連接器伺服器是否支援較新的修訂，並與支援的伺服器一起使用它。這包括雲端和 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 工作階段的連接器。Claude Code 連接到每個其他伺服器，如 v1 所做的那樣。339* 詢問 HTTP、stdio 和 claude.ai 連接器伺服器是否支援較新的修訂版，並與支援的伺服器使用該修訂版。這包括雲端和 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 工作階段的連接器。Claude Code 會以與 v1 相同的方式連線至其他所有伺服器。
340* 在 [它保持開啟的流](#notification-streams-on-the-v2-runtime)上從較新修訂上的伺服器接收 `list_changed` 通知。340* 透過[保持開啟的串流](#notification-streams-on-the-v2-runtime)，從使用較新修訂版的伺服器接收 `list_changed` 通知。
341* 不註冊在較新修訂上連接的 [頻道](#push-messages-with-channels)伺服器，因為該修訂無法攜帶頻道訊息。341* 不會註冊以較新修訂版連線的[頻道](#push-messages-with-channels)伺服器，因為該修訂版無法承載頻道訊息。
342* 失敗 [MCP OAuth 登入](#authenticate-with-remote-mcp-servers)，其授權回應命名意外發行者。342* 當[MCP OAuth 登入](#authenticate-with-remote-mcp-servers)的授權回應指名了非預期的發行者時，使登入失敗。
343* 僅將 [MCP OAuth](#authenticate-with-remote-mcp-servers) 憑證傳送到透過 HTTPS 或在 `localhost`、`127.0.0.1` 或 `::1` 上提供的 token 端點。對於 token 端點為其他地方（例如本機網路上的裝置）的純 `http://` 的伺服器，登入失敗。請參閱 [拒絕將憑證傳送到非 https token 端點](https://code.claude.com/docs/zh-TW/errors.md#refusing-to-send-credentials-to-non-https-token-endpoint)。343* 只將 [MCP OAuth](#authenticate-with-remote-mcp-servers) 憑證傳送至透過 HTTPS 提供服務，或位於 `localhost`、`127.0.0.1` 或 `::1` 的 token 端點。對於 token 端點在其他任何位置使用純 `http://` 的伺服器（例如您本機網路上的裝置），登入會失敗。請參閱 [Refusing to send credentials to non-https token endpoint](https://code.claude.com/docs/zh-TW/errors.md#refusing-to-send-credentials-to-non-https-token-endpoint)。
344 344
345Anthropic 可以使用 Claude Code 擷取的功能旗標將特定伺服器保持在較早的協議上，或關閉該流。345Anthropic 可以透過 Claude Code 擷取的功能旗標，讓特定伺服器維持使用較早的協定，或不使用該串流。
346 346
347若要自行選擇執行時，請設定 [`MCP_SDK_GENERATION`](https://code.claude.com/docs/zh-TW/env-vars) 為 `v1` 或 `v2`。若要決定 Claude Code 是否詢問，請設定 [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/zh-TW/env-vars) 為 `auto` 或 `legacy`。347若要自行選擇執行環境，請將 [`MCP_SDK_GENERATION`](https://code.claude.com/docs/zh-TW/env-vars) 設為 `v1` 或 `v2`。若要決定 Claude Code 是否詢問，請將 [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/zh-TW/env-vars) 設為 `auto` 或 `legacy`。
348 348
349### 動態工具更新349### 動態工具更新
350 350
351MCP 伺服器可以在連接期間變更其提供的工具、提示詞或資源，並傳送 `list_changed` 通知。當收到通知時：351MCP 伺服器可以在連線期間變更其提供的工具、提示詞或資源，並傳送 `list_changed` 通知。收到通知時：
352 352
353* **在互動式終端機工作階段中**，Claude Code 會從該伺服器擷取更新後的列表，因此您無需重新連接它。353* **在互動式終端機工作階段中**，Claude Code 會從該伺服器擷取更新後的清單，因此您無需重新連線。
354* **在使用 `-p` 旗標的 [非互動模式](https://code.claude.com/docs/zh-TW/headless.md)中以及在 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 中**，Claude Code 在收到這些通知時只重新整理工具列表。354* **在使用 `-p` 旗標的[非互動模式](https://code.claude.com/docs/zh-TW/headless.md)及 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 中**，Claude Code 收到這些通知時只會重新整理工具清單。
355 355
356如果重新整理請求失敗，Claude Code 會保留伺服器之前發現的工具、提示詞和資源，直到稍後的重新整理成功。356若重新整理請求失敗，Claude Code 會保留該伺服器先前探索到的工具、提示詞和資源，直到之後的重新整理成功為止。
357 357
358#### v2 執行時上的通知流358#### v2 執行環境上的通知串流
359 359
360在 [v2 執行時](#mcp-client-runtimes)上，Claude Code 在它保持開啟的流上從較新協議修訂上的伺服器接收 `list_changed` 通知。當流關閉時，Claude Code 會重新開啟它，有兩個限制：360在 [v2 執行環境](#mcp-client-runtimes)上，Claude Code 會透過保持開啟的串流，從使用較新協定修訂版的伺服器接收 `list_changed` 通知。串流關閉時，Claude Code 會重新開啟它，但有兩項限制：
361 361
362* **流在 10 秒內再次關閉**：Claude Code 最多重新開啟三次，然後停止該連接。362* **串流在 10 秒內再次關閉**：Claude Code 最多重新開啟三次，之後對該連線停止重新開啟。
363* **流保持開啟超過 10 秒，然後關閉**（如流到無伺服器主機通常所做的那樣）：在一小時內五次重新開啟後，Claude Code 在下一次之前等待約六小時。363* **串流保持開啟超過 10 秒後才關閉**（連至無伺服器主機的串流通常如此）：在一小時內重新開啟五次後，Claude Code 會等待約六小時才進行下一次。
364 364
365直到流重新開啟，您保留伺服器的最後擷取工具、提示詞和資源。若要更快地取得其變更，請從 `/mcp` 重新連接伺服器。365在串流重新開啟之前，您會保留該伺服器最後擷取的工具、提示詞和資源。若要更快取得其變更，請從 `/mcp` 重新連線該伺服器。
366 366
367### 自動重新連接367### 自動重新連線
368 368
369Claude Code 重新連接在工作階段中途掉線的遠端伺服器，並在暫時性錯誤後重試 HTTP 或 SSE 伺服器的首次連接。對於 stdio 伺服器，請參閱 [退出或無法啟動的 Stdio 伺服器](#stdio-servers-that-exit-or-fail-to-start)。369Claude Code 會重新連線在工作階段中途斷線的遠端伺服器，並在發生暫時性錯誤後重試 HTTP 或 SSE 伺服器的第一次連線。關於 stdio 伺服器，請參閱[結束或無法啟動的 stdio 伺服器](#stdio-servers-that-exit-or-fail-to-start)。
370 370
371#### 遠端伺服器的工作階段中途掉線371#### 遠端伺服器在工作階段中途斷線
372 372
373Claude Code 首先會使用指數退避嘗試重新連接掉線的遠端伺服器，最多五次，從一秒延遲開始，每次加倍：373Claude Code 會先以指數退避嘗試重新連線斷線的遠端伺服器最多五次，從一秒延遲開始，每次加倍：
374 374
375* **在互動式工作階段中**：`/mcp` 在 Claude Code 重新連接時將伺服器顯示為待處理。在五次失敗嘗試後，Claude Code 將伺服器標記為失敗，或在伺服器需要再次授權時標記為需要身分驗證。當它將伺服器標記為失敗時，您會看到 `MCP server "<name>" disconnected · open /mcp to reconnect` 通知。您可以從 `/mcp` 手動重試。375* **在互動式工作階段中**：Claude Code 重新連線時，`/mcp` 會將該伺服器顯示為擱置中。五次嘗試都失敗後，Claude Code 會將該伺服器標示為失敗，或在伺服器需要重新授權時標示為需要身分驗證。標示為失敗時，您會看到 `MCP server "<name>" disconnected · open /mcp to reconnect` 通知。您可以從 `/mcp` 手動重試。
376* **在 [`claude -p`](https://code.claude.com/docs/zh-TW/headless) 執行和 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 工作階段中**：Claude Code 進行相同的五次嘗試，沒有 `/mcp` 面板顯示這些嘗試。如果五次都失敗，執行會在沒有該伺服器工具的情況下繼續：376* **在 [`claude -p`](https://code.claude.com/docs/zh-TW/headless) 執行和 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 工作階段中**：Claude Code 會進行相同的五次嘗試，但沒有 `/mcp` 面板可顯示。若五次都失敗，執行會在沒有該伺服器工具的情況下繼續：
377 * **在暫時性錯誤（例如 5xx 回應或逾時）之後**：Claude Code 會在背景中持續重試 HTTP 或 SSE 伺服器。重試最多持續約半小時，當某次重試連接成功時，伺服器的工具會再次可用。在此之前，Agent SDK 工作階段會回報 [狀態](https://code.claude.com/docs/zh-TW/agent-sdk/mcp.md#error-handling) `failed`，您的程式碼可以 [重新連接伺服器](https://code.claude.com/docs/zh-TW/agent-sdk/mcp.md#error-handling)。若要在 `claude -p` 中重新連接，請重新開始執行。377 * **在暫時性錯誤之後，例如 5xx 回應或逾時**：Claude Code 會在背景持續重試 HTTP 或 SSE 伺服器。重試最多持續約半小時，當其中一次連線成功時，該伺服器的工具會再次變為可用。在此之前，Agent SDK 工作階段會回報[狀態](https://code.claude.com/docs/zh-TW/agent-sdk/mcp.md#error-handling) `failed`，而您的程式碼可以[重新連線該伺服器](https://code.claude.com/docs/zh-TW/agent-sdk/mcp.md#error-handling)。若要在 `claude -p` 中重新連線，請重新開始執行。
378 * **當伺服器 [需要您重新登入](#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-TW/agent-sdk/mcp.md#error-handling)。378 * **當伺服器[需要您重新登入](#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-TW/agent-sdk/mcp.md#error-handling)。
379 379
380#### 失敗的首次連接380#### 第一次連線失敗
381 381
382當 HTTP 或 SSE 伺服器的首次連接因暫時性錯誤（例如 5xx 回應、連接被拒絕或逾時）失敗時，Claude Code 最多重試三次。如果連接仍然失敗，Claude Code 將伺服器標記為失敗。382當 HTTP 或 SSE 伺服器的第一次連線因暫時性錯誤（例如 5xx 回應、連線被拒或逾時）而失敗時，Claude Code 最多會重試三次。若連線仍然失敗，Claude Code 會將該伺服器標示為失敗。
383 383
384這些重試在下列情況下不適用：384這些重試在以下情況不適用：
385 385
386* stdio 伺服器的首次連接。若要再次嘗試，請參閱 [退出或無法啟動的 Stdio 伺服器](#stdio-servers-that-exit-or-fail-to-start)386* stdio 伺服器的第一次連線。若要再試一次，請參閱[結束或無法啟動的 stdio 伺服器](#stdio-servers-that-exit-or-fail-to-start)
387* WebSocket 伺服器的首次連接387* WebSocket 伺服器的第一次連線。若要在互動式終端機工作階段中再試一次，請從 `/mcp` 中該伺服器的選單選取 **Reconnect**
388* 身分驗證或找不到錯誤，因為它需要設定變更才能解決。當 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 是伺服器唯一的 `Authorization` 標頭來源時，Claude Code 仍然重試身分驗證錯誤，因為它在每次嘗試時重新執行助手並可以取得新憑證388* 身分驗證或找不到的錯誤，因為這需要變更設定才能解決。當 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 是伺服器 `Authorization` 標頭的唯一來源時，Claude Code 仍會重試身分驗證錯誤，因為它在每次嘗試時都會重新執行該 helper，並可能取得新的憑證
389 389
390#### 退出或無法啟動的 Stdio 伺服器390#### 結束或無法啟動的 stdio 伺服器
391 391
392若要再次啟動 stdio 伺服器，請閱讀與其發生情況相符的欄。依您執行 Claude Code 的方式找到您的列：互動式工作階段、`claude -p` 執行或 Agent SDK 工作階段。392若要重新啟動 stdio 伺服器，請閱讀符合其發生情況的欄位。請依您執行 Claude Code 的方式找到對應的列：互動式工作階段、`claude -p` 執行或 Agent SDK 工作階段。
393 393
394| 您執行 Claude Code 的方式 | 伺服器的程序在工作階段中途退出 | 伺服器的首次連接失敗 |394| 您執行 Claude Code 的方式 | 伺服器程序在工作階段中途結束 | 伺服器的第一次連線失敗 |
395| - | - | - |395| - | - | - |
396| 互動式工作階段 | Claude Code 將伺服器標記為失敗。若要再次啟動它，請從 `/mcp` 中伺服器的選單選擇 **Reconnect** | Claude Code 將伺服器標記為失敗。若要再次啟動它，請從 `/mcp` 中伺服器的選單選擇 **Reconnect** |396| 互動式工作階段 | Claude Code 將該伺服器標示為失敗。若要重新啟動，請從 `/mcp` 中該伺服器的選單選取 **Reconnect** | Claude Code 將該伺服器標示為失敗。若要重新啟動，請從 `/mcp` 中該伺服器的選單選取 **Reconnect** |
397| `claude -p` 執行 | Claude Code 會在下次 Claude 呼叫該伺服器的其中一個工具時再次啟動伺服器，並在伺服器連接後執行該呼叫 | 執行會在沒有該伺服器工具的情況下繼續。若要讓 Claude Code 再次嘗試連接，請重新開始執行。當外掛提供該伺服器時，新的執行會在失敗後 15 分鐘內跳過連接，因此請先等待這段時間，或 [更早重試](https://code.claude.com/docs/zh-TW/errors.md#skipping-connection-recent-failure-cached) |397| `claude -p` 執行 | Claude Code 會在 Claude 下次呼叫該伺服器的某個工具時重新啟動伺服器，並在伺服器連線後執行該呼叫 | 執行會在沒有該伺服器工具的情況下繼續。若要讓 Claude Code 再次嘗試連線，請重新開始執行。當伺服器由外掛提供時，新的執行會在失敗後 15 分鐘內略過連線，因此請先等待這段時間，或[更早重試](https://code.claude.com/docs/zh-TW/errors.md#skipping-connection-recent-failure-cached) |
398| Agent SDK 工作階段 | Claude Code 會在下次 Claude 呼叫該伺服器的其中一個工具時再次啟動伺服器，並在伺服器連接後執行該呼叫 | 工作階段會在沒有該伺服器工具的情況下繼續。您的程式碼可以 [重新連接伺服器](https://code.claude.com/docs/zh-TW/agent-sdk/mcp.md#error-handling) |398| Agent SDK 工作階段 | Claude Code 會在 Claude 下次呼叫該伺服器的某個工具時重新啟動伺服器，並在伺服器連線後執行該呼叫 | 工作階段會在沒有該伺服器工具的情況下繼續。您的程式碼可以[重新連線該伺服器](https://code.claude.com/docs/zh-TW/agent-sdk/mcp.md#error-handling) |
399 399
400#### 失敗的發現請求400#### 探索請求失敗
401 401
402伺服器連接後，Claude Code 向其傳送功能發現請求，例如 `tools/list`、`prompts/list` 和 `resources/list`。Claude Code 在暫時性網路或伺服器錯誤後使用短退避最多重試這些請求三次。它不重試身分驗證錯誤、4xx 回應或請求逾時。402伺服器連線後，Claude Code 會向其傳送能力探索請求，例如 `tools/list`、`prompts/list` 和 `resources/list`。發生暫時性網路或伺服器錯誤後，Claude Code 會以短暫退避重試這些請求最多三次。它不會重試身分驗證錯誤、4xx 回應或請求逾時。
403 403
404#### 自行重試失敗的伺服器404#### 自行重試失敗的伺服器
405 405
406若要重試所有失敗或需要身分驗證的伺服器，請執行 `/mcp reconnect all`。在互動式終端機中，這需要 Claude Code v2.1.284 或更新版本，較早版本會在該處列印 `MCP server "all" not found`。406若要重試每個失敗或需要身分驗證的伺服器，請在互動式終端機工作階段的 Claude Code 提示字元執行 `/mcp reconnect all`。這需要 Claude Code v2.1.284 或更新版本。較早的版本會印出 `MCP server "all" not found`。
407 407
408#### Claude 如何了解伺服器失敗408#### Claude 如何得知伺服器失敗
409 409
410Claude Code 是否告訴 Claude 關於失敗連接的已設定伺服器取決於 [工具搜尋](#scale-with-mcp-tool-search)（預設開啟）：410Claude Code 是否會告知 Claude 某個已設定的伺服器連線失敗，取決於[工具搜尋](#scale-with-mcp-tool-search)，該功能預設為開啟：
411 411
412* 使用工具搜尋，Claude Code 告訴 Claude 哪個伺服器失敗及其連接錯誤，因此 Claude 在其回應中報告連接失敗。Claude Code 在找不到符合工具的 `ToolSearch` 結果中包含相同的資訊。412* 使用工具搜尋時，Claude Code 會告知 Claude 哪個伺服器失敗及其連線錯誤，因此 Claude 會在其回應中回報連線失敗。Claude Code 也會在找不到相符工具的 `ToolSearch` 結果中包含相同的資訊。
413* 在任何 [沒有工具搜尋的設定](#configure-tool-search)中，Claude Code 不向 Claude 報告失敗的伺服器連接。413* 在任何[不使用工具搜尋的設定](#configure-tool-search)中，Claude Code 不會向 Claude 回報失敗的伺服器連線。
414 414
415### 使用頻道推送訊息415### 使用頻道推送訊息
416 416
417MCP 伺服器也可以直接將訊息推送到您的工作階段，以便 Claude 可以對外部事件（如 CI 結果、監控警報或聊天訊息）做出反應。若要啟用此功能，您的伺服器宣告 `claude/channel` 功能，您在啟動時使用 `--channels` 旗標選擇加入。請參閱 [頻道](https://code.claude.com/docs/zh-TW/channels.md)以使用官方支援的頻道，或 [頻道參考](https://code.claude.com/docs/zh-TW/channels-reference.md)以建立您自己的。417MCP 伺服器也可以直接將訊息推送到您的工作階段中，讓 Claude 能對外部事件做出反應，例如 CI 結果、監控警示或聊天訊息。若要啟用此功能，您的伺服器需宣告 `claude/channel` 能力，並由您在啟動時以 `--channels` 旗標選擇加入。請參閱[頻道](https://code.claude.com/docs/zh-TW/channels.md)以使用官方支援的頻道，或參閱[頻道參考](https://code.claude.com/docs/zh-TW/channels-reference.md)以建立您自己的頻道。
418 418
419在 [v2 執行時](#mcp-client-runtimes)上，協商 MCP 協議修訂 2026-07-28 的頻道伺服器無法傳遞頻道訊息，因此 Claude Code 不會將其註冊為頻道。不支援該修訂的頻道伺服器會在較早的握手上連接，並如以往一樣註冊。419在 [v2 執行環境](#mcp-client-runtimes)上，協商使用 MCP 協定修訂版 2026-07-28 的頻道伺服器無法傳遞頻道訊息，因此 Claude Code 不會將其註冊為頻道。不支援該修訂版的頻道伺服器會以較早的交握方式連線，並如往常一樣註冊。
420 420
421Claude Code 預設會向 stdio 伺服器詢問該修訂。若要將 stdio 頻道伺服器保持在較早的握手上，請設定 [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/zh-TW/env-vars) 為 `legacy`，這會將每個伺服器都保持在較早的握手上。421Claude Code 預設會向 stdio 伺服器要求該修訂版。若要讓 stdio 頻道伺服器維持使用較早的交握方式，請將 [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/zh-TW/env-vars) 設為 `legacy`，這會讓所有伺服器都維持使用較早的交握方式。
422 422
423> [!TIP]423> [!TIP]
424>424>
425> 提示：425> 提示：
426>426>
427> * 使用 `-s` 或 `--scope` 旗標指定設定的儲存位置：427> * 使用 `-s` 或 `--scope` 旗標指定設定的儲存位置：
428> * `local`（預設）：僅在目前專案中對您可用428> * `local`（預設）：僅在目前專案中供您使用
429> * `project`：透過 `.mcp.json` 檔案與專案中的每個人共享429> * `project`：透過 `.mcp.json` 檔案與專案中的所有人共用
430> * `user`：在所有專案中對您可用430> * `user`：在所有專案中供您使用
431> * 使用 `-e` 或 `--env` 旗標設定環境變數（例如 `-e KEY=value`）431> * 使用 `-e` 或 `--env` 旗標設定環境變數（例如 `-e KEY=value`）
432> * `--transport` 和 `--header` 旗標也接受 `-t` 和 `-H` 短形式432> * `--transport` 和 `--header` 旗標也接受 `-t` 和 `-H` 簡寫形式
433> * 使用 `MCP_TIMEOUT` 環境變數設定 MCP 伺服器啟動逾時（例如 `MCP_TIMEOUT=10000 claude` 設定 10 秒逾時）433> * 使用 `MCP_TIMEOUT` 環境變數設定 MCP 伺服器啟動逾時（例如 `MCP_TIMEOUT=10000 claude` 會設定 10 秒逾時）
434> * 透過將 `timeout` 欄位（以毫秒為單位）新增到該伺服器的 `.mcp.json` 項目來設定按伺服器工具執行逾時，例如 `"timeout": 600000` 表示十分鐘。這僅針對該伺服器覆寫 `MCP_TOOL_TIMEOUT` 環境變數434> * 在該伺服器的 `.mcp.json` 項目中加入以毫秒為單位的 `timeout` 欄位，即可為個別伺服器設定工具執行逾時，例如 `"timeout": 600000` 代表十分鐘。這只會針對該伺服器覆寫 `MCP_TOOL_TIMEOUT` 環境變數
435> * 當 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)435> * 當 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)
436> * 使用 `/mcp` 對需要 OAuth 2.0 身分驗證的遠端伺服器進行驗證436> * 使用 `/mcp` 向需要 OAuth 2.0 身分驗證的遠端伺服器進行身分驗證
437 437
438### MCP 工具呼叫的時間限制438### MCP 工具呼叫的時間限制
439 439
440若要限制 MCP 工具呼叫可執行的時間：440若要限制 MCP 工具呼叫可執行的時間長度：
441 441
442* **各伺服器**：在該伺服器的設定項目中加入以毫秒為單位的 `timeout` 欄位442* **個別伺服器**：在該伺服器的設定項目中加入以毫秒為單位的 `timeout` 欄位
443* **跨伺服器**：設定 [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/zh-TW/env-vars)443* **所有伺服器**：設定 [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/zh-TW/env-vars)
444 444
445按伺服器 `timeout` 是每個工具呼叫的硬牆鐘限制，來自伺服器的進度通知不會延長它。低於 1000 的值被忽略並落回 `MCP_TOOL_TIMEOUT`，或在該變數未設定時落回其約 28 小時的預設值。對於 HTTP、SSE 或 [claude.ai 連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai)伺服器，還有第二個按請求計時器，涵蓋每個請求到伺服器的第一個回應位元組。Claude Code 將該計時器設定為三個值中最大的：60 秒、適用於伺服器的工具逾時和 `MCP_TIMEOUT`。未設定 `MCP_TOOL_TIMEOUT` 的 28 小時預設值不進入該比較，低於 60 秒的值不會縮短計時器。Stdio 和 WebSocket 伺服器沒有按請求計時器。445個別伺服器的 `timeout` 是每次工具呼叫的硬性實際時間限制，伺服器的進度通知不會延長它。低於 1000 的值會被忽略，並改用 `MCP_TOOL_TIMEOUT`，若該變數未設定，則改用其約 28 小時的預設值。對於 HTTP、SSE 或 [claude.ai 連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai)伺服器，還有第二個針對每個請求的計時器，涵蓋每個請求直到收到伺服器的第一個回應位元組為止。Claude Code 會將該計時器設為三個值中的最大值：60 秒、適用於該伺服器的工具逾時，以及 `MCP_TIMEOUT`。未設定 `MCP_TOOL_TIMEOUT` 時的 28 小時預設值不會納入該比較，且低於 60 秒的值不會縮短該計時器。Stdio 和 WebSocket 伺服器沒有針對每個請求的計時器。
446 446
447至少 1000 的按伺服器 `timeout` 也充當下面描述的空閒逾時的下限：Claude Code 永遠不會因空閒而早於按伺服器 `timeout` 中止該伺服器的工具呼叫。447至少為 1000 的個別伺服器 `timeout` 也會作為下述閒置逾時的下限：Claude Code 絕不會比個別伺服器的 `timeout` 更早因閒置而中止該伺服器的工具呼叫。
448 448
449對 MCP 伺服器的工具呼叫，在空閒視窗內不傳送回應且不傳送進度通知，會因錯誤而中止，而不是等待牆鐘限制。空閒逾時適用於除 IDE 伺服器和 SDK 進程內伺服器外的每個伺服器類型。空閒視窗預設為 HTTP、SSE、WebSocket 和 [claude.ai 連接器](#use-mcp-servers-from-claude-ai)伺服器的五分鐘，以及 stdio 伺服器的 30 分鐘。449若 MCP 伺服器在閒置時間範圍內沒有傳送任何回應或進度通知，對其的工具呼叫會以錯誤中止，而不是等到實際時間限制。閒置逾時適用於 IDE 伺服器和 SDK 行程內伺服器以外的所有伺服器類型。閒置時間範圍預設為：HTTP、SSE、WebSocket 和 [claude.ai 連接器](#use-mcp-servers-from-claude-ai)伺服器為五分鐘，stdio 伺服器為 30 分鐘。
450 450
451以毫秒為單位設定 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/zh-TW/env-vars) 環境變數以變更空閒視窗，或設定為 `0` 以停用檢查。451請以毫秒為單位設定 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/zh-TW/env-vars) 環境變數來變更閒置時間範圍，或將其設為 `0` 以停用此檢查。
452 452
453這些逾時限制呼叫可以執行多長時間，不總是它阻止工作階段多長時間：執行超過兩分鐘的主對話呼叫首先移動到背景任務。請參閱 [長工具呼叫的自動背景化](#automatic-backgrounding-of-long-tool-calls)。453這些逾時限制的是呼叫可以執行多久，而不一定是它會阻擋工作階段多久：執行超過兩分鐘的主要對話呼叫會先移至背景任務。請參閱[長時間工具呼叫的自動背景化](#automatic-backgrounding-of-long-tool-calls)。
454 454
455### 長工具呼叫的自動背景化455### 長時間工具呼叫的自動背景化
456 456
457若背景呼叫在 [`/tasks`](https://code.claude.com/docs/zh-TW/commands#all-commands) 中的詳細檢視顯示 `runs on the server; survives exiting this session`，請參閱[在伺服器上執行的 MCP 任務](#mcp-tasks-that-run-on-the-server)。457若背景呼叫在 [`/tasks`](https://code.claude.com/docs/zh-TW/commands#all-commands) 中的詳細資訊檢視顯示 `runs on the server; survives exiting this session`，請參閱[在伺服器上執行的 MCP 任務](#mcp-tasks-that-run-on-the-server)。
458 458
459主對話中仍在執行兩分鐘後的 MCP 工具呼叫移動到背景任務，而不是阻止工作階段。Claude 立即接收任務 ID 並繼續工作，結果在呼叫解決時作為任務通知到達。459主要對話中的 MCP 工具呼叫若在兩分鐘後仍在執行，會移至背景任務，而不會阻擋工作階段。Claude 會立即收到任務 ID 並繼續工作，呼叫結束時，結果會以任務通知的形式送達。
460 460
461任務出現在 [`/tasks`](https://code.claude.com/docs/zh-TW/commands#all-commands)中，您也可以在其中停止它，它不會在退出工作階段時存活。任務的項目顯示伺服器報告的最新進度。如果您停止任務，Claude Code 會取消該呼叫並告知 Claude 不會有結果。停止並不保證伺服器會停止：它可能已經完成部分工作，或仍可能完成它。461該任務會出現在 [`/tasks`](https://code.claude.com/docs/zh-TW/commands#all-commands) 中，您也可以在那裡停止它，且它不會在結束工作階段後延續。任務的項目會顯示伺服器回報的最新進度。若您停止任務，Claude Code 會取消呼叫並告知 Claude 不會有結果。停止並不保證伺服器會停止：它可能已完成部分工作，或仍可能完成它。
462 462
463按呼叫限制仍然適用於呼叫在背景中執行時：由按伺服器 `timeout` 或 [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/zh-TW/env-vars)設定的牆鐘限制，以及由 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/zh-TW/env-vars)設定的空閒逾時。463呼叫在背景執行時，每次呼叫的限制仍然適用：由個別伺服器 `timeout` 或 [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/zh-TW/env-vars) 設定的實際時間限制，以及由 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/zh-TW/env-vars) 設定的閒置逾時。
464 464
465若要變更或關閉自動背景化：465若要變更或關閉自動背景化：
466 466
467* 設定以毫秒為單位的 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/zh-TW/env-vars) 環境變數以變更門檻，或設為 `0` 以關閉自動背景化。設為 `0` 時，Claude 在互動式工作階段中也會[等待 MCP 任務](#make-claude-wait-for-the-result-of-an-mcp-task)467* 以毫秒為單位設定 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/zh-TW/env-vars) 環境變數來變更閾值，或將其設為 `0` 以關閉自動背景化。設為 `0` 時，Claude 在互動式工作階段中也會[等待 MCP 任務](#make-claude-wait-for-the-result-of-an-mcp-task)
468* 將 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/zh-TW/env-vars) 設為 `1`，這會將其與背景命令和背景 subagent 一併關閉468* 將 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/zh-TW/env-vars) 設為 `1`，這會將其與背景命令和背景 subagent 一併關閉
469 469
470某些呼叫永遠不會移動到背景：470有些呼叫永遠不會移至背景：
471 471
472* 來自 [subagent](https://code.claude.com/docs/zh-TW/sub-agents.md) 的呼叫；Claude Code 只背景化主對話呼叫472* 來自 [subagent](https://code.claude.com/docs/zh-TW/sub-agents.md) 的呼叫；Claude Code 只會將主要對話的呼叫背景化
473* 對 IDE 伺服器的呼叫473* 對 IDE 伺服器的呼叫
474* 在 [非互動模式](https://code.claude.com/docs/zh-TW/headless.md)中的呼叫，除非 `CLAUDE_AUTO_BACKGROUND_TASKS` 設定為 `1`，因為一次性執行可能在結果到達之前結束474* [非互動模式](https://code.claude.com/docs/zh-TW/headless.md)中的呼叫，除非 `CLAUDE_AUTO_BACKGROUND_TASKS` 設為 `1`，因為單次執行可能在結果送達前就結束
475 475
476等待開啟 [引出對話](#respond-to-mcp-elicitation-requests)的呼叫在對話開啟時不會背景化；伺服器被阻止在您的輸入上，而不是緩慢，因此 Claude Code 將移動延遲到對話關閉。476等待開啟中之[引導對話框](#respond-to-mcp-elicitation-requests)的呼叫，在對話框開啟期間不會被背景化；伺服器是在等待您的輸入，而不是速度慢，因此 Claude Code 會將移動延後至對話框關閉為止。
477 477
478### 在伺服器上執行的 MCP 任務478### 在伺服器上執行的 MCP 任務
479 479
480MCP 任務是 MCP 伺服器使用 [MCP tasks 擴充功能](https://modelcontextprotocol.io/extensions/tasks/overview)自行執行的長時間工作，例如報表匯出或建置。伺服器接受工作後，Claude 的工具呼叫就會傳回，因此 Claude 會繼續工作，除非您[讓 Claude 等待](#make-claude-wait-for-the-result-of-an-mcp-task)。工作結束時，逐字稿會註明，且 Claude 會取得結果。請向 Claude 詢問結果。480MCP 任務是 MCP 伺服器使用 [MCP tasks 擴充功能](https://modelcontextprotocol.io/extensions/tasks/overview)自行執行的長時間工作，例如報表匯出或建置。伺服器一接受該工作，Claude 的工具呼叫就會返回，因此除非您[讓 Claude 等待](#make-claude-wait-for-the-result-of-an-mcp-task)，否則 Claude 會繼續工作。工作結束時，逐字稿會顯示此情況，而 Claude 會取得結果。請向 Claude 詢問結果。
481 481
482在此期間，頁尾會顯示如 `1 MCP task` 的計數，Claude Code 會透過向伺服器檢查狀態來追蹤任務。遠端伺服器上的任務在您結束後仍會繼續執行。若要再次追蹤它，請[恢復同一個工作階段](#exit-clear-or-resume-while-an-mcp-task-runs)。482在此期間，頁尾會顯示如 `1 MCP task` 的計數，而 Claude Code 會透過向伺服器檢查其狀態來追蹤該任務。遠端伺服器上的任務在您結束後仍會繼續執行。若要再次追蹤它，請[恢復同一個工作階段](#exit-clear-or-resume-while-an-mcp-task-runs)。
483 483
484> [!NOTE]484> [!NOTE]
485>485>
486> MCP 任務在 Claude Code CLI 中為公開測試版，需要 Claude Code v2.1.304 或更新版本。[呼叫成為 MCP 任務所需的條件](#requirements-for-mcp-tasks)列出了可取得此功能的工作階段和伺服器。486> MCP 任務在 Claude Code CLI 中處於公開測試版階段，需要 Claude Code v2.1.304 或更新版本。[呼叫成為 MCP 任務的條件](#requirements-for-mcp-tasks)列出了可使用它們的工作階段與伺服器。
487 487
488#### 停止 MCP 任務或取得其結果488#### 停止 MCP 任務或取得其結果
489 489
490若要停止執行中的任務，請在 [`/tasks`](https://code.claude.com/docs/zh-TW/commands#all-commands) 中選取它並按下 `x`，或請 Claude 停止。Claude Code 會停止追蹤該任務並要求伺服器取消，但伺服器仍可能將其完成。請先從 `/mcp` 重新連線已中斷連線的伺服器，否則不會送出取消請求，且 Claude Code 會遺忘該任務而無法再次追蹤。按下 `Esc` 不會停止背景任務。490若要停止執行中的任務，請在 [`/tasks`](https://code.claude.com/docs/zh-TW/commands#all-commands) 中選取它並按下 `x`，或請 Claude 停止它。Claude Code 會停止追蹤該任務並要求伺服器取消它，但伺服器仍可能完成它。請先從 `/mcp` 重新連線已中斷連線的伺服器，否則不會送出取消請求，且 Claude Code 會遺忘該任務而無法再次追蹤它。按下 `Esc` 不會停止背景任務。
491 491
492任務結束時，逐字稿中會出現如下的一行：492任務結束時，逐字稿中會出現如下的一行：
493 493
495MCP task <server task id> (<server>/<tool>) completed.495MCP task <server task id> (<server>/<tool>) completed.
496```496```
497 497
498結果會傳給 Claude，而非寫入逐字稿，因此請向 Claude 詢問結果。若結果送達時 Claude 處於閒置狀態，Claude 會主動開始處理。498結果會傳給 Claude，而不是寫入逐字稿，因此請向 Claude 詢問結果。若結果送達時 Claude 處於閒置狀態，Claude 會主動開始處理它。
499 499
500#### 回答 MCP 任務提出的問題500#### 回答來自 MCP 任務的問題
501 501
502執行中的任務可以開啟 [elicitation 對話框](#respond-to-mcp-elicitation-requests)來要求您輸入。`/tasks` 開啟期間，對話框會保持隱藏，因此請關閉 `/tasks` 以進行回答。拒絕或按下 `Esc` 也是對伺服器的回答，伺服器接著會決定任務是否繼續。502執行中的任務可以開啟[引導對話框](#respond-to-mcp-elicitation-requests)來要求您輸入。當 `/tasks` 開啟時，對話框會保持隱藏，因此請關閉 `/tasks` 以作答。拒絕或按下 `Esc` 也是對伺服器的一種回答，伺服器隨後會決定任務是否繼續。
503 503
504在[非互動](https://code.claude.com/docs/zh-TW/headless.md)工作階段中，Claude Code 會要求伺服器取消請求輸入的任務，而不會執行您的 [`Elicitation` hook](https://code.claude.com/docs/zh-TW/hooks#elicitation) 或呼叫 Agent SDK 的 `onElicitation` 回呼。504在[非互動](https://code.claude.com/docs/zh-TW/headless.md)工作階段中，Claude Code 會要求伺服器取消要求輸入的任務，而不會執行您的 [`Elicitation` hook](https://code.claude.com/docs/zh-TW/hooks#elicitation) 或呼叫 Agent SDK 的 `onElicitation` 回呼。
505 505
506#### 在 MCP 任務執行期間結束、清除或恢復506#### 在 MCP 任務執行期間結束、清除或恢復
507 507
508遠端伺服器上的任務在您結束後仍會繼續執行。stdio 伺服器的程序會在 Claude Code 結束時停止，儘管其任務在 `/tasks` 中顯示 `runs on the server; survives exiting this session`。除非該伺服器的文件說明工作會在程序結束後持續，否則請先讓這些任務完成，或在 `/tasks` 中將其停止。508遠端伺服器上的任務在您結束後仍會繼續執行。stdio 伺服器的程序會在 Claude Code 結束時停止，儘管其任務在 `/tasks` 中顯示 `runs on the server; survives exiting this session`。除非該伺服器的文件表示工作會在程序結束後延續，否則請先讓這些任務完成，或在 `/tasks` 中停止它們。
509 509
510| 情況 | 任務會發生什麼事 | 您可以做什麼 |510| 情況 | 任務會發生什麼事 | 您可以做什麼 |
511| - | - | - |511| - | - | - |
512| 您執行 `/clear` 或 `/branch`，或以 `/resume` 切換到另一個工作階段 | 只要 Claude Code 保持開啟，結果就會送達您目前的對話 | 結束後，以 `claude --resume` 恢復任務開始時所在的工作階段 |512| 您執行 `/clear` 或 `/branch`，或 `/resume` 另一個工作階段 | 只要 Claude Code 保持開啟，結果就會送達您目前的對話 | 結束之後，使用 `claude --resume` 恢復任務開始時所在的工作階段 |
513| 您結束 Claude Code | 沒有任何結束選項會取消遠端伺服器的任務，即使結束對話框將其列在 `The following will stop when you exit:` 之下 | 先在 `/tasks` 中停止它，或稍後恢復同一個工作階段 |513| 您結束 Claude Code | 沒有任何結束選項會取消遠端伺服器的任務，即使結束對話框將其列在 `The following will stop when you exit:` 之下 | 先在 `/tasks` 中停止它，或稍後恢復同一個工作階段 |
514| 您以互動方式返回任務的工作階段：`claude --resume`、`claude --continue` 或 `/resume` | 伺服器連線後，Claude Code 會再次追蹤該任務，若任務在此期間已完成且伺服器仍記得它，Claude 會取得結果 | 保持伺服器的名稱和連線設定不變 |514| 您以互動方式回到任務的工作階段：`claude --resume`、`claude --continue` 或 `/resume` | 伺服器連線後，Claude Code 會再次追蹤該任務；若任務在此期間已完成且伺服器仍知道它，Claude 會取得結果 | 保持伺服器的名稱和連線設定不變 |
515| 您在單次 `claude -p "<prompt>"` 執行中以 `--resume` 或 `--continue` 恢復任務的工作階段 | 該次執行不會追蹤任務 | 以互動方式恢復，或使用 `--input-format stream-json` |515| 您在單次 `claude -p "<prompt>"` 執行中使用 `--resume` 或 `--continue` 恢復任務的工作階段 | 該執行不會追蹤該任務 | 以互動方式恢復，或使用 `--input-format stream-json` 恢復 |
516| 您開始新的工作階段或使用 `--fork-session` | 新的工作階段不會追蹤任務 | 恢復啟動該任務的工作階段 |516| 您開始新的工作階段或使用 `--fork-session` | 新的工作階段不會追蹤該任務 | 恢復啟動該任務的工作階段 |
517 517
518#### 呼叫成為 MCP 任務所需的條件518#### 呼叫成為 MCP 任務的條件
519 519
520只有在以下所有條件都成立時，工具呼叫才會成為 MCP 任務：520只有在以下所有條件都成立時，工具呼叫才會成為 MCP 任務：
521 521
522* 伺服器支援任務522* 伺服器支援任務
523* 伺服器是以[協定修訂版 2026-07-28](#mcp-client-runtimes) 連線的 HTTP、stdio 或 claude.ai 連接器伺服器。設定 [`MCP_SDK_GENERATION=v1` 或 `MCP_PROTOCOL_NEGOTIATION=legacy`](https://code.claude.com/docs/zh-TW/env-vars) 會排除此情況523* 伺服器是以[協定修訂版 2026-07-28](#mcp-client-runtimes) 連線的 HTTP、stdio 或 claude.ai 連接器伺服器。設定 [`MCP_SDK_GENERATION=v1` 或 `MCP_PROTOCOL_NEGOTIATION=legacy`](https://code.claude.com/docs/zh-TW/env-vars) 會排除此情況
524* 工作階段會[擷取功能旗標](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)，因此不能在 Amazon Bedrock 等第三方供應商上，也不能關閉遙測或旗標擷取524* 工作階段會[擷取功能旗標](https://code.claude.com/docs/zh-TW/env-vars.md#features-that-need-feature-flag-fetching)，因此不能在 Amazon Bedrock 等第三方供應商上，也不能關閉遙測或旗標擷取
525* Anthropic 已為您的工作階段類型開啟 MCP 任務。在 v2.1.304 或更新版本上，涵蓋終端機 CLI 工作階段、[Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 工作階段和 [GitHub Actions](https://code.claude.com/docs/zh-TW/github-actions.md) 執行。其他使用介面，例如 [VS Code 擴充功能](https://code.claude.com/docs/zh-TW/vs-code.md)和[桌面應用程式](https://code.claude.com/docs/zh-TW/desktop.md)，沒有 MCP 任務525* Anthropic 已為您這類工作階段開啟 MCP 任務。在 v2.1.304 或更新版本上，這涵蓋終端機 CLI 工作階段、[Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 工作階段和 [GitHub Actions](https://code.claude.com/docs/zh-TW/github-actions.md) 執行。其他使用介面，例如 [VS Code 擴充功能](https://code.claude.com/docs/zh-TW/vs-code.md)和[桌面應用程式](https://code.claude.com/docs/zh-TW/desktop.md)，沒有 MCP 任務
526* 呼叫來自主對話，而非來自 [subagent](https://code.claude.com/docs/zh-TW/sub-agents.md)526* 呼叫來自主要對話，而非來自 [subagent](https://code.claude.com/docs/zh-TW/sub-agents.md)
527* 工作階段為互動式，或者 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 工作階段或讀取 `--input-format stream-json` 的 `claude -p` 執行具備：527* 工作階段是互動式的，或者 [Agent SDK](https://code.claude.com/docs/zh-TW/agent-sdk/overview.md) 工作階段或讀取 `--input-format stream-json` 的 `claude -p` 執行具備：
528 * [`CLAUDE_AUTO_BACKGROUND_TASKS`](https://code.claude.com/docs/zh-TW/env-vars) 為 `1`528 * [`CLAUDE_AUTO_BACKGROUND_TASKS`](https://code.claude.com/docs/zh-TW/env-vars) 為 `1`
529 * `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND` 不為 `1`529 * `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND` 不為 `1`
530 * `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` 不為 `0`530 * `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` 不為 `0`
531 531
532任何其他呼叫都是一般的工具呼叫，[長時間工具呼叫的自動背景化](#automatic-backgrounding-of-long-tool-calls)說明了其中哪些會移至背景。532其他任何呼叫都是一般的工具呼叫，而[長時間工具呼叫的自動背景化](#automatic-backgrounding-of-long-tool-calls)說明了其中哪些會移至背景。
533 533
534請保持 Agent SDK 或 stream-json 工作階段的輸入開啟，因為輸入關閉後，執行[不會等待 MCP 任務](https://code.claude.com/docs/zh-TW/headless.md#mcp-work-when-a-non-interactive-run-ends)。單次 `claude -p "<prompt>"` 執行不會取得 MCP 任務。534請保持 Agent SDK 或 stream-json 工作階段的輸入開啟，因為輸入關閉後，執行[不會等待 MCP 任務](https://code.claude.com/docs/zh-TW/headless.md#mcp-work-when-a-non-interactive-run-ends)。單次 `claude -p "<prompt>"` 執行不會取得 MCP 任務。
535 535
536#### MCP 任務上的狀態訊息536#### MCP 任務上的狀態訊息
537 537
538這些訊息出現在任務的 `/tasks` 項目或其結束時的逐字稿行中，表示 Claude Code 無法連絡伺服器或任務。當其中一則訊息顯示在 `/tasks` 中時，工作可能仍在執行：Claude Code 不會干預它，並會持續檢查。`300s` 和設定相關的訊息即使在恢復連絡後仍會保留在項目上。538這些訊息出現在任務的 `/tasks` 項目或其結束的逐字稿行中，表示 Claude Code 無法連繫到伺服器或任務。當其中一則顯示在 `/tasks` 中時，該工作可能仍在執行：Claude Code 不會干預它，並持續檢查。`300s` 和設定相關的訊息即使在恢復聯繫後仍會保留在項目上。
539 539
540| 訊息 | 發生了什麼事 | 您可以做什麼 |540| 訊息 | 發生了什麼事 | 您可以做什麼 |
541| - | - | - |541| - | - | - |
542| `reconnecting…` | 自恢復以來伺服器尚未回應，或狀態檢查沒有得到回應 | 若持續出現，請從 `/mcp` 重新連線 |542| `reconnecting…` | 恢復後伺服器尚未回應，或狀態檢查沒有得到回應 | 若持續顯示，請從 `/mcp` 重新連線 |
543| `needs a sign-in to <server>` | 伺服器拒絕了狀態檢查 | 從 `/mcp` 登入 |543| `needs a sign-in to <server>` | 伺服器拒絕了狀態檢查 | 從 `/mcp` 登入 |
544| `status requests come back with errors; retrying…` | 伺服器或其前方的代理伺服器以錯誤回應狀態檢查 | 在 Claude Code 重試期間等待 |544| `status requests come back with errors; retrying…` | 伺服器或其前方的代理伺服器以錯誤回應狀態檢查 | 在 Claude Code 重試時等待 |
545| `server '<name>' did not reconnect within 300s` | 五分鐘內沒有任何檢查得到回應，例如連線中斷或伺服器已停用 | 從 `/mcp` 重新連線 |545| `server '<name>' did not reconnect within 300s` | 五分鐘內沒有任何得到回應的檢查，例如連線中斷或伺服器已停用 | 從 `/mcp` 重新連線 |
546| `server '<name>' asked for a sign-in, and none was accepted within 300s` | 五分鐘後伺服器仍要求登入 | 從 `/mcp` 登入 |546| `server '<name>' asked for a sign-in, and none was accepted within 300s` | 五分鐘後伺服器仍要求登入 | 從 `/mcp` 登入 |
547| `status requests to server '<name>' came back with errors, and none succeeded in 300s` | 五分鐘內都是錯誤回應 | 檢查伺服器本身的健康狀態或日誌 |547| `status requests to server '<name>' came back with errors, and none succeeded in 300s` | 五分鐘內都是錯誤回應 | 檢查伺服器本身的健康狀態或日誌 |
548| `server '<name>' is not configured in this session; the task may still be running on it` | 工作階段中沒有該名稱的伺服器，例如它已被移除、重新命名或未包含在 `--mcp-config` 中，或 claude.ai 連接器仍在載入中 | 以相同名稱還原伺服器，然後再次恢復工作階段。若是載入中的連接器，則無需任何操作：連接器出現後，Claude Code 就會追蹤該任務 |548| `server '<name>' is not configured in this session; the task may still be running on it` | 工作階段中沒有該名稱的伺服器，例如它已被移除、重新命名或未包含在 `--mcp-config` 中，或 claude.ai 連接器仍在載入 | 以相同名稱還原該伺服器，然後再次恢復工作階段。若是載入中的連接器，則無需任何操作：連接器出現後，Claude Code 就會追蹤該任務 |
549| 以 `server '<name>' was reconfigured to a different transport since this task was created` 開頭的訊息 | 存在該名稱的伺服器，但其連線設定在任務開始後已變更，例如其 URL、command、args、env、headers 或 timeout | 還原先前的設定，然後再次恢復工作階段 |549| 以 `server '<name>' was reconfigured to a different transport since this task was created` 開頭的訊息 | 存在該名稱的伺服器，但其連線設定自任務開始後已變更，例如其 URL、command、args、env、headers 或 timeout | 還原先前的設定，然後再次恢復工作階段 |
550| `the server rejected this task's id; asking again…` | 伺服器表示不認得該任務 ID。Claude Code 會持續詢問最多五分鐘 | 等待：若伺服器再次認得該 ID，訊息就會清除，否則會接著出現 `outcome unknown.` 行 |550| `the server rejected this task's id; asking again…` | 伺服器表示它不認識該任務 ID。Claude Code 會持續詢問最多五分鐘 | 等待：若伺服器再次識別該 ID，訊息就會清除，否則接著會出現 `outcome unknown.` 行 |
551| 以 `outcome unknown.` 結尾的逐字稿行，其中一種形式為 `expired on the server: outcome unknown.` | 伺服器拒絕了該 ID 或以其他永久性錯誤拒絕，且 Claude Code 已停止追蹤該任務 | 第二次呼叫可能會重複工作。再次呼叫該工具之前，請向伺服器確認已完成的內容，例如請 Claude 使用該伺服器的其他工具 |551| 以 `outcome unknown.` 結尾的逐字稿行，其中一種形式為 `expired on the server: outcome unknown.` | 伺服器拒絕了該 ID 或以其他永久性錯誤拒絕，且 Claude Code 已停止追蹤該任務 | 第二次呼叫可能會重複該工作。再次呼叫該工具之前，請向伺服器確認已完成的內容，例如請 Claude 使用該伺服器的其他工具 |
552 552
553#### MCP 任務的時間限制553#### MCP 任務的時間限制
554 554
555預設情況下，背景中的任務沒有 Claude Code 時間限制。[工具呼叫時間限制](#time-limits-on-mcp-tool-calls)，包括實際時間限制和閒置逾時，會在伺服器以任務回應呼叫之前適用。若您[讓 Claude 等待](#make-claude-wait-for-the-result-of-an-mcp-task)，這些限制會在整個任務期間適用。得到回應的狀態檢查會計為閒置逾時的活動。555預設情況下，背景中的任務沒有 Claude Code 時間限制。[工具呼叫時間限制](#time-limits-on-mcp-tool-calls)（包括實際時間限制和閒置逾時）在伺服器以任務回應該呼叫之前適用。若您[讓 Claude 等待](#make-claude-wait-for-the-result-of-an-mcp-task)，這些限制會在整個任務期間適用。得到回應的狀態檢查會計為閒置逾時的活動。
556 556
557#### 讓 Claude 等待 MCP 任務的結果557#### 讓 Claude 等待 MCP 任務的結果
558 558
559若要在互動式工作階段中讓 Claude 等待任務的結果，請設定兩個環境變數之一，例如在 [`settings.json`](https://code.claude.com/docs/zh-TW/settings) 的 `env` 區塊中：559若要讓 Claude 在互動式工作階段中等待任務的結果，請設定以下兩個環境變數之一，例如在 [`settings.json`](https://code.claude.com/docs/zh-TW/settings) 的 `env` 區塊中：
560 560
561* **將 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/zh-TW/env-vars) 設為 `0`**：Claude 會等待每個 MCP 工具呼叫直到呼叫結束561* **[`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/zh-TW/env-vars) 設為 `0`**：Claude 會等待每個 MCP 工具呼叫直到呼叫結束
562* **將 [`CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`](https://code.claude.com/docs/zh-TW/env-vars) 設為 `1`**：Claude 會等待任務的結果。當[自動背景化](#automatic-backgrounding-of-long-tool-calls)開啟時，它預設會在兩分鐘後移動呼叫，因此短任務會就地完成，而長任務不會阻擋您。被移動的呼叫是一般的背景呼叫，而非 MCP 任務。它不會在結束工作階段後保留562* **[`CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`](https://code.claude.com/docs/zh-TW/env-vars) 設為 `1`**：Claude 會等待任務的結果。當[自動背景化](#automatic-backgrounding-of-long-tool-calls)開啟時，它預設會在兩分鐘後移動該呼叫，因此短任務會就地完成，長任務則不會阻擋您。被移動的呼叫是一般的背景呼叫，而非 MCP 任務。它不會在結束工作階段後延續
563 563
564Claude 等待期間，按下 `Esc` 或達到[實際時間限制或閒置逾時](#time-limits-on-mcp-tasks)會結束呼叫，且 Claude Code 會要求伺服器取消任務。564在 Claude 等待期間，按下 `Esc` 或達到[實際時間限制或閒置逾時](#time-limits-on-mcp-tasks)都會結束該呼叫，且 Claude Code 會要求伺服器取消該任務。
565 565
566若您將 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 設為 `1` 或以 [bare 模式](https://code.claude.com/docs/zh-TW/headless.md#start-faster-with-bare-mode)啟動，單憑這樣並不會讓 Claude 等待 MCP 任務。此範例將 `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` 設為 `0`，因此 Claude 會等待每個 MCP 工具呼叫：566若您將 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 設為 `1` 或以 [bare 模式](https://code.claude.com/docs/zh-TW/headless.md#start-faster-with-bare-mode)啟動，僅此並不會讓 Claude 等待 MCP 任務。此範例將 `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` 設為 `0`，因此 Claude 會等待每個 MCP 工具呼叫：
567 567
568```json settings.json theme={null}568```json settings.json theme={null}
569{569{
573}573}
574```574```
575 575
576### 給伺服器作者的 MCP 任務說明576### 供伺服器作者參考的 MCP 任務
577 577
578若您建置 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` 請求會省略該擴充功能。578若您建置 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` 請求會省略該擴充功能。
579 579
580#### 以任務回應呼叫580#### 以任務回應呼叫
581 581
582只有在請求攜帶該擴充功能時才以任務回應，否則 Claude 會收到工具錯誤 `Unsupported result type 'task' for tools/call`。當缺少 `taskId`、`status`、`createdAt`、`lastUpdatedAt` 或 `ttlMs` 時，Claude 也會收到相同的錯誤。任務物件是 `tools/call` 回應的 JSON-RPC `result`，不需要 `content` 陣列，此處還包含選用的 `statusMessage` 和 `pollIntervalMs`：582只有在請求攜帶該擴充功能時才以任務回應，否則 Claude 會收到工具錯誤 `Unsupported result type 'task' for tools/call`。當缺少 `taskId`、`status`、`createdAt`、`lastUpdatedAt` 或 `ttlMs` 時，Claude 也會收到相同的錯誤。任務物件是您 `tools/call` 回應的 JSON-RPC `result`，不需要 `content` 陣列，此處包含了選用的 `statusMessage` 和 `pollIntervalMs`：
583 583
584```json theme={null}584```json theme={null}
585{585{
596 596
597| 欄位 | Claude Code 如何處理 |597| 欄位 | Claude Code 如何處理 |
598| - | - |598| - | - |
599| `resultType` | 設為 `"task"` 以將回應標示為任務。若沒有此欄位，Claude Code 會將回應讀取為一般結果 |599| `resultType` | 設為 `"task"` 以將回覆標示為任務。若沒有此欄位，Claude Code 會將回覆讀取為一般結果 |
600| `taskId` | 必填。最多 128 個可列印的 ASCII 字元且不含空格，否則 Claude 會收到以 `MCP server "<name>" returned a malformed task handle for tool "<tool>"` 開頭的工具錯誤。請讓此 ID 在不同連線間都能被回應，因為恢復後 Claude Code 會在新的連線上詢問它 |600| `taskId` | 必要。最多 128 個可列印的 ASCII 字元且不含空格，否則 Claude 會收到以 `MCP server "<name>" returned a malformed task handle for tool "<tool>"` 開頭的工具錯誤。請讓該 ID 在不同連線間都能被回應，因為恢復後 Claude Code 會在新的連線上詢問它 |
601| `status` | 必填。為 `working`、`input_required`、`completed`、`failed` 或 `cancelled` 之一。其他值會產生 `Unsupported result type` 錯誤 |601| `status` | 必要。為 `working`、`input_required`、`completed`、`failed` 或 `cancelled` 之一。其他值會產生 `Unsupported result type` 錯誤 |
602| `createdAt`、`lastUpdatedAt`、`ttlMs` | 必填，`ttlMs` 可以是 `null`。Claude Code 不會因為任務的 `ttlMs` 已過而捨棄該任務 |602| `createdAt`、`lastUpdatedAt`、`ttlMs` | 必要，且 `ttlMs` 可以是 `null`。Claude Code 不會因為任務的 `ttlMs` 已過而捨棄該任務 |
603| `pollIntervalMs` | 選填，但不可為 `null`。兩次 `tasks/get` 請求之間的毫秒數，限制在 250 到 30000 之間。缺少此欄位時，Claude Code 使用 2000，並會從每個 `tasks/get` 回應中重新讀取此值 |603| `pollIntervalMs` | 選用，但不可為 `null`。`tasks/get` 請求之間的毫秒數，會被限制在 250 到 30000 之間。若缺少此欄位，Claude Code 會使用 2000，並從每個 `tasks/get` 回應中重新讀取該值 |
604| `statusMessage` | 選填。`/tasks` 顯示的是您最新一次 `tasks/get` 回應中的值，而非這第一次的值，且省略此欄位的回應會將其清除。[Claude Code 的狀態訊息](#status-messages-on-an-mcp-task)可能會取代它 |604| `statusMessage` | 選用。`/tasks` 會顯示您最新 `tasks/get` 回應中的值，而非這第一個回應中的值，且省略此欄位的回應會將其清除。[Claude Code 的狀態訊息](#status-messages-on-an-mcp-task)可能會取代它 |
605 605
606在 HTTP 或 claude.ai 連接器伺服器上，任務回應必須在[逐請求計時器](#time-limits-on-mcp-tool-calls)內開始，因此請先接受工作並回應，再進行工作。606在 HTTP 或 claude.ai 連接器伺服器上，任務回應必須在[每個請求的計時器](#time-limits-on-mcp-tool-calls)內開始，因此請先接受工作並回應，然後再執行工作。
607 607
608#### 回報狀態、結果與問題608#### 回報狀態、結果與問題
609 609
610在任務回應之後，Claude Code 會立即傳送帶有 `{ "taskId": ... }` 的 `tasks/get`，然後每個輪詢間隔重複一次。tasks 擴充功能要求您的回應攜帶 `"resultType": "complete"`，以及 `taskId`、`status`、`createdAt`、`lastUpdatedAt` 和 `ttlMs`。`ttlMs` 可以是 `null`，`statusMessage` 和 `pollIntervalMs` 為選填。此範例回報建置已完成：610在任務回應之後，Claude Code 會立即傳送帶有 `{ "taskId": ... }` 的 `tasks/get`，然後每個輪詢間隔重複一次。tasks 擴充功能要求您的回應攜帶 `"resultType": "complete"`，以及 `taskId`、`status`、`createdAt`、`lastUpdatedAt` 和 `ttlMs`。`ttlMs` 可以是 `null`，而 `statusMessage` 和 `pollIntervalMs` 為選用。此範例回報建置已完成：
611 611
612```json theme={null}612```json theme={null}
613{613{
626| 狀態、方法或回應 | Claude Code 如何處理 |626| 狀態、方法或回應 | Claude Code 如何處理 |
627| - | - |627| - | - |
628| `working` | 持續輪詢 |628| `working` | 持續輪詢 |
629| `completed` | 將頂層 `result` 物件中的一般 `tools/call` 結果交給 Claude。其中的 `isError: true` 會被回報為失敗 |629| `completed` | 將頂層 `result` 物件中的一般 `tools/call` 結果提供給 Claude。其中的 `isError: true` 會回報為失敗 |
630| `failed` | 告知 Claude 頂層 `error` 物件 `{ code, message, data }` 的 `message`，tasks 擴充功能要求失敗的任務必須帶有此物件。若沒有該 `message`，Claude 會改為取得 `statusMessage`，否則取得 `Task failed` |630| `failed` | 將頂層 `error` 物件 `{ code, message, data }` 的 `message` 告知 Claude，tasks 擴充功能要求失敗的任務必須包含此物件。若沒有該 `message`，Claude 會改為收到 `statusMessage`，否則為 `Task failed` |
631| `cancelled` | 告知 Claude `statusMessage`，否則告知 `Task was cancelled by the server` |631| `cancelled` | 將 `statusMessage` 告知 Claude，否則為 `Task was cancelled by the server` |
632| `input_required` | 讀取 `inputRequests`，這是一個將您所選的鍵對應到 `{ method, params }` 的物件。Claude Code 會透過帶有 `{ taskId, inputResponses }` 的 `tasks/update` 對每個鍵回答一次，其中 `inputResponses` 將相同的鍵對應到該請求的結果。每個任務超過 16 個的鍵會被忽略 |632| `input_required` | 讀取 `inputRequests`，這是一個將您選擇的鍵對應至 `{ method, params }` 的物件。Claude Code 會透過帶有 `{ taskId, inputResponses }` 的 `tasks/update` 對每個鍵回答一次，其中 `inputResponses` 會將相同的鍵對應至該請求的結果。每個任務超過 16 個的鍵會被忽略 |
633| `inputRequests` 中的方法 | `elicitation/create` 只在互動式終端機工作階段中提供服務，`roots/list` 則在所有地方都提供。當 Claude Code 無法處理請求時，會要求伺服器取消任務 |633| `inputRequests` 中的方法 | `elicitation/create` 只在互動式終端機工作階段中提供服務，`roots/list` 則在所有地方都提供。當 Claude Code 無法處理某個請求時，它會要求伺服器取消該任務 |
634| 其他 `status` 值 | Claude Code 會要求伺服器取消任務，並向 Claude 回報為失敗 |634| 其他 `status` 值 | Claude Code 會要求伺服器取消該任務，並向 Claude 回報為失敗 |
635| JSON-RPC 錯誤 `-32602` | 視為未知的任務 ID。對於背景中的任務，Claude Code 會持續詢問最多五分鐘，然後向 Claude 回報結果未知 |635| JSON-RPC 錯誤 `-32602` | 讀取為未知的任務 ID。對於背景中的任務，Claude Code 會持續詢問最多五分鐘，然後向 Claude 回報結果未知 |
636| `tasks/cancel` | 例如在伺服器連線期間，Claude 或使用者停止任務時傳送。結束時不會傳送 |636| `tasks/cancel` | 例如當 Claude 或使用者在伺服器連線期間停止任務時傳送。結束時不會傳送 |
637| `tasks/result`、`tasks/list`、`notifications/tasks` | 不使用，因此請將結果放在您的 `tasks/get` 回應中 |637| `tasks/result`、`tasks/list`、`notifications/tasks` | 不會使用，因此請將結果放在您的 `tasks/get` 回應中 |
638 638
639### 外掛提供的 MCP 伺服器639### 外掛提供的 MCP 伺服器
640 640
641[外掛](https://code.claude.com/docs/zh-TW/plugins/overview.md)可以捆綁 MCP 伺服器，在您啟用外掛時提供工具和整合。641[外掛](https://code.claude.com/docs/zh-TW/plugins/overview.md)可以捆綁 MCP 伺服器，在您啟用外掛時提供工具與整合功能。
642 642
643**外掛 MCP 伺服器如何工作**：643**外掛 MCP 伺服器的運作方式**：
644 644
645* 外掛在外掛根目錄的 `.mcp.json` 中或內聯在 `plugin.json` 中定義 MCP 伺服器645* 外掛在外掛根目錄的 `.mcp.json` 中定義 MCP 伺服器，或內嵌於 `plugin.json` 中
646* 當您啟用外掛時，Claude Code 自動啟動其 MCP 伺服器646* 當您啟用外掛時，Claude Code 會自動啟動其 MCP 伺服器
647* Claude Code 將外掛 MCP 工具與手動設定的 MCP 工具一起提供647* Claude Code 會將外掛 MCP 工具與手動設定的 MCP 工具一併提供
648* 您透過安裝或解除安裝外掛新增和移除外掛伺服器，而不是使用 `/mcp` 命令。您仍然可以 [在 `/mcp` 中切換已安裝的外掛伺服器關閉](#disable-a-server-without-removing-it)，這會停止 Claude Code 連接到它，而不會移除外掛648* 外掛伺服器的新增與移除是透過安裝或解除安裝外掛來完成，而非使用 `/mcp` 命令。您仍可在 `/mcp` 中[將已安裝的外掛伺服器切換為關閉](#disable-a-server-without-removing-it)，這會讓 Claude Code 停止連線至該伺服器，而不會移除外掛
649 649
650**範例外掛 MCP 設定**：650**外掛 MCP 設定範例**：
651 651
652在外掛根目錄的 `.mcp.json` 中：652在外掛根目錄的 `.mcp.json` 中：
653 653
665}665}
666```666```
667 667
668或內聯在 `plugin.json` 中：668或內嵌於 `plugin.json` 中：
669 669
670```json theme={null}670```json theme={null}
671{671{
681 681
682**外掛 MCP 功能**：682**外掛 MCP 功能**：
683 683
684* **自動生命週期**：伺服器在這些點連接和斷開連接：684* **自動生命週期**：伺服器會在以下時間點連線與中斷連線：
685 * 在工作階段啟動時，Claude Code 自動連接已啟用外掛的伺服器。在 `/mcp` 中，您之前使用過的遠端（HTTP 或 SSE）外掛伺服器可以改為顯示 [`cached` 狀態](#server-status-detail)；Claude Code 在 Claude 首次呼叫其工具之一時連接它。當 stdio 外掛伺服器的連接在不到 15 分鐘前失敗時，Claude Code 會 [跳過該連接](https://code.claude.com/docs/zh-TW/errors.md#skipping-connection-recent-failure-cached)685 * 在工作階段啟動時，Claude Code 會自動連線已啟用外掛的伺服器。在 `/mcp` 中，您先前使用過的遠端（HTTP 或 SSE）外掛伺服器可能會改為顯示 [`cached` 狀態](#server-status-detail)；Claude Code 會在 Claude 首次呼叫其中一個工具時連線該伺服器。當 stdio 外掛伺服器的連線在不到 15 分鐘前失敗時，Claude Code 會[略過該連線](https://code.claude.com/docs/zh-TW/errors.md#skipping-connection-recent-failure-cached)
686 * 如果您在工作階段期間啟用或停用外掛，Claude Code 在變更適用時連接或斷開其 MCP 伺服器。[在不重新啟動的情況下應用外掛變更](https://code.claude.com/docs/zh-TW/plugins/cli-reference.md#reload-plugins)描述何時發生。在沒有互動式終端機的工作階段中，`/reload-plugins` 不連接或斷開外掛 MCP 伺服器；這些變更在您的下一個工作階段中生效686 * 如果您在工作階段期間啟用或停用外掛，Claude Code 會在變更套用時連線或中斷其 MCP 伺服器。[無需重新啟動即可套用外掛變更](https://code.claude.com/docs/zh-TW/plugins/cli-reference.md#reload-plugins)說明了套用的時機。在沒有互動式終端機的工作階段中，`/reload-plugins` 不會連線或中斷外掛 MCP 伺服器；這些變更會在您的下一個工作階段生效
687 * 當您重新載入時，Claude Code 保留設定未變更的外掛伺服器的即時連接，並在您 [從 Agent SDK 替換工作階段的 MCP 伺服器列表](https://code.claude.com/docs/zh-TW/agent-sdk/typescript.md#mcpsetserversresult)而不命名它們時執行相同操作687 * 當您重新載入時，Claude Code 會保留設定未變更之外掛伺服器的現有連線；當您從 Agent SDK [取代工作階段的 MCP 伺服器清單](https://code.claude.com/docs/zh-TW/agent-sdk/typescript.md#mcpsetserversresult)而未指名這些伺服器時，也會如此處理
688 * 當您在 v2.1.246 或更新版本上 [使用 `/cd` 移動工作階段](https://code.claude.com/docs/zh-TW/permissions#move-the-session-to-another-directory)時，Claude Code 連接新目錄的設定啟用的外掛的伺服器，並斷開不再啟用的外掛的伺服器，因此您不需要在移動後執行 `/reload-plugins`688 * 當您在 v2.1.246 或更新版本中[使用 `/cd` 移動工作階段](https://code.claude.com/docs/zh-TW/permissions#move-the-session-to-another-directory)時，Claude Code 會連線新目錄設定所啟用之外掛的伺服器，並中斷不再啟用之外掛的伺服器，因此移動後您不需要執行 `/reload-plugins`
689 * 在 [雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)中，對尚未連接的外掛伺服器的 MCP 呼叫（例如空閒工作階段喚醒後）按需啟動伺服器並等待它連接689 * 在[雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)中，對尚未連線之外掛伺服器的 MCP 呼叫（例如在閒置的工作階段剛喚醒後）會依需求啟動該伺服器，並等待其連線
690* **路徑佔位符**：`${CLAUDE_PLUGIN_ROOT}` 解析為外掛的安裝目錄，`${CLAUDE_PLUGIN_DATA}` 解析為其 [持久狀態](https://code.claude.com/docs/zh-TW/plugins/components.md#path-variables-and-persistent-data)目錄，`${CLAUDE_PROJECT_DIR}` 解析為穩定的專案根目錄。替換適用於：690* **路徑預留位置**：`${CLAUDE_PLUGIN_ROOT}` 會解析為外掛的安裝目錄，`${CLAUDE_PLUGIN_DATA}` 會解析為其[持久狀態](https://code.claude.com/docs/zh-TW/plugins/components.md#path-variables-and-persistent-data)目錄，而 `${CLAUDE_PROJECT_DIR}` 會解析為穩定的專案根目錄。替換適用於：
691 * `stdio` 伺服器：`command`、`args`、`env`691 * `stdio` 伺服器：`command`、`args`、`env`
692 * `http`、`sse` 和 `ws` 伺服器：`url`、`headers` 和 `headersHelper`692 * `http`、`sse` 和 `ws` 伺服器：`url`、`headers` 和 `headersHelper`
693* **使用者環境存取**：存取與手動設定伺服器相同的環境變數693* **使用者環境存取**：可存取與手動設定之伺服器相同的環境變數
694* **多個傳輸類型**：支援 stdio、SSE、HTTP 和 WebSocket 傳輸，儘管傳輸支援可能因伺服器而異694* **多種傳輸類型**：支援 stdio、SSE、HTTP 和 WebSocket 傳輸，但傳輸支援可能因伺服器而異
695 695
696外掛伺服器出現在 `/mcp` 中，指標顯示它們來自外掛。696外掛伺服器會顯示在 `/mcp` 中，並附有表示其來自外掛的標示。
697 697
698`claude mcp get` 會隱藏為外掛的 stdio 或 WebSocket 伺服器設定的值，因為它們可能攜帶憑證：698`claude mcp get` 會隱藏為外掛之 stdio 或 WebSocket 伺服器設定的值，因為這些值可能包含憑證：
699 699
700* **stdio 伺服器**：它列印 `Command: stdio`、空 `Args:` 行，並將每個環境變數列印為 `NAME=[REDACTED]`700* **stdio 伺服器**：會輸出 `Command: stdio`、一行空白的 `Args:`，並將每個環境變數輸出為 `NAME=[REDACTED]`
701* **WebSocket 伺服器**：它列印 `URL: ws`，並將每個標頭列印為 `<name>: [REDACTED]`，而 `claude mcp list` 會以 `ws` 取代 URL 顯示701* **WebSocket 伺服器**：會輸出 `URL: ws`，並將每個標頭輸出為 `<name>: [REDACTED]`，而 `claude mcp list` 會以 `ws` 取代 URL 顯示
702 702
703若要查看外掛設定的內容，請 [在磁碟上找到外掛](https://code.claude.com/docs/zh-TW/plugins/loading.md#find-plugins-on-disk)並讀取其 `.mcp.json` 或 `plugin.json`。703若要查看外掛設定的內容，請[在磁碟上找到該外掛](https://code.claude.com/docs/zh-TW/plugins/loading.md#find-plugins-on-disk)，並閱讀其 `.mcp.json` 或 `plugin.json`。
704 704
705**外掛 MCP 工具名稱**：705**外掛 MCP 工具名稱**：
706 706
707來自外掛捆綁的 MCP 伺服器的工具在其可呼叫名稱中包含外掛名稱和伺服器金鑰。完整形式是 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`，其中 `A-Z`、`a-z`、`0-9`、`_` 和 `-` 以外的任何字元都被替換為 `_`。對於名為 `my-plugin` 的外掛中捆綁的 `database-tools` 伺服器，`query` 工具可呼叫為：707來自外掛捆綁之 MCP 伺服器的工具，其可呼叫名稱同時包含外掛名稱與伺服器鍵。完整形式為 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`，其中 `A-Z`、`a-z`、`0-9`、`_` 和 `-` 以外的任何字元都會被替換為 `_`。以名為 `my-plugin` 之外掛中捆綁的 `database-tools` 伺服器為例，`query` 工具的呼叫名稱為：
708 708
709```709```
710mcp__plugin_my-plugin_database-tools__query710mcp__plugin_my-plugin_database-tools__query
711```711```
712 712
713在 [權限規則](https://code.claude.com/docs/zh-TW/permissions.md)、skill 的 `allowed-tools` 列表、[subagent 的 `tools` 欄位](https://code.claude.com/docs/zh-TW/sub-agents#available-tools)或 [hook matcher](https://code.claude.com/docs/zh-TW/hooks.md#match-mcp-tools) 中參考工具時使用此完整名稱。針對裸伺服器金鑰編寫的 hook matcher（例如 `mcp__database-tools__.*`）永遠不會針對外掛捆綁的伺服器觸發。713在[權限規則](https://code.claude.com/docs/zh-TW/permissions.md)、skill 的 `allowed-tools` 清單、[subagent 的 `tools` 欄位](https://code.claude.com/docs/zh-TW/sub-agents#available-tools)或 [hook matcher](https://code.claude.com/docs/zh-TW/hooks.md#match-mcp-tools) 中參照該工具時，請使用此完整名稱。針對單純伺服器鍵撰寫的 hook matcher（例如 `mcp__database-tools__.*`）永遠不會對外掛捆綁的伺服器觸發。
714 714
715伺服器本身在範圍名稱 `plugin:<plugin-name>:<server-name>` 下註冊，例如 `plugin:my-plugin:database-tools`。在預期已設定伺服器名稱的地方使用該名稱，例如 [`mcp_tool` hook 的 `server` 欄位](https://code.claude.com/docs/zh-TW/hooks#mcp-tool-hook-fields)。715伺服器本身會以範圍名稱 `plugin:<plugin-name>:<server-name>` 註冊，例如 `plugin:my-plugin:database-tools`。在需要已設定之伺服器名稱的地方請使用該名稱，例如 [`mcp_tool` hook 的 `server` 欄位](https://code.claude.com/docs/zh-TW/hooks#mcp-tool-hook-fields)。
716 716
717請參閱 [外掛元件參考](https://code.claude.com/docs/zh-TW/plugins/components.md#mcp-servers)以取得有關使用外掛捆綁 MCP 伺服器的詳細資訊。717如需在外掛中捆綁 MCP 伺服器的詳細資訊，請參閱[外掛元件參考](https://code.claude.com/docs/zh-TW/plugins/components.md#mcp-servers)。
718 718
719## MCP 安裝範圍719## MCP 安裝範圍
720 720
1332 1332
1333來自 claude.ai 的伺服器會出現在清單中，並有指示器顯示它們來自 claude.ai。1333來自 claude.ai 的伺服器會出現在清單中，並有指示器顯示它們來自 claude.ai。
1334 1334
1335Anthropic 也自行提供一些 connectors，無需您或管理員新增。在可使用 [Claude Docs](https://code.claude.com/docs/zh-TW/artifacts.md#write-a-document-with-claude-docs) 的帳戶上，`/mcp` 會列出 `claude.ai Claude Docs`，無需設定，當您要求建立供他人使用的文件時，Claude 會使用它。若要關閉它，請將 `"claude.ai Claude Docs"` 的 `serverName` 項目新增至 `deniedMcpServers`，或使用 `/mcp` 切換，兩者都在 [停用 claude.ai connectors](#disable-claude-ai-connectors) 中說明。1335Anthropic 也自行提供一些 connectors，無需您或管理員新增。在可使用 [Claude Docs](https://code.claude.com/docs/zh-TW/artifacts.md#write-a-document-with-claude-docs) 的帳戶上，`/mcp` 會列出 `claude.ai Claude Docs`，無需設定，當您要求建立供他人使用的文件時，Claude 會使用它。若要僅關閉此 connector，請參閱 [停用 claude.ai connectors](#disable-claude-ai-connectors)。
1336 1336
1337當您的組織在 claude.ai 中管理其驗證時，Claude Code 會在 `/mcp` 和 [`/plugin`](https://code.claude.com/docs/zh-TW/plugins/install) 管理員中將 connector 標記為 `managed`。Managed 狀態不會改變 Claude Code 連接到 connector 的方式，也不會改變您組織的 [工具控制](#organization-controls-on-connector-tools) 的應用方式。1337當您的組織在 claude.ai 中管理其驗證時，Claude Code 會在 `/mcp` 和 [`/plugin`](https://code.claude.com/docs/zh-TW/plugins/install) 管理員中將 connector 標記為 `managed`。Managed 狀態不會改變 Claude Code 連接到 connector 的方式，也不會改變您組織的 [工具控制](#organization-controls-on-connector-tools) 的應用方式。
1338 1338
