> ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 透過 MCP 將 Claude Code 連接到工具 > 了解如何使用 Model Context Protocol 將 Claude Code 連接到您的工具。 Claude Code 可以透過 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 連接到數百個外部工具和資料來源，這是一個開源標準，用於 AI 工具整合。MCP servers 讓 Claude Code 能夠存取您的工具、資料庫和 API。 當您發現自己從另一個工具（例如問題追蹤器或監控儀表板）複製資料到聊天中時，請連接一個 server。連接後，Claude 可以直接讀取和操作該系統，而不是根據您貼上的內容進行工作。 如果您是第一次連接 server，請從 [MCP 快速入門](/docs/zh-TW/mcp-quickstart) 開始，以取得逐步說明。本頁面是完整參考。

使用 MCP 可以做什麼

使用連接的 MCP servers，您可以要求 Claude Code： * **從問題追蹤器實現功能**："新增 JIRA 問題 ENG-4521 中描述的功能，並在 GitHub 上建立 PR。" * **分析監控資料**："檢查 Sentry 和 Statsig，以檢查 ENG-4521 中描述的功能使用情況。" * **查詢資料庫**："根據我們的 PostgreSQL 資料庫，找到 10 個使用功能 ENG-4521 的隨機使用者的電子郵件。" * **整合設計**："根據在 Slack 中發佈的新 Figma 設計更新我們的標準電子郵件範本" * **自動化工作流程**："建立 Gmail 草稿，邀請這 10 個使用者參加關於新功能的回饋會議。" * **回應外部事件**：MCP server 也可以充當 [channel](/docs/zh-TW/channels)，將訊息推送到您的 session 中，因此當您不在時，Claude 可以回應 Telegram 訊息、Discord 聊天或 webhook 事件。

尋找並建立 MCP servers

在 [Anthropic Directory](https://claude.ai/directory) 中瀏覽已審核的連接器。Directory 連接器使用與 Claude Code 相同的 MCP 基礎設施，因此您可以使用 `claude mcp add` 新增任何列在其中的遠端伺服器。 在連接伺服器之前，請驗證您信任每個伺服器。取得外部內容的伺服器可能會使您面臨[提示注入風險](/docs/zh-TW/security#protect-against-prompt-injection)。 若要建立您自己的伺服器，請參閱 [MCP server 指南](https://modelcontextprotocol.io/docs/develop/build-server) 以了解協議基礎知識，以及 [Claude 連接器建立文件](https://claude.com/docs/connectors/building) 以了解身份驗證、測試和 Directory 提交。 您也可以使用官方的 [`mcp-server-dev` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev) 讓 Claude 為您建立伺服器。 在 VS Code 擴充功能或桌面應用程式中，請改為依照[安裝外掛](/docs/zh-TW/plugins/install#install-a-plugin)操作，而非執行此步驟。在終端機中，執行 `claude` 啟動 Claude Code，然後在其提示字元輸入以下內容： ``` /plugin install mcp-server-dev@claude-plugins-official ``` 如果安裝失敗，請符合 Claude Code 報告的訊息： * `Marketplace "claude-plugins-official" not found`：使用 `/plugin marketplace add anthropics/claude-plugins-official` 新增市集，然後重試安裝。 * `Plugin "" not found in marketplace "claude-plugins-official"`：您本機的市集目錄副本可能已過時。請使用 `/plugin marketplace update claude-plugins-official` 重新整理，然後重試安裝。如果重試後顯示相同的訊息，請參閱 [Plugin not found in marketplace](/docs/zh-TW/plugins/troubleshooting#plugin-not-found-in-marketplace)。 如果安裝摘要報告 `Run /reload-plugins to apply.`，Claude Code 會為您執行該重新載入。如果重新載入警告您的下一則訊息會重新讀取對話，請執行 `/reload-plugins --force`。 ``` /mcp-server-dev:build-mcp-server ``` Claude 會詢問您的使用案例，並建立遠端 HTTP 或本機 stdio 伺服器。

安裝 MCP 伺服器

MCP 伺服器可以根據您的需求以多種方式進行設定：

選項 1：新增遠端 HTTP 伺服器

HTTP 伺服器是連接到遠端 MCP 伺服器的建議選項。這是雲端服務最廣泛支援的傳輸方式。 ```bash theme={null} # 基本語法 claude mcp add --transport http # 實際範例：連接到 Notion claude mcp add --transport http notion https://mcp.notion.com/mcp # 使用 Bearer token 的範例 claude mcp add --transport http secure-api https://api.example.com/mcp \ --header "Authorization: Bearer your-token" ``` 在透過 `.mcp.json`、`~/.claude.json` 或 `claude mcp add-json` 中的 JSON 設定 MCP 伺服器時，`type` 欄位接受 `streamable-http` 作為 `http` 的別名。MCP 規範使用名稱 `streamable-http` 作為此傳輸方式，因此從伺服器文件複製的設定無需修改即可運作。 具有 `url` 但沒有 `type` 的 JSON 項目是設定錯誤，因為 Claude Code 將沒有 `type` 的項目讀取為 stdio 伺服器。Claude Code 會跳過該伺服器並報告 `MCP server "" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`。 只有 SDK 主機應用程式（例如 [Agent SDK](/docs/zh-TW/agent-sdk/mcp) 應用程式或 [桌面應用程式](/docs/zh-TW/desktop)）可以註冊進程內 `"type": "sdk"` 伺服器。Claude Code 會跳過 `.mcp.json`、`~/.claude.json` 或設定中的 `"type": "sdk"` 項目，並報告 `Skipped — MCP server "" declares type "sdk", which only an SDK host application can register`。 在 `--output-format stream-json` 執行中，Claude Code 也會在 `system/init` 事件的 [`mcp_server_errors` 欄位](/docs/zh-TW/headless#stream-responses)中報告跳過的 `--mcp-config` 項目，以便指令碼可以偵測伺服器從未載入。這需要 Claude Code v2.1.219 或更新版本。

選項 2：新增遠端 SSE 伺服器

SSE (Server-Sent Events) 傳輸已棄用。請改用 HTTP 伺服器（如果可用）。 某些服務仍然只公開 SSE 端點。使用與 [HTTP 伺服器](#option-1-add-a-remote-http-server)相同的 `claude mcp add --transport http ` 命令新增這些。Claude Code 首先嘗試 HTTP 傳輸，當伺服器不接受時切換到 SSE。自動切換需要 Claude Code v2.1.265 或更新版本。 在較早版本上，或直接透過 SSE 連接，請改為傳遞 `--transport sse`： ```bash theme={null} # 基本語法 claude mcp add --transport sse # 實際範例：連接到 Asana claude mcp add --transport sse asana https://mcp.asana.com/sse # 使用驗證標頭的範例 claude mcp add --transport sse private-api https://api.company.com/sse \ --header "X-API-Key: your-key-here" ```

選項 3：新增本機 stdio 伺服器

Stdio 伺服器在您的機器上作為本機程序執行。它們非常適合需要直接系統存取或自訂指令碼的工具。 Claude Code 在生成的伺服器環境中設定 `CLAUDE_PROJECT_DIR` 為專案根目錄，因此您的伺服器可以解析專案相對路徑，而無需依賴工作目錄。這是 hook 在其 `CLAUDE_PROJECT_DIR` 變數中接收的相同目錄。從伺服器程序內部讀取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。 `CLAUDE_PROJECT_DIR` 是穩定的專案根目錄，在您於工作階段中途新增或移除工作目錄時不會變更。限制自身檔案系統存取到一組允許目錄的伺服器應改為實作 MCP `roots/list` 請求。Claude Code 使用工作階段的啟動目錄加上您透過 `--add-dir`、`/add-dir` 或 `additionalDirectories` 設定授予的每個 [額外工作目錄](/docs/zh-TW/permissions#working-directories)來回答 `roots/list`。當該集合變更時，Claude Code 會傳送 `notifications/roots/list_changed`。 此變數設定在伺服器的環境中，而不是在 Claude Code 自身的環境中，因此在專案範圍的 `.mcp.json` 項目或 `~/.claude.json` 中的本機或使用者範圍伺服器項目的 `command` 或 `args` 中透過 `${VAR}` 擴展參考它需要預設值，例如 `${CLAUDE_PROJECT_DIR:-.}`。外掛提供的 MCP 設定直接替換 `${CLAUDE_PROJECT_DIR}`，不需要預設值。 ```bash theme={null} # 基本語法 claude mcp add [options] -- [args...] # 實際範例：新增 Airtable 伺服器 claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \ -- npx -y airtable-mcp-server ``` 對於 stdio 伺服器，`--`（雙破折號）分隔 Claude 自身的選項（例如 `--transport`、`--env` 和 `--scope`）與執行伺服器的命令和引數。`--` 之後的所有內容都會原封不動地傳遞給伺服器。 例如： * `claude mcp add --transport stdio myserver -- npx server` → 執行 `npx server` * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 執行 `python server.py --port 8080`，環境中有 `KEY=value` 沒有 `--`，Claude Code 會嘗試將伺服器的旗標（例如上面的 `--port`）解析為自身的選項。 `--env` 接受多個 `KEY=value` 對。如果伺服器名稱直接跟在 `--env` 之後，CLI 會將名稱讀取為另一對並拒絕它，因此請在 `--env` 和伺服器名稱之間放置至少一個其他選項，例如 `--transport stdio`。

Claude Code 如何停止 stdio 伺服器

當 Claude Code 中斷與 stdio 伺服器的連接時（例如在您的工作階段結束時），它會向伺服器程序傳送訊號，並短暫等待其退出，然後才強制停止它。如果您的伺服器在關閉時儲存狀態或移除鎖定檔案，請處理您平台的訊號，並在該時間內完成： * **在 macOS 和 Linux 上**：Claude Code 傳送 `SIGINT`，如果程序在 100 毫秒後仍在執行，則傳送 `SIGTERM`，再過 400 毫秒後傳送 `SIGKILL`。 * **在 Windows 上**：Claude Code 關閉伺服器的 stdin，如果程序在 300 毫秒後仍在執行，則結束伺服器的程序樹。 在 v2.1.296 之前，Windows 上的 Claude Code 會立即結束伺服器的程序樹，不會先關閉 stdin 或等待。

選項 4：新增遠端 WebSocket 伺服器

WebSocket 伺服器保持持久雙向連接，適合遠端 MCP 伺服器主動向 Claude 推送事件。當您的伺服器只回應請求時，請改用 HTTP，因為 HTTP 支援 OAuth 和 `claude mcp add --transport` 旗標，而 WebSocket 都不支援。 在 `.mcp.json` 中或使用 `claude mcp add-json` 設定 WebSocket 伺服器： ```bash theme={null} claude mcp add-json events-server \ '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}' ``` `type: "ws"` 項目接受與 `http` 相同的 `url`、`headers`、`headersHelper`、`timeout` 和 `alwaysLoad` 欄位。身分驗證僅限標頭，因此在 `headers` 中傳遞靜態 token 或在連接時使用 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 產生 token。`claude mcp add --transport` 旗標不接受 `ws`。

從為另一個用戶端編寫的設定指示新增伺服器

MCP 伺服器不是 Claude Code 特有的，因此伺服器的設定指示可能是為 Claude Desktop、Cursor 或另一個 MCP 用戶端編寫的，並且不提供 `claude mcp add` 命令。若要新增伺服器，請在這些指示中尋找 URL、啟動命令或 JSON 區塊： * **URL**（例如 `https://mcp.example.com/mcp`）：伺服器是遠端的。 * **啟動命令**（例如 `npx -y @example/mcp-server`）：伺服器在您的機器上執行。 * **`mcpServers` JSON 區塊**：為另一個用戶端的設定檔編寫的設定。 每一個都是 [安裝 MCP 伺服器](#installing-mcp-servers)中四個選項之一接受的輸入。在下面找到您擁有的形狀，將其轉換為 Claude Code 接受的命令。除非您新增 `--scope project` 或 `--scope user`，否則每個命令都會寫入 [本機範圍](#local-scope)。

從 URL 新增伺服器

URL 表示伺服器是遠端的。對於 `https://` 端點，使用 `--transport http` 新增它，或在指示說端點使用 SSE 時遵循 [選項 2](#option-2-add-a-remote-sse-server)。對於 `wss://` 端點，改為使用 [選項 4](#option-4-add-a-remote-websocket-server)，因為 `--transport` 不接受 `ws`： ```bash theme={null} claude mcp add --transport http example https://mcp.example.com/mcp ``` 如果指示也提供 API 金鑰或 token 標頭，請使用 `--header` 傳遞它，如 [選項 1](#option-1-add-a-remote-http-server)所示。

從 `npx`、`uvx` 或二進位命令新增伺服器

啟動命令表示伺服器作為本機 stdio 程序執行。將整個命令放在 `--` 之後，以便 Claude Code 將旗標（例如 `-y`）傳遞給啟動伺服器的命令，而不是將其讀取為自身的選項。使用 `--env` 傳遞指示要求的任何環境變數，在伺服器名稱之後和 `--` 之前： ```bash theme={null} claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server ``` [選項 3](#option-3-add-a-local-stdio-server)完整涵蓋 `--` 分隔符。

從 `mcpServers` JSON 區塊新增伺服器

為另一個 MCP 用戶端（例如 Claude Desktop）編寫的 `mcpServers` 區塊使用 Claude Code 讀取的包裝器金鑰和項目形狀。將 `mcpServers` 內的物件傳遞給 `claude mcp add-json`，而不是包裝器。兩個項目需要先修復： * **`url` 沒有 `type`**：新增 `"type": "http"`、`"type": "sse"` 或 `"type": "ws"` 以符合端點。Claude Code 將沒有 `type` 的項目讀取為 stdio 伺服器，因此沒有 `type` 的 `url` 項目會失敗。 * **金鑰包含字母、數字、連字號和底線以外的字元**：選擇僅使用這些字元的伺服器名稱。否則金鑰是伺服器名稱。 例如，此區塊： ```json theme={null} { "mcpServers": { "example": { "command": "npx", "args": ["-y", "@example/mcp-server"] } } } ``` 變成此命令： ```bash theme={null} claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}' ``` [從 JSON 設定新增 MCP 伺服器](#add-mcp-servers-from-json-configuration)涵蓋 `add-json` 的 shell 逃逸和 `--scope` 旗標。若要與您的團隊共享伺服器，請改為新增 `--scope project`，或在您的專案根目錄的 `.mcp.json` 下的 `mcpServers` 下新增項目並提交它。[專案範圍](#project-scope)涵蓋 Claude Code 如何載入和核准該檔案。 每個 `claude mcp add` 和 `claude mcp add-json` 命令在成功時列印 `Added ...` 行。若要檢查 Claude Code 是否已連接，請執行 `claude mcp get `；[伺服器狀態](#server-status)涵蓋它顯示的狀態和 `.mcp.json` 伺服器的核准步驟。

管理您的伺服器

設定後，您可以使用這些命令管理您的 MCP 伺服器： ```bash theme={null} # 列出所有已設定的伺服器 claude mcp list # 取得特定伺服器的詳細資訊 claude mcp get notion # 移除伺服器 claude mcp remove notion # （在 Claude Code 內）檢查伺服器狀態 /mcp ``` 移除遠端伺服器時，Claude Code 也會刪除為該伺服器儲存的 OAuth token 和用戶端註冊。

伺服器狀態

`claude mcp add` 透過列印 `Added ...` 行確認成功新增，這表示設定已寫入。如果命令改為列印 `was not saved` 訊息，請參閱 [MCP 伺服器未儲存或移除](/docs/zh-TW/errors#mcp-server-was-not-saved-or-removed)；對於 `may not have been saved` 訊息，請參閱 [MCP 伺服器可能未儲存或移除](/docs/zh-TW/errors#mcp-server-may-not-have-been-saved-or-removed)。 `claude mcp list` 在它列出的每個伺服器旁邊顯示健康狀態，例如 `✔ Connected`、`! Needs authentication` 或 `✘ Failed to connect`。失敗狀態表示 Claude Code 無法連接到該伺服器，而不是列表命令失敗。 此列表中的狀態報告設定決定而不是連接嘗試，因此 Claude Code 在不連接到伺服器的情況下列印它們： * ``⏸ Pending approval (run `claude` to approve)``：來自 `.mcp.json` 的專案範圍伺服器，您尚未核准。Claude Code 在 `claude mcp list` 和 `claude mcp get ` 中都顯示它。執行 `claude` 互動式地檢查並核准它。 * `✘ Rejected (see disabledMcpjsonServers in settings)`：由 [`disabledMcpjsonServers`](/docs/zh-TW/settings-reference#disabledmcpjsonservers) 項目拒絕的 `.mcp.json` 伺服器。Claude Code 只在 `claude mcp get ` 中顯示它。 * `⊘ Disabled for this project (re-enable via /mcp)`：專案的 [`disabledMcpServers`](#disable-a-server-without-removing-it) 列表命名的伺服器。Claude Code 在 `claude mcp list` 和 `claude mcp get ` 中都顯示它。從 `/mcp` 面板重新開啟伺服器。

專案伺服器核准和工作區信任

`claude mcp list` 和 `claude mcp get` 只從未簽入儲存庫的設定檔讀取 `.mcp.json` 核准，直到您透過在工作區中執行 `claude` 並接受工作區信任對話來信任工作區。複製的儲存庫無法核准自身的伺服器：提交到專案的 `.claude/settings.json` 的 [`enableAllProjectMcpServers`](/docs/zh-TW/settings-reference#enableallprojectmcpservers) 或 [`enabledMcpjsonServers`](/docs/zh-TW/settings-reference#enabledmcpjsonservers) 在不受信任的資料夾中被忽略，伺服器保持在 `⏸ Pending approval` 而不是被連接和健康檢查。 這些來源的核准在不受信任的資料夾中仍然適用： * 您的使用者 `~/.claude/settings.json` * 受管設定 * 使用 `--settings` 傳遞的設定 Claude Code 也應用來自未追蹤 `.claude/settings.local.json` 的核准，但它執行 git 來檢查檔案是否被追蹤，並且只在 [受信任的資料夾](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust)中執行該檢查。在您從未信任的資料夾中，Claude Code 會等待信任對話，然後才應用檔案的核准，除非資料夾是您自己的設定主目錄：您的家目錄，或其 `.claude` 您已設定為 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) 的目錄。在 v2.1.207 之前，Claude Code 即使在您從未信任的資料夾中也應用來自未追蹤 `.claude/settings.local.json` 的核准。 任何設定檔中的 `disabledMcpjsonServers` 項目仍然拒絕伺服器。

伺服器狀態詳細資訊

在 `/mcp` 中（包括伺服器的選單）和 [`/plugin`](/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 或更新版本。 發現快取預設關閉，除非逐步推出已為您的帳戶啟用它。設定 [`MCP_DISCOVERY_CACHE=1`](/docs/zh-TW/env-vars) 以開啟它，或設定 `0` 以在推出啟用它時保持關閉。在 v2.1.238 之前，快取預設開啟。 當您從 `/mcp` 中的伺服器選單選擇 **Disable** 或 **Clear authentication** 時，Claude Code 也會捨棄該伺服器的快取項目。**Reconnect** 在已連接或失敗的伺服器上也會捨棄它；在 `cached` 伺服器上，**Reconnect** 現在連接伺服器並保留項目。Claude Code 在捨棄項目後下次連接到伺服器時，它會從伺服器而不是從快取中擷取工具列表。 當伺服器的狀態為 `✘ Failed to connect` 時，`claude mcp list` 將失敗詳細資訊附加到該狀態行，`claude mcp get ` 在 `Issue:` 行上顯示它：HTTP 狀態或錯誤代碼，加上伺服器傳回的任何錯誤文字。伺服器在 `/mcp` 中的詳細檢視在其 `Issue:` 列中包含相同的伺服器報告文字。Claude Code 從此詳細資訊中編輯類似憑證的文字，並且永遠不包括擴展的伺服器 URL，它可能攜帶機密。Claude Code 不會將詳細資訊附加到 `✘ Connection error` 狀態，因為它會列印的異常文字可以嵌入該 URL。在 v2.1.219 之前，兩個命令都只顯示裸露的失敗狀態，沒有狀態代碼或伺服器的錯誤文字。 當您從 `/mcp` 完成身分驗證且連接仍然因 HTTP 狀態或傳輸錯誤代碼而失敗時，Claude Code 會在嘗試後列印的訊息中新增該代碼和伺服器 URL 的來源。來源是方案和主機，加上 URL 命名的連接埠（例如 `https://mcp.example.com`）。 * 路徑和查詢永遠不會出現在該訊息中。 * 對於本機、專案或使用者 [範圍](#mcp-installation-scopes)中的伺服器或受管 MCP 設定，來源顯示該設定中寫入的主機，因此主機中的 `${VAR}` 參考在訊息中不會展開。 * 對於沒有狀態或錯誤代碼的失敗，Claude Code 顯示錯誤文字而不顯示來源。 設定為空 `url` 的遠端伺服器在 `/mcp`、`claude mcp list` 和 [`/plugin`](/docs/zh-TW/plugins/install) 管理員中顯示為 `not configured`，Claude Code 不會嘗試連接到它。外掛可以包含此類佔位符項目，用於您稍後設定的連接器，因此 Claude Code 不會將其報告為錯誤或設定問題。伺服器在 `/mcp` 中的詳細檢視讀取 `No URL configured for this server`；設定項目的 `url` 以連接它。在 v2.1.208 之前，Claude Code 將空 `url` 報告為設定問題，並提示重新連接。

設定警告

Claude Code 警告下面的設定問題。每個項目說明 Claude Code 檢查的內容以及如何清除警告： * **隱藏空白**：當 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 不會修剪空白並完全按照寫入的方式使用值，因此編輯設定以移除它。 * **在多個範圍中使用相同名稱**：如果您在多個 [範圍](#mcp-installation-scopes)中定義相同的伺服器名稱，但端點不同，Claude Code 會在 `claude mcp list` 輸出和 `/mcp` 中警告衝突。Claude Code 按端點儲存 OAuth 登入，因此當您驗證在一個專案中載入的定義時，您仍然需要在不同定義載入的專案中單獨登入。保留您想要的端點並使用 `claude mcp remove --scope ` 移除其他端點。在警告中，Claude Code 引用每個範圍的端點，如您的設定中所寫，帶有 [`${VAR}` 參考](#environment-variable-expansion-in-mcp-json)未展開，因此它永遠不會顯示已解析的值，例如 API 金鑰。 * **保留名稱**：Claude Code 保留其內建伺服器的名稱，包括 `workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview` 和 `Claude Browser`。如果您的設定定義具有保留名稱的伺服器，Claude Code 會在載入時跳過它並顯示警告，要求您重新命名它。`claude mcp add` 拒絕帶有錯誤的保留名稱。`Claude Preview` 和 `Claude Browser` 都命名 [Claude Code 桌面應用程式的預覽窗格](/docs/zh-TW/desktop#preview-your-app)使用的內建伺服器。 * **遺漏環境變數**：如果伺服器設定中的 [`${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)，沒有警告。

工具可用性

`/mcp` 面板在每個已連接伺服器旁邊顯示工具計數，並標記宣傳工具功能但不公開工具的伺服器。 如果您的請求需要仍在背景連接的伺服器中的工具，Claude 會在繼續之前等待該伺服器。等待的方式取決於您的設定： * **使用 [工具搜尋](#scale-with-mcp-tool-search)（預設）**：等待發生在 `ToolSearch` 呼叫內。 * **沒有工具搜尋**：Claude 改為使用 `WaitForMcpServers` 工具。沒有工具搜尋的設定包括自訂 `ANTHROPIC_BASE_URL`、`ENABLE_TOOL_SEARCH=false`，以及 Google Cloud 的 Agent Platform 上早於 Claude Opus 4.5、Claude Sonnet 4.5 和 Claude Haiku 4.5 的模型。 * **在 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 的下一個請求上變得可用。 啟用工具搜尋後，當伺服器在 Claude 工作時完成連接時，Claude Code 在同一回合中的下一個請求上將伺服器的工具名稱列出給 Claude。Claude 然後可以搜尋並呼叫這些工具，而無需等待您的下一條訊息。 恢復工作階段後，Claude 可以在工具的 MCP 伺服器仍在連接時呼叫已儲存對話中的工具。當伺服器正在進行首次連接嘗試時，Claude Code 會保留該呼叫最多 10 秒，並在工具可用後執行它。如果伺服器未及時連接，或它已在 [失敗嘗試後重試](#automatic-reconnection)，該呼叫會以 `No such tool available` [工具錯誤](/docs/zh-TW/errors#no-such-tool-available)失敗。

在不移除的情況下停用伺服器

在 `/mcp` 面板中切換伺服器關閉，以停止 Claude Code 連接到它，而不會失去其設定。Claude Code 仍然在 `/mcp` 中列出伺服器，標記為已停用。 當您切換伺服器時，Claude Code 在 `~/.claude.json` 中按專案記錄您的選擇，在兩個涵蓋不相交伺服器集合的列表之一中： * `disabledMcpServers`：使用者設定伺服器、外掛伺服器、您的組織 [透過受管設定提供](/docs/zh-TW/managed-mcp#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`。 * `enabledMcpServers`：預設關閉的內建伺服器（例如 `computer-use`）的選擇加入列表。Claude Code 只在您在此列出時連接預設關閉的伺服器。 Claude Code 為每個伺服器查詢恰好兩個列表之一，因此兩個列表都不會覆寫另一個。如果您將常規伺服器新增到 `enabledMcpServers`，或將預設關閉的內建伺服器新增到 `disabledMcpServers`，Claude Code 會忽略該項目。 `disabledMcpServers` 和 `enabledMcpServers` 與 [`enabledMcpjsonServers`](/docs/zh-TW/settings-reference#enabledmcpjsonservers) 和 [`disabledMcpjsonServers`](/docs/zh-TW/settings-reference#disabledmcpjsonservers) 無關，它們控制專案的 `.mcp.json` 檔案中定義的伺服器的核准。

MCP 用戶端執行時

Claude 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 執行時。 Claude Code 每次啟動時選擇執行時，並保持到您退出。在 [擷取功能旗標](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)的工作階段中，它在 Claude Code v2.1.232 或更新版本上使用 v2 執行時。 在不擷取功能旗標的工作階段中，Claude Code 在 Claude Code v2.1.274 或更新版本上預設使用 v2 執行時： * Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的工作階段，除非嵌入 Claude Code 的主機平台設定 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-TW/env-vars) * 透過 [Claude 應用程式閘道](/docs/zh-TW/claude-apps-gateway)登入的工作階段 * 您關閉遙測或功能旗標擷取的工作階段，例如使用 `DISABLE_TELEMETRY` 在 v2 上，Claude Code 也： * 詢問 HTTP、stdio 和 claude.ai 連接器伺服器是否支援較新的修訂，並與支援的伺服器一起使用它。它連接到每個其他伺服器，如 v1 所做的那樣。 * 在 [它保持開啟的流](#notification-streams-on-the-v2-runtime)上從較新修訂上的伺服器接收 `list_changed` 通知。 * 不註冊在較新修訂上連接的 [頻道](#push-messages-with-channels)伺服器，因為該修訂無法攜帶頻道訊息。 * 失敗 [MCP OAuth 登入](#authenticate-with-remote-mcp-servers)，其授權回應命名意外發行者。 * 僅將 [MCP OAuth](#authenticate-with-remote-mcp-servers) 憑證傳送到透過 HTTPS 或在 `localhost`、`127.0.0.1` 或 `::1` 上提供的 token 端點。對於 token 端點為其他地方（例如本機網路上的裝置）的純 `http://` 的伺服器，登入失敗。請參閱 [拒絕將憑證傳送到非 https token 端點](/docs/zh-TW/errors#refusing-to-send-credentials-to-non-https-token-endpoint)。 Anthropic 可以使用 Claude Code 擷取的功能旗標將特定伺服器保持在較早的協議上，或關閉該流。 若要自行選擇執行時，請設定 [`MCP_SDK_GENERATION`](/docs/zh-TW/env-vars) 為 `v1` 或 `v2`。若要決定 Claude Code 是否詢問，請設定 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-TW/env-vars) 為 `auto` 或 `legacy`。

動態工具更新

MCP 伺服器可以在連接期間變更其提供的工具、提示詞或資源，並傳送 `list_changed` 通知。當收到通知時： * **在互動式終端機工作階段中**，Claude Code 會從該伺服器擷取更新後的列表，因此您無需重新連接它。 * **在使用 `-p` 旗標的 [非互動模式](/docs/zh-TW/headless)中以及在 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 中**，Claude Code 在收到這些通知時只重新整理工具列表。 如果重新整理請求失敗，Claude Code 會保留伺服器之前發現的工具、提示詞和資源，直到稍後的重新整理成功。在 v2.1.214 之前，重新整理期間的暫時性錯誤會將伺服器的工具、提示詞和資源替換為空列表。

v2 執行時上的通知流

在 [v2 執行時](#mcp-client-runtimes)上，Claude Code 在它保持開啟的流上從較新協議修訂上的伺服器接收 `list_changed` 通知。當流關閉時，Claude Code 會重新開啟它，有兩個限制： * **流在 10 秒內再次關閉**：Claude Code 最多重新開啟三次，然後停止該連接。 * **流保持開啟超過 10 秒，然後關閉**（如流到無伺服器主機通常所做的那樣）：在一小時內五次重新開啟後，Claude Code 在下一次之前等待約六小時。 直到流重新開啟，您保留伺服器的最後擷取工具、提示詞和資源。若要更快地取得其變更，請從 `/mcp` 重新連接伺服器。

自動重新連接

Claude Code 重新連接在工作階段中途掉線的遠端伺服器，並在暫時性錯誤後重試 HTTP 或 SSE 伺服器的首次連接。Stdio 伺服器是本機程序，Claude Code 不會自動重新連接它們。

遠端伺服器的工作階段中途掉線

Claude Code 首先會使用指數退避嘗試重新連接掉線的遠端伺服器，最多五次，從一秒延遲開始，每次加倍： * **在互動式工作階段中**：`/mcp` 在 Claude Code 重新連接時將伺服器顯示為待處理。在五次失敗嘗試後，Claude Code 將伺服器標記為失敗，或在伺服器需要再次授權時標記為需要身分驗證。當它將伺服器標記為失敗時，您會看到 `MCP server "" disconnected · open /mcp to reconnect` 通知。您可以從 `/mcp` 手動重試。 * **在 [`claude -p`](/docs/zh-TW/headless) 執行和 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 工作階段中**：Claude Code 進行相同的五次嘗試，沒有 `/mcp` 面板顯示這些嘗試。當 HTTP 或 SSE 伺服器的嘗試因暫時性錯誤而失敗時，它會在背景中持續重試最多約半小時，當某次重試連接成功時，伺服器及其工具會再次可用。

失敗的首次連接

當 HTTP 或 SSE 伺服器的首次連接因暫時性錯誤（例如 5xx 回應、連接被拒絕或逾時）失敗時，Claude Code 最多重試三次。如果連接仍然失敗，Claude Code 將伺服器標記為失敗。 Claude Code 在這些情況下不重試： * WebSocket 伺服器的首次連接 * 身分驗證或找不到錯誤，因為它需要設定變更才能解決。當 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 是伺服器唯一的 `Authorization` 標頭來源時，Claude Code 仍然重試身分驗證錯誤，因為它在每次嘗試時重新執行助手並可以取得新憑證

失敗的發現請求

伺服器連接後，Claude Code 向其傳送功能發現請求，例如 `tools/list`、`prompts/list` 和 `resources/list`。Claude Code 在暫時性網路或伺服器錯誤後使用短退避最多重試這些請求三次。它不重試身分驗證錯誤、4xx 回應或請求逾時。

自行重試失敗的伺服器

若要重試所有失敗或需要身分驗證的伺服器，請執行 `/mcp reconnect all`。在互動式終端機中，這需要 Claude Code v2.1.284 或更新版本，較早版本會在該處列印 `MCP server "all" not found`。

Claude 如何了解伺服器失敗

Claude Code 是否告訴 Claude 關於失敗連接的已設定伺服器取決於 [工具搜尋](#scale-with-mcp-tool-search)（預設開啟）： * 使用工具搜尋，Claude Code 告訴 Claude 哪個伺服器失敗及其連接錯誤，因此 Claude 在其回應中報告連接失敗。Claude Code 在找不到符合工具的 `ToolSearch` 結果中包含相同的資訊。 * 在任何 [沒有工具搜尋的設定](#configure-tool-search)中，Claude Code 不向 Claude 報告失敗的伺服器連接。

使用頻道推送訊息

MCP 伺服器也可以直接將訊息推送到您的工作階段，以便 Claude 可以對外部事件（如 CI 結果、監控警報或聊天訊息）做出反應。若要啟用此功能，您的伺服器宣告 `claude/channel` 功能，您在啟動時使用 `--channels` 旗標選擇加入。請參閱 [頻道](/docs/zh-TW/channels)以使用官方支援的頻道，或 [頻道參考](/docs/zh-TW/channels-reference)以建立您自己的。 在 [v2 執行時](#mcp-client-runtimes)上，協商 MCP 協議修訂 2026-07-28 的頻道伺服器無法傳遞頻道訊息，因此 Claude Code 不會將其註冊為頻道。不支援該修訂的頻道伺服器會在較早的握手上連接，並如以往一樣註冊。 Claude Code 預設會向 stdio 伺服器詢問該修訂。若要將 stdio 頻道伺服器保持在較早的握手上，請設定 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-TW/env-vars) 為 `legacy`，這會將每個伺服器都保持在較早的握手上。 提示： * 使用 `-s` 或 `--scope` 旗標指定設定的儲存位置： * `local`（預設）：僅在目前專案中對您可用 * `project`：透過 `.mcp.json` 檔案與專案中的每個人共享 * `user`：在所有專案中對您可用 * 使用 `-e` 或 `--env` 旗標設定環境變數（例如 `-e KEY=value`） * `--transport` 和 `--header` 旗標也接受 `-t` 和 `-H` 短形式 * 使用 `MCP_TIMEOUT` 環境變數設定 MCP 伺服器啟動逾時（例如 `MCP_TIMEOUT=10000 claude` 設定 10 秒逾時） * 透過將 `timeout` 欄位（以毫秒為單位）新增到該伺服器的 `.mcp.json` 項目來設定按伺服器工具執行逾時，例如 `"timeout": 600000` 表示十分鐘。這僅針對該伺服器覆寫 `MCP_TOOL_TIMEOUT` 環境變數 * 當 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) * 使用 `/mcp` 對需要 OAuth 2.0 身分驗證的遠端伺服器進行驗證 按伺服器 `timeout` 是每個工具呼叫的硬牆鐘限制，來自伺服器的進度通知不會延長它。低於 1000 的值被忽略並落回 `MCP_TOOL_TIMEOUT`，或在該變數未設定時落回其約 28 小時的預設值。對於 HTTP、SSE 或 [claude.ai 連接器](/docs/zh-TW/mcp#use-mcp-servers-from-claude-ai)伺服器，還有第二個按請求計時器，涵蓋每個請求到伺服器的第一個回應位元組。Claude Code 將該計時器設定為三個值中最大的：60 秒、適用於伺服器的工具逾時和 `MCP_TIMEOUT`。未設定 `MCP_TOOL_TIMEOUT` 的 28 小時預設值不進入該比較，低於 60 秒的值不會縮短計時器。Stdio 和 WebSocket 伺服器沒有按請求計時器。 至少 1000 的按伺服器 `timeout` 也充當下面描述的空閒逾時的下限：Claude Code 永遠不會因空閒而早於按伺服器 `timeout` 中止該伺服器的工具呼叫。 對 MCP 伺服器的工具呼叫，在空閒視窗內不傳送回應且不傳送進度通知，會因錯誤而中止，而不是等待牆鐘限制。空閒逾時適用於除 IDE 伺服器和 SDK 進程內伺服器外的每個伺服器類型。空閒視窗預設為 HTTP、SSE、WebSocket 和 [claude.ai 連接器](#use-mcp-servers-from-claude-ai)伺服器的五分鐘，以及 stdio 伺服器的 30 分鐘。 以毫秒為單位設定 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-TW/env-vars) 環境變數以變更空閒視窗，或設定為 `0` 以停用檢查。 這些逾時限制呼叫可以執行多長時間，不總是它阻止工作階段多長時間：執行超過兩分鐘的主對話呼叫首先移動到背景任務。請參閱 [長工具呼叫的自動背景化](#automatic-backgrounding-of-long-tool-calls)。

長工具呼叫的自動背景化

主對話中仍在執行兩分鐘後的 MCP 工具呼叫移動到背景任務，而不是阻止工作階段。Claude 立即接收任務 ID 並繼續工作，結果在呼叫解決時作為任務通知到達。自動背景化需要 Claude Code v2.1.212 或更新版本。 任務出現在 [`/tasks`](/docs/zh-TW/commands#all-commands)中，您也可以在其中停止它，它不會在退出工作階段時存活。任務的項目顯示伺服器報告的最新進度。如果您停止任務，Claude Code 會取消該呼叫並告知 Claude 不會有結果。停止並不保證伺服器會停止：它可能已經完成部分工作，或仍可能完成它。 按呼叫限制仍然適用於呼叫在背景中執行時：由按伺服器 `timeout` 或 [`MCP_TOOL_TIMEOUT`](/docs/zh-TW/env-vars)設定的牆鐘限制，以及由 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-TW/env-vars)設定的空閒逾時。 以毫秒為單位設定 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](/docs/zh-TW/env-vars) 環境變數以變更閾值，或設定為 `0` 以關閉自動背景化。設定 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 為 `1` 也會關閉它，以及所有其他背景任務功能。 某些呼叫永遠不會移動到背景： * 來自 [subagent](/docs/zh-TW/sub-agents) 的呼叫；Claude Code 只背景化主對話呼叫 * 對 IDE 伺服器的呼叫 * 在 [非互動模式](/docs/zh-TW/headless)中的呼叫，除非 `CLAUDE_AUTO_BACKGROUND_TASKS` 設定為 `1`，因為一次性執行可能在結果到達之前結束 等待開啟 [引出對話](#respond-to-mcp-elicitation-requests)的呼叫在對話開啟時不會背景化；伺服器被阻止在您的輸入上，而不是緩慢，因此 Claude Code 將移動延遲到對話關閉。

外掛提供的 MCP 伺服器

[外掛](/docs/zh-TW/plugins/overview)可以捆綁 MCP 伺服器，在您啟用外掛時提供工具和整合。 **外掛 MCP 伺服器如何工作**： * 外掛在外掛根目錄的 `.mcp.json` 中或內聯在 `plugin.json` 中定義 MCP 伺服器 * 當您啟用外掛時，Claude Code 自動啟動其 MCP 伺服器 * Claude Code 將外掛 MCP 工具與手動設定的 MCP 工具一起提供 * 您透過安裝或解除安裝外掛新增和移除外掛伺服器，而不是使用 `/mcp` 命令。您仍然可以 [在 `/mcp` 中切換已安裝的外掛伺服器關閉](#disable-a-server-without-removing-it)，這會停止 Claude Code 連接到它，而不會移除外掛 **範例外掛 MCP 設定**： 在外掛根目錄的 `.mcp.json` 中： ```json theme={null} { "mcpServers": { "database-tools": { "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server", "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"], "env": { "DB_URL": "${DB_URL}" } } } } ``` 或內聯在 `plugin.json` 中： ```json theme={null} { "name": "my-plugin", "mcpServers": { "plugin-api": { "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server", "args": ["--port", "8080"] } } } ``` **外掛 MCP 功能**： * **自動生命週期**：伺服器在這些點連接和斷開連接： * 在工作階段啟動時，Claude Code 自動連接已啟用外掛的伺服器。在 `/mcp` 中，您之前使用過的遠端（HTTP 或 SSE）外掛伺服器可以改為顯示 [`cached` 狀態](#server-status-detail)；Claude Code 在 Claude 首次呼叫其工具之一時連接它 * 如果您在工作階段期間啟用或停用外掛，Claude Code 在變更適用時連接或斷開其 MCP 伺服器。[在不重新啟動的情況下應用外掛變更](/docs/zh-TW/plugins/cli-reference#reload-plugins)描述何時發生。在沒有互動式終端機的工作階段中，`/reload-plugins` 不連接或斷開外掛 MCP 伺服器；這些變更在您的下一個工作階段中生效 * 當您重新載入時，Claude Code 保留設定未變更的外掛伺服器的即時連接，並在您 [從 Agent SDK 替換工作階段的 MCP 伺服器列表](/docs/zh-TW/agent-sdk/typescript#mcpsetserversresult)而不命名它們時執行相同操作 * 當您在 v2.1.246 或更新版本上 [使用 `/cd` 移動工作階段](/docs/zh-TW/permissions#move-the-session-to-another-directory)時，Claude Code 連接新目錄的設定啟用的外掛的伺服器，並斷開不再啟用的外掛的伺服器，因此您不需要在移動後執行 `/reload-plugins` * 在 [雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，對尚未連接的外掛伺服器的 MCP 呼叫（例如空閒工作階段喚醒後）按需啟動伺服器並等待它連接 * **路徑佔位符**：`${CLAUDE_PLUGIN_ROOT}` 解析為外掛的安裝目錄，`${CLAUDE_PLUGIN_DATA}` 解析為其 [持久狀態](/docs/zh-TW/plugins/components#path-variables-and-persistent-data)目錄，`${CLAUDE_PROJECT_DIR}` 解析為穩定的專案根目錄。替換適用於： * `stdio` 伺服器：`command`、`args`、`env` * `http`、`sse` 和 `ws` 伺服器：`url`、`headers` 和 `headersHelper` * **使用者環境存取**：存取與手動設定伺服器相同的環境變數 * **多個傳輸類型**：支援 stdio、SSE、HTTP 和 WebSocket 傳輸，儘管傳輸支援可能因伺服器而異 外掛伺服器出現在 `/mcp` 中，指標顯示它們來自外掛。 對於外掛的 stdio 伺服器，`claude mcp get` 列印 `Command: stdio`、空 `Args:` 行和每個環境變數作為 `NAME=[REDACTED]`。值被隱藏，因為它們可能攜帶憑證。 **外掛 MCP 工具名稱**： 來自外掛捆綁的 MCP 伺服器的工具在其可呼叫名稱中包含外掛名稱和伺服器金鑰。完整形式是 `mcp__plugin____`，其中 `A-Z`、`a-z`、`0-9`、`_` 和 `-` 以外的任何字元都被替換為 `_`。對於名為 `my-plugin` 的外掛中捆綁的 `database-tools` 伺服器，`query` 工具可呼叫為： ``` mcp__plugin_my-plugin_database-tools__query ``` 在 [權限規則](/docs/zh-TW/permissions)、skill 的 `allowed-tools` 列表、[subagent 的 `tools` 欄位](/docs/zh-TW/sub-agents#available-tools)或 [hook matcher](/docs/zh-TW/hooks#match-mcp-tools) 中參考工具時使用此完整名稱。針對裸伺服器金鑰編寫的 hook matcher（例如 `mcp__database-tools__.*`）永遠不會針對外掛捆綁的伺服器觸發。 伺服器本身在範圍名稱 `plugin::` 下註冊，例如 `plugin:my-plugin:database-tools`。在預期已設定伺服器名稱的地方使用該名稱，例如 [`mcp_tool` hook 的 `server` 欄位](/docs/zh-TW/hooks#mcp-tool-hook-fields)。 請參閱 [外掛元件參考](/docs/zh-TW/plugins/components#mcp-servers)以取得有關使用外掛捆綁 MCP 伺服器的詳細資訊。

MCP 安裝範圍

MCP servers 可以在三個不同的範圍級別進行配置。您選擇的範圍控制 server 在哪些專案中載入，以及配置是否與您的團隊共享。管理員也可以透過[受管配置](#managed-mcp-configuration)為每個使用者部署或提供 servers。 | 範圍 | 載入位置 | 與團隊共享 | 儲存位置 | | - | - | - | - | | [Local](#local-scope) | 僅目前專案 | 否 | `~/.claude.json` | | [Project](#project-scope) | 僅目前專案 | 是，透過版本控制 | 專案根目錄中的 `.mcp.json` | | [User](#user-scope) | 您的所有專案 | 否 | `~/.claude.json` |

Local scope

Local scope 是預設值。本機範圍的 server 僅在您新增它的專案中載入，並對您保持私密。Claude Code 將其儲存在 `~/.claude.json` 中該專案的路徑下，因此相同的 server 不會出現在您的其他專案中。使用本機範圍進行個人開發 servers、實驗配置或包含您不想在版本控制中的認證的 servers。 MCP servers 的「local scope」術語與一般本機設定不同。MCP 本機範圍的 servers 儲存在 `~/.claude.json` (您的主目錄) 中，而一般本機設定使用 `.claude/settings.local.json` (在專案目錄中)。請參閱 [Settings](/docs/zh-TW/settings#where-settings-live) 了解設定檔案位置的詳細資訊。 ```bash theme={null} # 新增本機範圍的 server (預設) claude mcp add --transport http stripe https://mcp.stripe.com # 明確指定本機範圍 claude mcp add --transport http stripe --scope local https://mcp.stripe.com ``` 當您從 `/path/to/your/project` 執行命令時，該命令會將 server 寫入 `~/.claude.json` 中您目前專案的項目。下面的範例顯示結果： ```json theme={null} { "projects": { "/path/to/your/project": { "mcpServers": { "stripe": { "type": "http", "url": "https://mcp.stripe.com" } } } } } ```

Project scope

Project scope 的 servers 透過在專案根目錄中儲存配置在 `.mcp.json` 檔案中來啟用團隊協作。當您新增 project scope 的 server 時，Claude Code 會自動建立或更新此檔案，使用適當的配置結構。將 `.mcp.json` 簽入版本控制，以便您的團隊中的每個人都能取得相同的 MCP 工具和服務。 ```bash theme={null} # 新增 project scope 的 server claude mcp add --transport http shared-server --scope project https://example.com/mcp ``` 產生的 `.mcp.json` 檔案遵循標準化格式： ```json theme={null} { "mcpServers": { "shared-server": { "type": "http", "url": "https://example.com/mcp" } } } ``` 出於安全考慮，Claude Code 在互動式工作階段中使用來自 `.mcp.json` 檔案的 project scope servers 之前會提示批准。若要重設這些批准選擇，請執行 `claude mcp reset-project-choices`。 在 `claude -p` 執行、[Agent SDK](/docs/zh-TW/headless) 工作階段和[雲端工作階段](/docs/zh-TW/claude-code-on-the-web)中，Claude Code 無法顯示該提示：它會載入 project scope servers 而不詢問。Claude Code 也會在您以 `bypassPermissions` 模式啟動的工作階段中跳過提示，其中在您的使用者設定或受管設定中設定了 [`skipDangerousModePermissionPrompt`](/docs/zh-TW/settings-reference#skipdangerousmodepermissionprompt)。若要無論如何保持 server 不被使用： * 將其新增到 [`disabledMcpjsonServers`](/docs/zh-TW/settings-reference#disabledmcpjsonservers)，這會在每個權限模式中阻止它。 * 使用 [`--setting-sources`](/docs/zh-TW/cli-reference#cli-flags) 或 SDK 的 `settingSources` 選項完全排除專案設定。 * 使用 [`--strict-mcp-config`](/docs/zh-TW/cli-reference#cli-flags) 啟動工作階段。Claude Code 隨後只使用您透過 `--mcp-config` 傳遞的 MCP servers。跳過 Claude Code 未載入的 project scope servers 的批准提示需要 Claude Code v2.1.246 或更新版本；在 v2.1.246 之前，嚴格工作階段仍會等待它們的批准，這會導致背景工作階段在啟動時等待。請參閱[使用 managed-mcp.json 進行獨佔控制](/docs/zh-TW/managed-mcp#exclusive-control-with-managed-mcp-json)了解該旗標在受管 MCP 檔案下的作用。 [Project server 批准和工作區信任](#project-server-approvals-and-workspace-trust)涵蓋提交到儲存庫的批准如何與工作區信任互動。

User scope

User scope 的 servers 儲存在 `~/.claude.json` 中，並提供跨專案可存取性，使其在您機器上的所有專案中可用，同時對您的使用者帳戶保持私密。此範圍非常適合個人公用程式 servers、開發工具或您在不同專案中經常使用的服務。 ```bash theme={null} # 新增使用者 server claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic ```

Scope 階層和優先順序

當相同的 server 在多個位置定義時，Claude Code 連接到它一次，使用來自最高優先順序來源的定義。整個 server 項目來自該來源；欄位不會跨範圍合併。 1. Local scope 2. Project scope 3. User scope 4. [Plugin-provided servers](/docs/zh-TW/plugins/components#mcp-servers) 5. [claude.ai connectors](#use-mcp-servers-from-claude-ai) Claude Code 按名稱符合三個範圍中的重複項。它按端點符合 plugins 和 connectors，因此指向與上述 server 相同 URL 或命令的端點被視為重複項。 當兩個 URL 拼寫僅在配置或主機的字母大小寫、配置的預設連接埠 (例如 `https` 上的 `:443`) 或尾部斜線上有所不同時，它們被視為相同的端點。不同的路徑、查詢字串、使用者資訊或非預設連接埠會使兩個 servers 不同。 您的組織透過 [`managedMcpServers`](/docs/zh-TW/managed-mcp#provide-servers-through-managed-settings) 受管設定提供的 server 排名高於所有這些，因此當其中一個重複它時，Claude Code 連接組織的定義。需要 Claude Code v2.1.259 或更新版本。 如果您在[桌面應用程式的 Code 標籤](/docs/zh-TW/desktop#mcp-servers-from-the-claude-desktop-chat-app)中開啟本機工作階段，其中 `~/.claude.json` (user scope) 的頂層和 `.mcp.json` 中有相同的 stdio server 名稱，Code 標籤會使用 `~/.claude.json` 定義。

`.mcp.json` 中的環境變數擴展

Claude Code 支援 `.mcp.json` 檔案中的環境變數擴展，允許團隊共享配置，同時保持機器特定路徑和 API 金鑰等敏感值的靈活性。

支援的語法

* `${VAR}`：擴展為環境變數 `VAR` 的值 * `${VAR:-default}`：如果設定了 `VAR`，則擴展為 `VAR`，否則使用 `default`

擴展位置

環境變數可以在以下位置擴展： * `command`：server 可執行檔路徑 * `args`：命令列引數 * `env`：傳遞給 server 的環境變數 * `url`：對於 HTTP server 類型 * `headers`：對於 HTTP server 驗證

使用變數擴展的範例

```json theme={null} { "mcpServers": { "api-server": { "type": "http", "url": "${API_BASE_URL:-https://api.example.com}/mcp", "headers": { "Authorization": "Bearer ${API_KEY}" } } } } ```

未設定預設值的未設定變數

如果參考的環境變數未設定且沒有預設值，配置仍會載入：Claude Code 在 `claude mcp list` 輸出中為該 server 報告遺漏變數警告，並按原樣使用未擴展的 `${VAR}` 文字。設定變數或新增 `:-default` 後備，以便 server 使用您預期的值啟動。在遠端 server 的 `url` 和 `headers` 中，某些認證變數[讀取為空](#credential-variables-that-read-as-empty)，沒有警告。

讀取為空的認證變數

在遠端 server 的 `url` 和 `headers` 中，Claude Code 從您的環境讀取認證變數為空，而不是擴展它們。這可防止專案的 `.mcp.json` 或 plugin 將您的 Claude Code 或雲端提供者認證傳送到它命名的 server。如果您寫入 `Bearer ${ANTHROPIC_AUTH_TOKEN}`，server 會收到 `Bearer ` 且沒有認證，並拒絕請求，通常會出現 `401`。Claude Code 將其報告為連接失敗。 涵蓋的名稱包括： * Claude Code 自己的認證，例如 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` * 您的雲端提供者的認證，例如 `AWS_BEARER_TOKEN_BEDROCK` * 您的環境攜帶的其他認證，例如 `HTTPS_PROXY` 和 `NPM_TOKEN` 涵蓋的名稱讀取為空，無論您是否設定了變數，其上的 `:-default` 後備會被忽略。提供者基礎 URL (例如 `ANTHROPIC_BASE_URL`) 仍會擴展，因此 `"url": "${ANTHROPIC_BASE_URL}/mcp"` 有效，除非 URL 的值本身嵌入認證，例如使用者名稱和密碼。 此集合外的名稱 (例如 `API_KEY`) 按原樣擴展。若要為 server 提供涵蓋的認證之一，請將其複製到具有您自己名稱的變數中，並改為參考該名稱。 當遠端 server 的 `url` 或 `headers` 參考您已設定的涵蓋變數時，Claude Code 在偵錯日誌行中命名它。若要讀取該行，請執行 `claude --debug-file /tmp/claude-debug.log` 並在該檔案中搜尋 `never expanded toward a remote server`。

參考在 `/mcp` 和 CLI 輸出中的顯示方式

對於本機、專案或使用者[範圍](#mcp-installation-scopes)中的 server，以下表面按名稱而不是其解析值顯示 `${VAR}` 參考： * server 的 `/mcp` 詳細檢視中的 URL 或命令行 * `claude mcp list` 和 `claude mcp get` 輸出 `/mcp` 詳細檢視在 Claude Code v2.1.268 或更新版本中以這種方式顯示參考。 對於您的組織透過 `managedMcpServers` 設定提供的 server，這些表面顯示[僅 URL 的主機](/docs/zh-TW/managed-mcp#what-users-can-see-and-change)。 若要檢查當連接失敗時 `claude mcp list`、`claude mcp get` 和 `/mcp` 顯示的內容，請參閱 [Server 狀態詳細資訊](#server-status-detail)。

實用範例

範例：連接到 GitHub 進行程式碼審查

GitHub 的遠端 MCP server 使用作為標頭傳遞的 GitHub 個人存取 token 進行驗證。若要取得一個，請開啟您的 [GitHub token 設定](https://github.com/settings/personal-access-tokens)，產生一個新的細粒度 token，具有對您希望 Claude 使用的儲存庫的存取權，然後新增 server： ```bash theme={null} claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \ --header "Authorization: Bearer YOUR_GITHUB_PAT" ``` 將 `YOUR_GITHUB_PAT` 替換為您的個人存取 token。`claude mcp add` 命令會儲存設定而不驗證憑證，因此此處接受預留位置值，但伺服器稍後會無法連接。若要驗證連接，請執行 `/mcp` 並檢查該伺服器的列是否顯示核取記號。具有錯誤憑證的伺服器則會顯示 ✘，其[失敗詳細資訊](#server-status-detail)包括伺服器傳回的 HTTP 狀態，例如 401。 然後使用 GitHub： ```text wrap theme={null} 審查 PR #456 並建議改進 ``` ```text wrap theme={null} 為我們剛發現的錯誤建立新問題 ``` ```text wrap theme={null} 顯示所有指派給我的開放 PRs ```

範例：查詢您的 PostgreSQL 資料庫

[DBHub](https://github.com/bytebase/dbhub)，`@bytebase/dbhub` 套件，是一個 MCP server，可將 Claude 連接到您在 `--dsn` 中傳遞的連接字串的關聯式資料庫。在連接字串中使用唯讀資料庫使用者，以便 Claude 執行的查詢無法修改資料： ```bash theme={null} claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \ --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics" ``` 若要確認伺服器已啟動，請執行 `/mcp` 並檢查 `db` 列是否顯示核取記號。 然後自然地查詢您的資料庫： ```text wrap theme={null} 本月我們的總收入是多少？ ``` ```text wrap theme={null} 顯示 orders 表的 schema ``` ```text wrap theme={null} 找到 90 天內未進行購買的客戶 ```

使用遠端 MCP 伺服器進行身分驗證

許多雲端 MCP 伺服器需要身分驗證。Claude Code 支援 OAuth 2.0 以進行安全連線。 當伺服器回應 `401 Unauthorized` 或 `403 Forbidden` 時，Claude Code 會將遠端伺服器標記為需要身分驗證。Claude Code 顯示的內容取決於伺服器： * 對於您尚未登入的伺服器，任一狀態碼都會在 `/mcp` 中標記它，以便您完成 OAuth 流程。 * 對於 [claude.ai 連接器](#use-mcp-servers-from-claude-ai)，由 claude.ai 拒絕您的工作階段 token 導致的 `401` 不會標記連接器，因為重新授權連接器無法修復您的登入。Claude Code 改為顯示 [工作階段 token 被拒絕狀態](/docs/zh-TW/errors#claude-ai-rejected-the-session-token)。 * 對於您在 `headers` 中或透過 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 設定 `Authorization` 標頭的伺服器，連線時的 `401` 或 `403` 不會標記伺服器，因為要修復的憑證是您設定的憑證。Claude Code 改為報告連線失敗。如果您從 `${VAR}` 參考設定該標頭，請檢查該變數是否是 Claude Code [讀取為空](#credential-variables-that-read-as-empty) 的變數之一。 * 對於 [傳遞到雲端工作階段的連接器](#how-connectors-reach-claude-code)，Claude Code 不會執行登入流程，因為工作階段的代理伺服器使用您在 claude.ai 中授予的授權向連接器進行身分驗證。當那裡的連接器需要再次授權時，請在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 重新連接它，而不是從工作階段進行。 當對您已登入的 OAuth 伺服器的請求傳回 `401 Unauthorized` 時，Claude Code 會重新整理儲存的 token、重新連接並重試請求一次。只有在該重試也失敗時，它才會在 `/mcp` 中標記伺服器。 當伺服器拒絕儲存的重新整理 token 時，Claude Code 會立即顯示指向 `/mcp` 的通知。開啟 `/mcp` 並在伺服器上選擇 **Re-authenticate** 以在下一個工具呼叫失敗之前再次登入。 傳回指向其授權伺服器的 `WWW-Authenticate` 標頭的自訂伺服器會獲得與任何其他遠端伺服器相同的自動探索。 當一個或多個已設定的伺服器需要身分驗證時，Claude Code 也會顯示啟動通知，因此您不必開啟 `/mcp` 來探索哪些伺服器需要登入。該通知只計算您可以從 Claude Code 登入的伺服器。在 v2.1.218 之前，它也計算在 claude.ai 中未連接的 [claude.ai 連接器](#use-mcp-servers-from-claude-ai)，您只能從 claude.ai 設定進行連接。 該通知會宣佈每個伺服器一次，並在後續啟動時將其排除在計數之外，直到該伺服器已連接並再次需要登入。`/mcp` 仍會列出每個需要登入的伺服器。 `claude -p` 或 Agent SDK 執行沒有 `/mcp` 面板，因此 Claude Code 無法在其中執行 OAuth 流程。若要使用需要身分驗證的伺服器，請先從互動式工作階段完成登入：在工作階段中執行 `/mcp`，或在您的 shell 中執行 `claude mcp login `。當已設定的伺服器在啟用 [工具搜尋](#scale-with-mcp-tool-search) 的 `claude -p` 或 Agent SDK 執行期間需要身分驗證時，Claude Code 會告訴 Claude 該伺服器的工具在您授權之前無法使用。 如果您為伺服器設定了 `headers.Authorization` 且伺服器拒絕該標頭，Claude Code 會報告連線失敗，而不是回退到 OAuth。檢查 token 對 MCP 端點是否有效，或移除標頭以使用 OAuth 流程。 如果您已在 [MCP 快速入門](/docs/zh-TW/mcp-quickstart#connect-a-server-that-requires-sign-in) 中新增了 `sentry` 伺服器，請跳過此步驟：在相同範圍使用相同伺服器名稱再次執行 `claude mcp add` 會失敗，並顯示 `MCP server sentry already exists in local config`。否則，執行： ```bash theme={null} claude mcp add --transport http sentry https://mcp.sentry.dev/mcp ``` 在 Claude Code 中，使用命令： ```text wrap theme={null} /mcp ``` 然後按照瀏覽器中的步驟登入。 提示： * 身分驗證 token 會安全地儲存並自動重新整理 * 使用 `/mcp` 功能表中的「Clear authentication」撤銷存取權 * 如果瀏覽器未自動開啟，請複製提供的 URL 並手動開啟 * 如果瀏覽器重新導向在驗證後因連線錯誤而失敗，請將瀏覽器位址列中的完整回呼 URL 貼到 Claude Code 中出現的 URL 提示中 * OAuth 身分驗證適用於 HTTP 伺服器

從命令列進行身分驗證

`claude mcp login ` 命令直接從您的 shell 執行已設定伺服器的 OAuth 流程，因此您不需要在工作階段內開啟 `/mcp` 面板。對於 claude.ai 連接器，請按照 [從您的 shell 再次授權連接器](/docs/zh-TW/remote-control#authorize-a-connector-again-from-your-shell) 操作。 ```bash theme={null} claude mcp login sentry ``` 若要稍後清除儲存的憑證，請執行 `claude mcp logout `。 `claude mcp login` 會偵測何時沒有本機瀏覽器可用（例如在 SSH 工作階段期間或在沒有顯示伺服器的 Linux 上），並列印授權 URL，而不是嘗試開啟瀏覽器。在您的本機機器上開啟 URL，然後將瀏覽器位址列中的完整重新導向 URL 貼回提示。該命令需要互動式終端機進行貼上步驟，因此請使用 `ssh -t` 連接。傳遞 `--no-browser` 以強制 URL 提示，即使偵測到本機瀏覽器。 ```bash theme={null} claude mcp login sentry --no-browser ```

使用固定的 OAuth 回呼連接埠

某些 MCP 伺服器需要預先註冊的特定重新導向 URI。根據預設，Claude Code 為 OAuth 回呼選擇隨機可用連接埠。使用 `--callback-port` 固定連接埠，使其符合 `http://localhost:PORT/callback` 形式的預先註冊重新導向 URI。如果在 Claude Code v2.1.229 上登入因重新導向 URI 不符而失敗，請參閱 [使用預先設定的 OAuth 憑證](#use-pre-configured-oauth-credentials) 下的版本說明。 您可以單獨使用 `--callback-port`（使用動態用戶端註冊）或與 `--client-id` 一起使用（使用預先設定的憑證）。 ```bash theme={null} # Fixed callback port with dynamic client registration claude mcp add --transport http \ --callback-port 8080 \ my-server https://mcp.example.com/mcp ```

使用預先設定的 OAuth 憑證

某些 MCP 伺服器不支援透過動態用戶端註冊進行自動 OAuth 設定。如果您看到類似「Incompatible auth server: does not support dynamic client registration」的錯誤，伺服器需要預先設定的憑證。Claude Code 也支援使用用戶端 ID 中繼資料文件 (CIMD) 而不是動態用戶端註冊的伺服器，並自動探索這些伺服器。如果自動探索失敗，請先透過伺服器的開發人員入口網站註冊 OAuth 應用程式，然後在新增伺服器時提供憑證。 透過伺服器的開發人員入口網站建立應用程式，並記下您的用戶端 ID 和用戶端密碼。 如果註冊表單要求重新導向 URI，請選擇任何可用連接埠並輸入 `http://localhost:PORT/callback`（使用該連接埠）。您將在下一步中使用相同的連接埠。 在 v2.1.229 中，Claude Code 改為傳送 `http://127.0.0.1:PORT/callback`，而精確符合已註冊重新導向 URI 的伺服器會因重新導向 URI 不符而拒絕登入。Claude Code v2.1.231 恢復了 `localhost` 形式。若要在 v2.1.229 上復原，請升級 Claude Code，或暫時將 `http://127.0.0.1:PORT/callback` 形式新增到伺服器的已註冊重新導向 URI。 這些標籤涵蓋兩個命令：`claude mcp add` 將您的用戶端 ID 和回呼連接埠作為旗標，`claude mcp add-json` 在 `oauth` 物件中採用它們。如果您註冊了重新導向 URI，請將回呼連接埠設定為該 URI 中的連接埠。 使用 `--client-id` 傳遞您應用程式的用戶端 ID。`--client-secret` 旗標會以遮罩輸入提示輸入密碼： ```bash theme={null} claude mcp add --transport http \ --client-id your-client-id --client-secret --callback-port 8080 \ my-server https://mcp.example.com/mcp ``` 在 JSON 設定中包含 `oauth` 物件，並將 `--client-secret` 作為單獨的旗標傳遞： ```bash theme={null} claude mcp add-json my-server \ '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \ --client-secret ``` 若要僅固定回呼連接埠並讓 Claude Code 自動註冊用戶端，請單獨設定 `callbackPort`： ```bash theme={null} claude mcp add-json my-server \ '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}' ``` 透過環境變數設定密碼以跳過互動式提示： ```bash theme={null} MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \ --client-id your-client-id --client-secret --callback-port 8080 \ my-server https://mcp.example.com/mcp ``` 在 Claude Code 中執行 `/mcp` 並按照瀏覽器登入流程。 提示： * 用戶端密碼安全地儲存在您的系統鑰匙圈 (macOS) 或憑證檔案中，而不是在您的設定中 * 您只能在新增伺服器時設定用戶端密碼。當您使用 `claude mcp login` 或從 `/mcp` 進行身分驗證時，Claude Code 會使用儲存的密碼，不會提示輸入密碼或讀取 `MCP_CLIENT_SECRET` * 若要稍後新增或變更密碼，請使用 `claude mcp remove ` 移除伺服器，然後使用 `--client-secret` 和相同的 `--scope` 再次新增它 * 如果伺服器使用沒有密碼的公開 OAuth 用戶端，請僅使用 `--client-id` 而不使用 `--client-secret` * 這些旗標僅適用於 HTTP 和 SSE 傳輸。它們對 stdio 伺服器沒有影響 * 使用 `claude mcp get ` 驗證為伺服器設定了 OAuth 憑證

覆寫 OAuth 中繼資料探索

將 Claude Code 指向特定的 OAuth 授權伺服器中繼資料 URL 以繞過預設探索鏈。當 MCP 伺服器的標準端點出錯時，或當您想透過內部代理伺服器路由探索時，設定 `authServerMetadataUrl`。根據預設，Claude Code 首先檢查 `/.well-known/oauth-protected-resource` 的 RFC 9728 受保護資源中繼資料，然後回退到 `/.well-known/oauth-authorization-server` 的 RFC 8414 授權伺服器中繼資料。 在 `.mcp.json` 中您伺服器設定的 `oauth` 物件中設定 `authServerMetadataUrl`： ```json theme={null} { "mcpServers": { "my-server": { "type": "http", "url": "https://mcp.example.com/mcp", "oauth": { "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration" } } } } ``` URL 必須使用 `https://`。中繼資料 URL 的 `scopes_supported` 會覆寫上游伺服器公告的範圍。

限制 OAuth 範圍

設定 `oauth.scopes` 以固定 Claude Code 在授權流程期間請求的範圍。這是當上游授權伺服器公告的範圍超過您想授予的範圍時，將 MCP 伺服器限制為安全團隊批准的子集的支援方式。該值是單個空格分隔的字串，符合 RFC 6749 §3.3 中的 `scope` 參數格式。 ```json theme={null} { "mcpServers": { "slack": { "type": "http", "url": "https://mcp.slack.com/mcp", "oauth": { "scopes": "channels:read chat:write search:read" } } } } ``` `oauth.scopes` 優先於 `authServerMetadataUrl` 和伺服器在 `/.well-known` 探索的範圍。將其保留為未設定以讓 MCP 伺服器決定請求的範圍集。 當未設定 `oauth.scopes` 時，Claude Code 不會請求自動探索的授權伺服器中繼資料中的完整 `scopes_supported` 目錄。從已設定的 `authServerMetadataUrl` 擷取的中繼資料仍會將其 `scopes_supported` 作為請求的範圍提供。 如果授權伺服器在 `scopes_supported` 中公告 `offline_access`，Claude Code 會將其附加到固定範圍，以便可以在不進行新瀏覽器登入的情況下重新整理存取 token。 如果伺服器稍後為工具呼叫傳回 403 `insufficient_scope`，該呼叫會失敗，並顯示 [`needs additional permissions`](/docs/zh-TW/errors#mcp-server-needs-you-to-sign-in-again) 訊息，該訊息指出伺服器請求的範圍。伺服器在 `/mcp` 中顯示為需要身分驗證。 如果該範圍不在您的固定 `oauth.scopes` 中，請新增它，然後執行 `/mcp` 並再次驗證伺服器。Claude Code 請求固定範圍而不是伺服器指出的範圍，因此如果您在不新增它的情況下再次驗證，您獲得的 token 仍然缺少它。

使用動態標頭進行自訂身分驗證

如果您的 MCP 伺服器使用 OAuth 以外的身分驗證方案，例如 Kerberos、短期 token 或內部 SSO，請使用 `headersHelper` 在連線時產生請求標頭。Claude Code 執行命令並將其輸出合併到連線標頭中。 ```json theme={null} { "mcpServers": { "internal-api": { "type": "http", "url": "https://mcp.internal.example.com", "headersHelper": "/opt/bin/get-mcp-auth-headers.sh" } } } ``` 該命令也可以是內聯的： ```json theme={null} { "mcpServers": { "internal-api": { "type": "http", "url": "https://mcp.internal.example.com", "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'" } } } ``` **需求：** * 命令必須將字串鍵值對的 JSON 物件寫入 stdout * Claude Code 在 shell 中執行命令，並在 10 秒後放棄 * Claude Code 根據 [您設定伺服器的位置](#where-the-helper-runs) 選擇命令的工作目錄，因此請將指令碼作為絕對路徑提供或將其放在 `PATH` 上 * 動態標頭會覆寫任何具有相同名稱的靜態 `headers` 一旦 [專案和本機範圍伺服器的信任規則](#trust-a-folder-before-its-headershelper-runs) 允許 helper 執行，Claude Code 會在每次連線時（工作階段開始和重新連接時）重新執行 helper。它不會快取結果，因此您的指令碼負責任何 token 重用。 如果工具呼叫傳回 `401 Unauthorized` 或 `403 Forbidden`，Claude Code 會自動在相同規則下重新執行 helper、使用新標頭重新連接並重試呼叫一次。Claude Code 只有在該重試也失敗時才會在 `/mcp` 中將伺服器標記為需要身分驗證。 當 helper 的輸出包含 `Authorization` 標頭時，Claude Code 會使用該憑證作為伺服器的身分驗證，不會為該伺服器回退到 OAuth。 如果伺服器在連線時拒絕 helper 的憑證，Claude Code 會報告連線失敗，而不是將伺服器標記為需要身分驗證。修復您的 helper 傳回的憑證，然後從 `/mcp` 重新連接以重新執行 helper。 Claude Code 在執行 helper 時設定這些環境變數： | 變數 | 值 | | :- | :- | | `CLAUDE_CODE_MCP_SERVER_NAME` | MCP 伺服器的名稱 | | `CLAUDE_CODE_MCP_SERVER_URL` | MCP 伺服器的 URL | | `CLAUDE_PLUGIN_ROOT` | 外掛程式的根目錄。僅當 [外掛程式](/docs/zh-TW/plugins/components#mcp-servers) 提供伺服器時設定 | 使用這些來編寫為多個 MCP 伺服器服務的單個 helper 指令碼。 外掛程式提供的 `headersHelper` 無法參考外掛程式的 [`${user_config.*}`](/docs/zh-TW/plugins/manifest-reference#user-configuration) 值，因為命令透過 shell 執行。Claude Code 報告伺服器設定錯誤，並顯示 [錯誤](/docs/zh-TW/errors#plugin-command-references-user-config)，不會替換該值。改為將 `${user_config.KEY}` 放在伺服器的 `headers` 欄位中，該欄位不會進行 shell 解析，或讓 helper 指令碼從設定檔讀取該值。在 v2.1.207 之前，`headersHelper` 會替換 `${user_config.*}` 值。

Helper 執行的位置

Claude Code 從宣告伺服器的設定中選擇 `headersHelper` 命令的工作目錄。Claude 在 Bash 中執行的 `cd` 不會移動它，[`/cd`](/docs/zh-TW/permissions#move-the-session-to-another-directory) 僅對從工作階段主要工作目錄執行的伺服器移動它。下表中的每一行給出您的 `headersHelper` 命令中相對路徑解析的目錄。 | 您設定伺服器的位置 | 工作目錄 | | :- | :- | | [外掛程式](/docs/zh-TW/plugins/components#mcp-servers) | 外掛程式的根目錄 | | 專案 `.mcp.json` 或 [本機範圍](#local-scope) 伺服器 | 宣告伺服器的專案目錄 | | 您專案中的 agent 檔案、來自 SDK 的 `mcpServers` 選項或 `setMcpServers()` 方法的伺服器，或 [`--mcp-config`](/docs/zh-TW/cli-reference) | 工作階段的 [主要工作目錄](/docs/zh-TW/permissions#working-directories) | | [使用者範圍](#user-scope)、[受管 MCP](/docs/zh-TW/managed-mcp)、[claude.ai 連接器](#use-mcp-servers-from-claude-ai)，或來自您專案外的 agent 檔案，包括來自 `--add-dir` 目錄的檔案 | 您的設定目錄，`~/.claude`，除非您設定 [`CLAUDE_CONFIG_DIR`](/docs/zh-TW/env-vars) | 在 v2.1.238 之前，Claude Code 也從您啟動它的目錄執行使用者範圍、受管和 claude.ai 連接器伺服器的 helper，以及來自您專案外的 agent 檔案的 helper。

Helper 可以讀取哪些變數

儲存庫或外掛程式提供的 `headersHelper` 是您未編寫的命令，因此 Claude Code 執行它時不會從您的環境中提供憑證變數，例如 `ANTHROPIC_API_KEY`。您設定伺服器的位置決定是否適用： * **已移除**：專案 `.mcp.json` 或外掛程式中的伺服器，以及來自您專案或 `--add-dir` 目錄的 agent 檔案中的內聯伺服器 * **未移除**：[使用者](#user-scope) 或 [本機範圍](#local-scope) 的伺服器、[受管 MCP](/docs/zh-TW/managed-mcp) 中的伺服器、來自 [claude.ai 連接器](#use-mcp-servers-from-claude-ai) 的伺服器、由 SDK 或 [`--mcp-config`](/docs/zh-TW/cli-reference) 提供的伺服器，以及來自 `~/.claude/agents/`、受管設定或使用 `--agents` 傳遞的 agent 檔案中的內聯伺服器 除了 Git 的 `GIT_CONFIG_KEY_` 變數外，Claude Code 會從您的環境中移除名稱看起來像憑證的每個變數，例如名稱中包含 `TOKEN`、`SECRET`、`PASSWORD`、`KEY` 或 `AUTH` 的名稱（無論大小寫），因此 `ANTHROPIC_API_KEY` 和 `MY_REGISTRY_TOKEN` 都會被移除。Claude Code 也會移除名稱不遵循該模式的固定憑證變數清單，例如 `ANTHROPIC_CUSTOM_HEADERS`。 當這適用於您的 helper 時，讓指令碼從檔案或憑證存放區讀取其憑證。如果伺服器的 `url` [帶有這些變數之一的即時值](#environment-variable-expansion-in-mcp-json)，例如 `MY_REGISTRY_TOKEN`，helper 接收的 `CLAUDE_CODE_MCP_SERVER_URL` 值也會將該部分替換為 `REDACTED`。

在 headersHelper 執行之前信任資料夾

Claude Code 將 `headersHelper` 作為任意 shell 命令執行。對於專案 `.mcp.json` 中或 [本機範圍](#local-scope) 的伺服器，它只在您接受宣告伺服器的專案目錄的 [信任對話方塊](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust) 後執行 helper。在 v2.1.238 之前，`claude -p` 或 SDK 工作階段執行這些 helper 而不檢查信任，互動式工作階段在您信任父資料夾後執行它們。 * **不計算的信任**：父資料夾的信任，以及 `claude -p` 或 SDK 工作階段為 [設定檔中的 hook](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder) 獲得的自動信任 * **直到您信任資料夾**：Claude Code 僅使用其靜態 `headers` 連接伺服器。在 `claude -p` 或 SDK 工作階段中，它也會為每個伺服器將一行 [`headersHelper not run`](/docs/zh-TW/errors#headershelper-not-run) 列印到 stderr，告訴您如何授予信任。 * **無對話方塊的信任**：在 `~/.claude.json` 中將 `projects[""].hasTrustDialogAccepted` 設定為 `true`。`` 是 [專案允許規則和工作區信任](/docs/zh-TW/permissions#project-allow-rules-and-workspace-trust) 所說明 Claude Code 用來作為信任鍵的資料夾。 Claude Code 將相同規則應用於在 [agent 檔案](/docs/zh-TW/sub-agents#scope-mcp-servers-to-a-subagent) 中內聯宣告的伺服器，檢查該 agent 檔案來自何處：您的專案（對於其 `.claude/agents/` 目錄中的檔案）或 `--add-dir` 目錄。直到您 [信任該專案或目錄本身](/docs/zh-TW/permissions#what-runs-before-you-trust-a-folder)，Claude Code 完全不會載入伺服器，因此其 helper 也永遠不會執行。

從 JSON 配置新增 MCP servers

如果您有 MCP server 的 JSON 配置，您可以直接新增它： ```bash theme={null} # 基本語法 claude mcp add-json '' # 範例：使用 JSON 配置新增 HTTP server claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}' # 範例：使用 JSON 配置新增 stdio server claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}' # 範例：使用預先配置的 OAuth 認證新增 HTTP server claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret ``` ```bash theme={null} claude mcp get weather-api ``` 提示： * 確保 JSON 在您的 shell 中正確逸出 * JSON 必須符合 MCP server 配置架構 * 您可以使用 `--scope user` 將 server 新增到您的使用者配置，而不是專案特定的配置

從 Claude Desktop 匯入 MCP servers

如果您已在 Claude Desktop 中配置了 MCP servers，您可以匯入它們： ```bash theme={null} # 基本語法 claude mcp add-from-claude-desktop ``` 執行命令後，您會看到一個互動式對話框，允許您選擇要匯入的 servers。 ```bash theme={null} claude mcp list ``` 透過 `claude mcp` 命令新增的伺服器名稱只能包含字母、數字、連字號和底線。Claude Desktop 不會套用該限制，因此名稱包含任何其他字元（例如空格）的 Claude Desktop 伺服器無法匯入。匯入會報告它拒絕的每個名稱，並仍會匯入您選擇的其他伺服器。 提示： * 此功能僅適用於 macOS 和 Windows Subsystem for Linux (WSL) * 它從這些平台上的標準位置讀取 Claude Desktop 配置檔案 * 使用 `--scope user` 旗標將 servers 新增到您的使用者配置 * 匯入的 servers 將具有與 Claude Desktop 中相同的名稱（當名稱只包含字母、數字、連字號和底線時）。Claude Code 會報告名稱包含任何其他字元的伺服器並跳過它 * 如果已存在相同名稱的 servers，它們將獲得數字尾碼（例如，`server_1`）

使用來自 claude.ai 的 MCP 伺服器

如果您已使用 [claude.ai](https://claude.ai) 帳戶登入 Claude Code，您在 claude.ai 中新增的 MCP 伺服器（稱為 [connectors](https://claude.com/docs/connectors)）會自動在 Claude Code 中可用： 在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 新增伺服器。在 Team 和 Enterprise 方案上，只有管理員可以新增伺服器。 在 claude.ai 中完成任何必要的驗證步驟。 在 Claude Code 中，使用命令： ```text wrap theme={null} /mcp ``` 來自 claude.ai 的伺服器會出現在清單中，並有指示器顯示它們來自 claude.ai。 Anthropic 也自行提供一些 connectors，無需您或管理員新增。在可使用 [Claude Docs](/docs/zh-TW/artifacts#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) 中說明。 當您的組織在 claude.ai 中管理其驗證時，Claude Code 會在 `/mcp` 和 [`/plugin`](/docs/zh-TW/plugins/install) 管理員中將 connector 標記為 `managed`。Managed 狀態不會改變 Claude Code 連接到 connector 的方式，也不會改變您組織的 [工具控制](#organization-controls-on-connector-tools) 的應用方式。 您從未登入過的 Connectors 會在 claude.ai 區段末尾的 `Show unused connectors` 列後面摺疊，因此組織佈建的清單不會填滿面板。選擇該列以展開它們。您之前登入過的 connector 即使目前需要重新驗證，仍會保持可見。 Connectors 來自 claude.ai 時，只有在您的作用中 [驗證方法](/docs/zh-TW/authentication#authentication-precedence) 是 claude.ai 訂閱登入時才會擷取。即使您之前執行過 `/login`，在以下情況下也不會載入： * `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 處於作用中 * Amazon Bedrock 或 Google Cloud 的 Agent Platform 等第三方提供者處於作用中 * `ANTHROPIC_PROFILE`、federation 變數或作用中的 [Anthropic 設定檔](/docs/zh-TW/authentication#anthropic-profiles-and-federation-credentials) 提供認證 * `CLAUDE_CODE_OAUTH_TOKEN` 持有來自 [`claude setup-token`](/docs/zh-TW/authentication#generate-a-long-lived-token) 的權杖，該權杖只能進行模型請求 如果 `/mcp` 未列出您新增的 connector，請執行 `/status` 以確認哪個驗證方法處於作用中。取消設定該環境變數、移除 `apiKeyHelper` 設定，或 [關閉設定檔](/docs/zh-TW/authentication#anthropic-profiles-and-federation-credentials)，然後執行 `/login` 以選擇您的 claude.ai 帳戶。 如果暫時性網路問題導致您的工作階段啟動時無法載入 connector 清單，Claude Code 會在背景中重試擷取最多三次，一旦重試成功，connectors 就會出現。如果它們仍未出現，請重新啟動 Claude Code 以再次擷取清單。 如果 `/mcp` 顯示 connector 為 `session token rejected`，或其詳細檢視顯示 [`claude.ai rejected the session token`](/docs/zh-TW/errors#claude-ai-rejected-the-session-token)，則 claude.ai 拒絕了來自您 Claude Code 登入的權杖。再次授權 connector 不會清除此狀態，因為被拒絕的不是 connector 在 claude.ai 中的授權。若要清除它： 1. 執行 `/login` 以再次登入。 2. 從 `/mcp` 重新連接 connector。 在 v2.1.222 之前，Claude Code 將 connectors 標記為需要驗證，授權它們無法解決此問題。 您在 Claude Code 中新增的伺服器會 [優先於](#scope-hierarchy-and-precedence) 指向相同 URL 的 claude.ai connector。發生這種情況時，`/mcp` 會將 connector 列為隱藏，並顯示如何移除重複項（如果您寧願使用 connector）。 某些 Anthropic 託管的 connectors（例如 Microsoft 365、Gmail 和 Google Calendar）不支援來自 Claude Code 的本機 OAuth，因為上游身分識別提供者只接受 claude.ai 註冊的重新導向 URL。當您使用 `claude mcp add` 或在 `.mcp.json` 中新增的伺服器指向這些主機之一，且您從 `/mcp` 或使用 `claude mcp login` 登入時，Claude Code 會顯示 [`is Anthropic-hosted and doesn't support local OAuth`](/docs/zh-TW/errors#anthropic-hosted-and-doesnt-support-local-oauth)，指導您改為在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 連接服務。 在您使用 `claude mcp remove ` 移除您的項目並在 claude.ai 上連接服務後，connector 會自動出現在 Claude Code 中。

Connectors 如何到達 Claude Code

哪些設定控制 claude.ai connector 取決於您的工作階段在何處執行，因為只有某些工作階段本身從 claude.ai 擷取 connectors。下表中的每一列命名 connectors 在一種工作階段中的到達方式及其控制方式。桌面應用程式的 [WSL 工作階段](/docs/zh-TW/desktop-wsl#what-works-in-a-wsl-session) 沒有列，因為 connectors 在其中尚不可用。 | 工作階段執行位置 | Connectors 如何到達 | 控制它們的因素 | | :- | :- | :- | | Terminal、[VS Code](/docs/zh-TW/vs-code)、[JetBrains](/docs/zh-TW/jetbrains) 和 [Agent SDK](/docs/zh-TW/agent-sdk/claude-code-features) 工作階段 | Claude Code 從 claude.ai 擷取它們 | 本節中的設定和 [managed MCP 設定](/docs/zh-TW/managed-mcp) | | [Cloud 工作階段](/docs/zh-TW/claude-code-on-the-web) | 雲端主機傳入它們 | 您的 claude.ai 組織設定，加上到達工作階段的 [allowlist 和 denylist](/docs/zh-TW/managed-mcp#policy-based-control-with-allowlists-and-denylists) 設定，以及執行它的主機上的任何 `managed-mcp.json` | | [桌面應用程式](/docs/zh-TW/desktop) 的本機和 SSH 工作階段 | 桌面應用程式在程序中傳遞它們 | 您組織的 [connector 工具控制](#organization-controls-on-connector-tools) 中的 `blocked` 項目 | [`disableClaudeAiConnectors`](#disable-claude-ai-connectors)、`ENABLE_CLAUDEAI_MCP_SERVERS` 和 [`allowAllClaudeAiMcps`](/docs/zh-TW/settings-reference#allowallclaudeaimcps) 只作用於第一列，Claude Code 本身擷取的 connectors。其他兩列在以下方面與其不同： * **Cloud 工作階段**：到達工作階段的 `allowedMcpServers` 和 `deniedMcpServers` 項目（例如透過 [server-managed 設定](/docs/zh-TW/server-managed-settings)）也會篩選傳遞的 connectors。工作階段的代理會重寫每個 connector 的 URL，因此為 connector 自己的 URL 編寫的 `serverUrl` 模式不會符合它。若要在自託管環境中的 URL allowlist 旁邊允許傳遞的 connectors，請新增 [Connector 流量離開您的網路](/docs/zh-TW/self-hosted-environments-deploy#connector-traffic-leaves-your-network) 下列出的 `serverUrl` 項目。當執行工作階段的主機上存在 `managed-mcp.json` 時（例如 [self-hosted runner 主機](/docs/zh-TW/self-hosted-environments-configuration#mcp-servers)），Claude Code 會捨棄傳遞的 connectors，無論您是否設定 `allowAllClaudeAiMcps`。 * **桌面應用程式本機和 SSH 工作階段**：桌面應用程式將 connectors 註冊為程序內 `type: "sdk"` 伺服器，沒有 MCP 設定或 `managed-mcp.json` 到達它們。使用者可以透過在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 斷開連接來將 connector 排除在自己的工作階段之外。組織可以阻止 connector 的 [工具](#organization-controls-on-connector-tools) 或完全 [關閉桌面應用程式中的 Claude Code](/docs/zh-TW/desktop#admin-console-controls)。

組織對 connector 工具的控制

您的組織可以在 [claude.ai connectors](https://claude.com/docs/connectors) 上設定每個工具的控制。Claude Code 在啟動時讀取這些設定並在本機強制執行，除了桌面應用程式的 [本機和 SSH 工作階段](#how-connectors-reach-claude-code)。在那裡，桌面應用程式在傳遞 connector 之前會隱藏 `blocked` 工具，`ask` 設定不會到達 Claude Code，因此它會將工作階段的普通 [權限規則](/docs/zh-TW/permissions) 應用於這些工具，而不是在每次呼叫時提示。在 Claude Code 本身擷取 connectors 的工作階段中，執行 `/mcp` 以查看哪個設定適用於 connector 上的每個工具。 * **工具設定為 `ask`**：Claude Code 會在每次呼叫時提示，原因為 `Your organization requires approval for this tool`。即使在 `acceptEdits`、`auto` 和 `bypassPermissions` [權限模式](/docs/zh-TW/permissions#permission-modes) 中，提示也會出現，且永遠不會提供記住您選擇的選項。符合工具的 [Allow 規則](/docs/zh-TW/permissions) 也不會跳過提示。在 `dontAsk` 模式中（永遠不提示），Claude Code 會改為拒絕呼叫。 * **工具設定為 `blocked`**：Claude Code 在 Claude 看到它之前會篩選出工具，因此它永遠不會出現在工具清單中。在 Claude Code 本身擷取 connectors 的工作階段中，`/mcp` 工具清單仍會顯示工具，標記為 `disabled by your organization`。 桌面應用程式和 claude.ai 聊天應用相同的 `blocked` 設定，因此 Claude 也無法在那裡使用工具，您無法從桌面應用程式的工作階段中隱藏工具，同時在聊天中保持可用。桌面應用程式會跳過所有工具都被阻止的 connector。

停用 claude.ai connectors

Claude Code 只將 [`disableClaudeAiConnectors`](/docs/zh-TW/settings-reference#disableclaudeaiconnectors) 應用於它 [本身擷取](#how-connectors-reach-claude-code) 的 connectors，而不是雲端主機或桌面應用程式傳遞的 connectors。若要關閉它擷取的 connectors，請在任何設定範圍中將設定設為 `true`： ```json theme={null} { "disableClaudeAiConnectors": true } ``` 此設定使用任何來源為真的語義：任何設定來源中的 `true` 優先。簽入的專案 `.claude/settings.json` 可以選擇退出 Claude Code 本身擷取的 connectors，但專案層級的 `false` 無法重新啟用使用者或原則層級 `true` 已停用的 connectors。透過 `--mcp-config` 明確傳遞的伺服器不受影響。 您也可以將 `ENABLE_CLAUDEAI_MCP_SERVERS` 環境變數設為 `false`，這對目前的 shell 工作階段有相同的效果： ```bash theme={null} ENABLE_CLAUDEAI_MCP_SERVERS=false claude ``` 若要阻止個別 claude.ai connectors 而不是全部，請按名稱或 URL 模式將它們新增至 [`deniedMcpServers`](/docs/zh-TW/managed-mcp)。例如，`"claude.ai Slack"` 的 `serverName` 項目會阻止 Slack connector。您也可以執行 `/mcp` 以針對目前專案切換 Claude Code 擷取的任何 connector。

將 Claude Code 用作 MCP 伺服器

您可以將 Claude Code 本身用作 MCP 伺服器，其他應用程式可以連接到它： ```bash theme={null} # Start Claude as a stdio MCP server claude mcp serve ``` 該命令在啟動時不會列印任何內容。stdio MCP 伺服器透過 stdin 和 stdout 進行通訊，因此沉默、被阻止的終端機表示伺服器正在執行並等待用戶端連接。 您可以透過將此設定新增到 claude\_desktop\_config.json 在 Claude Desktop 中使用它： ```json theme={null} { "mcpServers": { "claude-code": { "type": "stdio", "command": "claude", "args": ["mcp", "serve"], "env": {} } } } ``` **設定可執行檔路徑**：`command` 欄位必須參考 Claude Code 可執行檔。如果 `claude` 命令不在您系統的 PATH 中，您需要指定可執行檔的完整路徑。 若要找到完整路徑： ```bash theme={null} which claude ``` 然後在您的設定中使用完整路徑： ```json theme={null} { "mcpServers": { "claude-code": { "type": "stdio", "command": "/full/path/to/claude", "args": ["mcp", "serve"], "env": {} } } } ``` 沒有正確的可執行檔路徑，您會遇到像 `spawn claude ENOENT` 這樣的錯誤。 提示： * 在 Claude Desktop 中，嘗試要求 Claude 讀取目錄中的檔案、進行編輯等。 * 此 MCP 伺服器只向您的 MCP 用戶端公開 Claude Code 的工具，因此您自己的用戶端負責為個別工具呼叫實施使用者確認。 當 Bash 或 PowerShell 工具呼叫結果中的 JSON 文字包含 `backgroundOutputPath` 欄位時，表示該呼叫讓其命令[在背景](/docs/zh-TW/tools-reference#background-commands)中持續執行，例如呼叫設定了 `run_in_background: true`，或命令達到了逾時時間。此欄位提供該命令輸出檔案的路徑。命令完成時不會有任何通知傳送至您的用戶端，且命令完成時檔案也不會寫入結尾行，因此讀取該檔案會顯示目前為止已寫入的輸出。若要偵測結束，請在命令後附加一個標記，例如 `npm test; echo DONE`，並在檔案中尋找該標記。`backgroundOutputPath` 欄位需要 Claude Code v2.1.295 或更新版本。

MCP 輸出限制和警告

當 MCP 工具產生大量輸出時，Claude Code 會幫助管理 token 使用量，以防止淹沒您的對話上下文： * **輸出警告閾值**：當任何 MCP 工具輸出超過 10,000 個 token 時，Claude Code 會顯示警告 * **可設定的限制**：您可以使用 `MAX_MCP_OUTPUT_TOKENS` 環境變數調整允許的最大 MCP 輸出 token 數 * **預設限制**：預設最大值為 25,000 個 token * **範圍**：環境變數適用於未聲明自己限制的工具。設定 [`anthropic/maxResultSizeChars`](#raise-the-limit-for-a-specific-tool) 的工具會針對文字內容使用該值，無論 `MAX_MCP_OUTPUT_TOKENS` 設定為何。傳回影像資料的工具仍受 `MAX_MCP_OUTPUT_TOKENS` 限制 * **超過限制**：當沒有影像內容的成功結果超過 token 限制時，Claude Code 會將其儲存到檔案，並在對話中用命名檔案路徑的訊息取代它，以便 Claude 在需要內容時讀取該檔案。該檔案位於 [`~/.claude/projects/`](/docs/zh-TW/claude-directory#cleaned-up-automatically) 下的工作階段 `tool-results` 目錄中。 * **來自 HTTP 和 SSE 伺服器的回應大小**：當來自 [HTTP](#option-1-add-a-remote-http-server) 或 [SSE](#option-2-add-a-remote-sse-server) 伺服器的回應超過 16 MiB 時，Claude Code 會停止讀取該回應，且請求會失敗。此限制適用於解壓縮後的單一 JSON 回應主體或事件串流中的單一事件。如果您負責維護該伺服器，請減少每個回應傳回的資料量以維持在限制之內，例如將結果分頁 * **來自 WebSocket 伺服器的訊息大小**：當 [WebSocket](#option-4-add-a-remote-websocket-server) 伺服器傳送單一超過 16 MiB 的訊息時，Claude Code 會[關閉連線](#mid-session-drops-of-a-remote-server)，且該伺服器上進行中的呼叫會失敗。如果您負責維護該伺服器，請減少每則訊息傳回的資料量以維持在限制之內 Claude Code 已[移至背景任務](#automatic-backgrounding-of-long-tool-calls)的呼叫會透過任務通知回報其結果。對於在前景完成的呼叫，另有兩項限制適用： * **文字結果的字元限制**：對於未聲明 [`anthropic/maxResultSizeChars`](#raise-the-limit-for-a-specific-tool) 的工具，沒有影像內容的成功結果一旦超過 50,000 個字元，無論其 token 數為何，Claude Code 都會將其儲存到檔案。設定 `MAX_MCP_OUTPUT_TOKENS` 不會改變此閾值 * **錯誤結果**：當工具傳回標記為 `isError: true` 的結果時，Claude 會將該結果的文字作為工具的錯誤訊息接收。超過約 11,000 個字元的錯誤文字只會保留其前 5,000 個和後 5,000 個字元，中間會有一個標記說明移除了多少字元 若要變更 token 限制，請在啟動 Claude Code 之前於 shell 中設定 `MAX_MCP_OUTPUT_TOKENS`： ```bash theme={null} export MAX_MCP_OUTPUT_TOKENS=50000 claude ```

提高特定工具的限制

如果您正在建置 MCP 伺服器，可以透過在工具的 `tools/list` 回應項目中設定 `_meta["anthropic/maxResultSizeChars"]`，允許個別工具傳回超過預設持久化到磁碟閾值 50,000 個字元的結果。Claude Code 會將該工具的閾值提高到註解值，最高可達 500,000 個字元的硬性上限。 這對於傳回本質上很大但必要的輸出的工具很有用，例如資料庫 schema 或完整檔案樹。沒有註解的情況下，超過預設閾值的成功結果會被持久化到磁碟，並在對話中被檔案參考取代。 ```json theme={null} { "name": "get_schema", "description": "Returns the full database schema", "_meta": { "anthropic/maxResultSizeChars": 200000 } } ``` 該註解對文字內容獨立於 `MAX_MCP_OUTPUT_TOKENS` 應用，因此使用者不需要為聲明它的工具提高環境變數。傳回影像資料的工具仍受 token 限制。

工具結果中的影像

當 MCP 工具傳回 PNG、JPEG、GIF 或 WebP 影像時，Claude 會在對話中內嵌看到該影像。內嵌副本可能會縮小或壓縮以符合模型的影像大小限制。Claude Code 也會將原始位元組儲存到 [`~/.claude/projects/`](/docs/zh-TW/claude-directory#cleaned-up-automatically) 下的工作階段 `tool-results` 目錄中的檔案，並提供 Claude 路徑。Claude 隨後可以使用 Bash 等工具裁剪、轉換或重複使用完整解析度檔案。 如果您使用 [`--no-session-persistence`](/docs/zh-TW/cli-reference#cli-flags) 或 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/zh-TW/env-vars) 停用工作階段持久性，Claude Code 不會寫入影像檔案，Claude 只會收到內嵌副本。 將 MCP 影像結果儲存到檔案需要 Claude Code v2.1.283 或更新版本。

具有根層級組合器的工具輸入綱要

某些 MCP 伺服器將工具的輸入綱要宣告為 JSON Schema 聯合，在綱要的最上層使用 `anyOf`、`oneOf` 或 `allOf`。Claude API 不接受這些關鍵字在綱要根層級。它確實接受嵌套在 `properties` 內的組合器，Claude Code 會原封不動地傳送這些組合器。 具有根層級組合器的工具仍然可用。在將工具傳送到 API 之前，Claude Code 會將綱要平坦化為單一物件，並在工具的描述前面加上一句話，告訴 Claude 哪些參數群組屬於一起： * `allOf`：來自每個分支的屬性會被合併，每個分支的 `required` 清單仍然適用 * `anyOf` 和 `oneOf`：來自每個分支的屬性會被合併，每個分支的 `required` 清單會在工具描述中說明，而不是由綱要強制執行 您的伺服器會接收 Claude 選擇的任何引數，因此請繼續在伺服器端驗證組合。 當 Claude Code 無法產生 API 接受的綱要，或在未收到啟用重寫的遠端設定的部署上時，它會跳過該工具，在伺服器的日誌中記錄原因，並讓伺服器的其他工具保持可用。

具有無效輸入綱要的工具

Claude API 會檢查請求中每個工具的輸入綱要，當任何一個綱要失敗時，會拒絕整個請求並返回 400 錯誤。Claude Code 在載入伺服器的工具時會自行執行 API 的兩項檢查，並排除每個會失敗的工具，以便伺服器的其他工具繼續運作： * 頂層屬性名稱必須為 1 到 64 個字元長，且只能使用 ASCII 字母和數字、`_`、`.` 和 `-` * 綱要必須對 JSON Schema draft 2020-12 元綱要有效。Claude Code 會對未宣告 `$schema` 的綱要和宣告 draft 2020-12 的綱要套用此檢查。宣告任何其他方言的綱要會跳過此檢查，但上述屬性名稱檢查仍然適用 當 Claude Code 排除一個工具時，它會在伺服器的日誌中記錄原因，並告訴 Claude 它排除了哪些工具以及原因，以便您可以詢問 Claude 為什麼工具遺失。如果您修復伺服器上的綱要，下次 Claude Code 載入伺服器的工具時，該工具就會恢復。 Claude Code 透過從 Anthropic 取得的功能旗標來開啟排除功能。在[停用旗標取得的部署](/docs/zh-TW/env-vars#features-that-need-feature-flag-fetching)上，或在旗標從未到達的機器上（例如隔離的機器），Claude Code 仍會執行檢查並在伺服器的日誌中記錄哪個工具會被拒絕，但仍會將工具的綱要傳送給 API。API 會拒絕包含該綱要的請求，並[返回 400 錯誤，按位置命名工具](/docs/zh-TW/errors#tool-input-schema-is-invalid)。在 v2.1.216 之前，沒有部署執行這些檢查。 [根層級組合子處理](#tool-input-schemas-with-a-root-level-combinator)是獨立的，當旗標取得關閉或旗標從未到達時，會保持自己的行為。

名稱超過 128 個字元的工具

如果 `/mcp` 列出了 Claude 無法呼叫的工具，請檢查該工具的完整名稱是否超過 128 個字元。在工作階段中執行 `/mcp` 並選取該工具，即可查看其完整名稱，例如 `mcp____`。當 MCP 工具的完整名稱超過 128 個字元時，Claude Code 會將其排除在傳送給 Claude 的工具之外。Claude API 會拒絕包含此類工具的請求，因此排除該工具可讓伺服器的其他工具正常運作。 如需指出該工具名稱的訊息，以及縮短其完整名稱的方法，請參閱 [MCP 工具名稱超過 128 個字元](/docs/zh-TW/errors#mcp-tool-name-over-128-characters)。

要求特定工具的核准

如果您正在建立 MCP 伺服器，可以透過在工具的 `tools/list` 回應項目中將 `_meta["anthropic/requiresUserInteraction"]` 設定為 `true`，來標記工具在每次呼叫時都需要明確核准。該值必須是 JSON 布林值 `true`；任何其他值都會被忽略。 Claude Code 會在每次呼叫時顯示該工具的權限提示，即使在 `acceptEdits`、`auto` 和 `bypassPermissions` [權限模式](/docs/zh-TW/permissions#permission-modes)中也是如此，並且不會為其提供「不再詢問」選項。與該工具相符的[允許規則](/docs/zh-TW/permissions#permission-rule-syntax)也不會跳過提示。在 `dontAsk` 模式中（從不提示），Claude Code 會改為拒絕該呼叫。 提示必須到達一個人。在非互動模式下使用 [`--permission-prompt-tool`](/docs/zh-TW/cli-reference#cli-flags)，來自提示工具的 `allow` 結果對於標記的工具會被轉換為拒絕，並顯示訊息 `MCP tool requires user interaction; not supported via --permission-prompt-tool`。Agent SDK 的 [`canUseTool` 回呼](/docs/zh-TW/agent-sdk/permissions)確實會接收這些呼叫並可以核准它們，因為您的 SDK 應用程式應該會將它們顯示給使用者。 將此用於權限提示本身就是重點的工具，例如同意或存取授予步驟，其中自動核准意味著沒有人類曾經同意。來自同一伺服器的其他工具保持其正常的權限行為。 以下 `tools/list` 項目將一個工具標記為始終需要核准。 ```json theme={null} { "name": "grant_access", "description": "Requests access to a protected resource", "_meta": { "anthropic/requiresUserInteraction": true } } ``` 某些使用介面，例如 [Remote Control](/docs/zh-TW/remote-control) 和基於 [Agent SDK](/docs/zh-TW/agent-sdk/overview) 建立的應用程式，通常允許您透過一次點擊來核准工具呼叫。對於使用此註解標記的工具，Claude Code 會隱藏一次點擊動作並改為顯示工具的完整權限提示，因此核准仍然來自於回答提示的人，而不是點擊。 Claude Code 對於任何只有終端機對話框才能完整呈現的權限請求（例如包含安全警告或遠端使用介面無法顯示的始終允許選項的請求），也會以相同方式隱藏一次點擊核准。您在終端機對話框中回答該請求，而不是從 Remote Control 回答。需要 Claude Code v2.1.214 或更新版本。

回應 MCP 徵詢請求

MCP 伺服器可以在任務進行中使用徵詢功能向您請求結構化輸入。當伺服器需要無法自行取得的資訊時，Claude Code 會顯示互動式對話框，並將您的回應傳回給伺服器。您無需進行任何設定：當伺服器請求徵詢對話框時，它們會自動出現。 伺服器可以透過兩種方式請求輸入： * **表單模式**：Claude Code 顯示一個對話框，其中包含伺服器定義的表單欄位（例如，使用者名稱和密碼提示）。填入欄位並提交。 * **URL 模式**：Claude Code 詢問是否在您的瀏覽器中開啟連結。伺服器使用此模式進行在終端機外完成的流程，例如登入。 在 URL 模式中，Claude Code 會將 URL 作為命令列引數傳遞給您系統的 URL 處理程式，並限制該引數的長度。當 URL 經過命令列轉義後超過該限制時，您只能拒絕請求。每個需要轉義的字元，例如 `%` 或 `&`，都會計為上限的四倍：其本身的字元加上三個轉義字元。沒有這些字元的 URL 在約 8,000 個字元時達到上限。主要由百分比轉義組成的 URL，其中每三個字元中有一個是 `%`，在大約 4,000 個字元時達到上限。 若要自動回應徵詢請求而不顯示對話框，請使用 [`Elicitation` hook](/docs/zh-TW/hooks#elicitation)。 如果您正在建置使用徵詢功能的 MCP 伺服器，請參閱 [MCP 徵詢規格](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation)以了解協定詳細資訊和結構描述範例。 在使用 [protocol revision 2026-07-28](#mcp-client-runtimes) 的連線上，Claude Code 在其用戶端功能中宣告 `elicitation: {form: {}, url: {}}`，因此該處的伺服器可以透過協定的標準徵詢請求來請求任一模式。

使用 MCP 資源

MCP 伺服器可以公開資源，您可以使用 @ 提及來參考這些資源，類似於您參考檔案的方式。

參考 MCP 資源

在您的提示中輸入 `@` 以查看來自所有已連接 MCP 伺服器的可用資源。資源會與檔案一起出現在自動完成選單中。 使用格式 `@server:protocol://resource/path` 來參考資源： ```text wrap theme={null} Can you analyze @github:issue://123 and suggest a fix? ``` ```text wrap theme={null} Please review the API documentation at @docs:file://api/authentication ``` 您可以在單一提示中參考多個資源： ```text wrap theme={null} Compare @postgres:schema://users with @docs:file://database/user-model ``` 提示： * 資源在被參考時會自動擷取並作為附件包含 * 資源路徑在 @ 提及自動完成中可進行模糊搜尋 * Claude Code 會在伺服器支援時自動提供列出和讀取 MCP 資源的工具 * 資源可以包含 MCP 伺服器提供的任何類型的內容（文字、JSON、結構化資料等） MCP Apps UI 資源是具有 `ui://` URI 或 `text/html;profile=mcp-app` 媒體類型的項目：供主應用程式呈現的頁面，而不是供 Claude 讀取的內容。它們不會出現在 `@` 建議或資源列表工具的結果中，而且只提供 UI 資源的伺服器會顯示空的資源列表。按其 URI 讀取 UI 資源仍然有效。 工具搜尋透過延遲工具定義直到 Claude 需要時才載入，來保持 MCP 上下文使用量較低。只有工具名稱和伺服器指令在工作階段開始時載入，因此新增更多 MCP 伺服器對您的上下文視窗影響最小。Claude Code 不會對每個伺服器施加固定的工具上限；實際限制是您的上下文視窗預算。 工具搜尋在 Microsoft Foundry [部署於 Azure 的部署](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)上不受支援，該部署在伺服器端拒絕它：Claude Code 偵測到拒絕並改為對該部署預先載入 MCP 工具。[`ENABLE_TOOL_SEARCH`](#configure-tool-search) 無法覆寫此設定，因為拒絕來自部署本身。

針對 MCP 伺服器作者的工具搜尋

如果您正在建立 MCP 伺服器，啟用工具搜尋時伺服器指令欄位會變得更有用。伺服器指令幫助 Claude 瞭解何時搜尋您的工具，類似於 [skills](/docs/zh-TW/skills) 的運作方式。 新增清晰、描述性的伺服器指令，說明： * 您的工具處理的任務類別 * Claude 應何時搜尋您的工具 * 您的伺服器提供的關鍵功能 Claude Code 會截斷超過下列預設限制的工具描述或伺服器指令，Claude 只會看到截斷點之前的文字： * **伺服器指令，以及預先載入之工具的描述**：4,096 個字元 * **Claude 透過工具搜尋載入之工具的描述**：16,384 個字元 請保持描述和指令簡潔，並將關鍵詳細資訊放在開頭。當工具搜尋將 Claude 的查詢與工具描述比對時，只會讀取較短限制內的部分，因此也請將 Claude 會搜尋的字詞放在開頭附近。只要工具未被延遲，就會預先載入並適用較短的限制，例如當[工具搜尋關閉](#configure-tool-search)、工具[被標記為預先載入](#per-tool-alwaysload)，或其伺服器[豁免延遲](#exempt-a-server-from-deferral)時。 在 v2.1.296 之前，較短的限制為 2,048 個字元；在 v2.1.295 之前，該限制適用於每個工具描述，包括透過工具搜尋載入的描述。 Anthropic 在 `api.anthropic.com` 託管的部分 MCP 伺服器，其描述和指令會完整傳送給 Claude。若要變更工作階段中其他 MCP 伺服器的限制，請將 [`CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH`](/docs/zh-TW/env-vars#variables) 設定為字元數。您設定的數字會取代這兩個限制：例如 `8192` 會提高較短的限制並降低較長的限制。此變數需要 Claude Code v2.1.280 或更新版本。

標記工具為預先載入或保持延遲

若要控制伺服器中某個工具的載入方式，請在該工具的 `_meta` 物件中設定 `"anthropic/alwaysLoad"`。將您的伺服器新增到 Claude Code 的人也可以在其設定中為整個伺服器設定 [`alwaysLoad`](#exempt-a-server-from-deferral)，而其設定可以覆寫您的設定： | 您的工具的值 | 結果 | | :- | :- | | `true` | 該工具會預先載入。啟動不會因為此值而等待您的伺服器。設定您伺服器的人仍可以[延遲其所有工具](#defer-a-servers-tools) | | `false` | 當對方的設定指定 `"alwaysLoad": true` 時，該工具仍保持延遲。這適用於您的伺服器透過 [`--mcp-config`](/docs/zh-TW/cli-reference#cli-flags) 傳入、由 [Agent SDK 應用程式](/docs/zh-TW/agent-sdk/mcp#in-code)提供，或由[外掛](#plugin-provided-mcp-servers)提供的情況。在其他伺服器上，該工具會預先載入。需要 Claude Code v2.1.285 或更新版本 | 以下 `tools/list` 項目要求某個工具預先載入： ```json theme={null} { "name": "search_tickets", "description": "Searches the ticket tracker by keyword", "_meta": { "anthropic/alwaysLoad": true } } ``` 工具搜尋預設為啟用：MCP 工具被延遲並按需發現。當 `ANTHROPIC_BASE_URL` 指向非第一方主機時，Claude Code 會停用它，因為大多數代理伺服器不轉發 `tool_reference` 區塊。明確設定 `ENABLE_TOOL_SEARCH` 可覆寫該備援行為。 設定 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-TW/env-vars) 會保持工具搜尋關閉。您無法透過自己設定 `ENABLE_TOOL_SEARCH` 來覆寫它。在 Claude Code v2.1.227 或更新版本上，您的組織可以透過[受管設定](/docs/zh-TW/managed-settings)在此變數之下保持工具搜尋開啟。在[套用 HIPAA 設定](/docs/zh-TW/hipaa-setup#check-how-developers-sign-in-and-connect)的工作階段中，工具搜尋會關閉，且 `ENABLE_TOOL_SEARCH` 和受管設定都無法將其重新開啟。[停用預發行功能](/docs/zh-TW/llm-gateway-protocol#disable-pre-release-capabilities) 涵蓋覆寫適用的位置以及變數移除的內容。 Claude Code 在 Claude Opus 4、Claude Sonnet 4、Claude Haiku 4.5 及更新的模型上使用工具搜尋，在 Google Cloud 的 Agent Platform 上則為 Opus 4.5、Sonnet 4.5、Haiku 4.5 及更新的模型。在較早的模型上，Claude Code 會預先載入所有 MCP 工具，且 `ENABLE_TOOL_SEARCH=true` 不會覆寫此行為。 在 Google Cloud 的 Agent Platform 上，Claude Code 按模型世代決定： * **Claude Opus 4.5、Sonnet 4.5、Haiku 4.5 及更新版本**：工具搜尋預設為開啟，與 Anthropic API 上相同。 * **較早的 Agent Platform 模型**：Claude Code 預先載入所有 MCP 工具，因為它們的服務堆疊拒絕所需的測試版標頭。`ENABLE_TOOL_SEARCH=true` 不會覆寫此設定。 在 v2.1.221 之前，Claude Code 在 Google Cloud 的 Agent Platform 上對所有模型停用工具搜尋，除非您設定 `ENABLE_TOOL_SEARCH=true`。 使用 `ENABLE_TOOL_SEARCH` 環境變數控制工具搜尋行為： | 值 | 行為 | | :- | :- | | (未設定) | 所有 MCP 工具延遲並按需載入。在早於 Opus 4 和 Sonnet 4 的模型上、在早於 Opus 4.5、Sonnet 4.5 和 Haiku 4.5 的 Google Cloud Agent Platform 模型上、當 `ANTHROPIC_BASE_URL` 是非第一方主機時，或在部署於 Azure 的 Microsoft Foundry 部署上，改為預先載入 | | `true` | 當 `ANTHROPIC_BASE_URL` 是非第一方主機時，MCP 工具仍保持延遲。其他（未設定時的）備援情況仍然適用。Claude Code 會透過代理伺服器傳送測試版標頭，在不支援 `tool_reference` 區塊的代理伺服器上請求會失敗 | | `auto` | 閾值模式：Claude Code 預先載入它會延遲的工具，同時它們的定義總計少於上下文視窗的 10%，一旦定義達到 10% 就延遲所有工具 | | `auto:N` | 具有自訂百分比的閾值模式，其中 `N` 是 0-100。例如，`auto:5` 表示 5% | | `false` | 所有 MCP 工具預先載入，無延遲 | ```bash theme={null} # Use a custom 5% threshold ENABLE_TOOL_SEARCH=auto:5 claude # Disable tool search entirely ENABLE_TOOL_SEARCH=false claude ``` 或在您的 [settings.json `env` 欄位](/docs/zh-TW/settings-reference#env)中設定值。 您也可以特別停用 `ToolSearch` 工具： ```json theme={null} { "permissions": { "deny": ["ToolSearch"] } } ```

豁免伺服器不延遲

如果伺服器的工具應始終對 Claude 可見而無需搜尋步驟，請在該伺服器的設定中將 `alwaysLoad` 設定為 `true`。該伺服器的工具隨後會載入到上下文中，無論 `ENABLE_TOOL_SEARCH` 設定如何。對於 Claude 在每個回合都需要的少量工具使用此設定，因為每個預先載入的工具會消耗原本可用於您的對話的上下文。 以下 `.mcp.json` 項目豁免一個 HTTP 伺服器，同時保持其他伺服器延遲： ```json theme={null} { "mcpServers": { "core-tools": { "type": "http", "url": "https://mcp.example.com/mcp", "alwaysLoad": true } } } ``` `alwaysLoad` 欄位在所有伺服器類型上都可用。 設定 `alwaysLoad: true` 也會使啟動等待伺服器的工具，上限為標準 5 秒連線逾時，因為它們必須在建立第一個提示詞時存在。具有有效 [`cached` 項目](#server-status-detail)的遠端伺服器從快取提供其工具而無需連線，因此它不會延遲啟動。其他伺服器預設在背景連線；設定 [`MCP_CONNECTION_NONBLOCKING=0`](/docs/zh-TW/env-vars) 也使啟動等待它們。

延遲伺服器的工具

若要讓伺服器的所有工具都透過工具搜尋載入，請在 MCP 設定中該伺服器的項目裡設定 `"alwaysLoad": false`。這包括伺服器作者已[標記為預先載入](#per-tool-alwaysload)的工具。如果您省略 `alwaysLoad`，這些被標記的工具會預先載入。需要 Claude Code v2.1.287 或更新版本。

使用 MCP 提示作為命令

MCP 伺服器可以公開提示，這些提示在 Claude Code 中成為可用的命令。 來自名為 `anthropic-skills` 的伺服器的提示不會出現，因為 Claude Code [保留該名稱](/docs/zh-TW/skills#names-reserved-for-synced-skills)用於從 claude.ai 同步的技能。伺服器的工具仍然有效。在您的 MCP 設定中重新命名伺服器以列出其提示。

執行 MCP 提示

輸入 `/` 以查看您可用的命令，包括來自 MCP 伺服器的命令。Claude Code 將每個 MCP 提示列為 `/servername:promptname (MCP)`。輸入 `/mcp__servername__promptname` 也會執行它。 ```text wrap theme={null} /mcp__github__list_prs ``` 許多提示接受引數。在命令後以空格分隔的方式傳遞它們。Claude Code 在空白處分割引數，因此每個引數是單一令牌： ```text wrap theme={null} /mcp__github__pr_review 456 ``` ```text wrap theme={null} /mcp__jira__create_issue login-bug high ``` 提示： * MCP 提示從連接的伺服器動態探索 * 引數根據提示的定義參數進行解析 * 提示結果直接注入到對話中 * 在 `/mcp__servername__promptname` 形式中，Claude Code 將伺服器名稱中 `A-Z`、`a-z`、`0-9`、`_` 和 `-` 之外的任何字元替換為 `_`，並使用伺服器聲明的提示名稱

Managed MCP 設定

對於需要集中控制使用者可以連接哪些 MCP 伺服器的組織，請參閱 [Managed MCP 設定](/docs/zh-TW/managed-mcp)。它涵蓋使用 `managed-mcp.json` 部署固定伺服器集、使用 `managedMcpServers` 為每個使用者提供伺服器、使用 `allowedMcpServers` 和 `deniedMcpServers` 限制伺服器，以及當伺服器被阻止時使用者看到的內容。