透過 MCP 將 Claude Code 連接到工具

Claude Code 可以透過 Model Context Protocol (MCP) 連接到數百個外部工具和資料來源，這是一個開源標準，用於 AI 工具整合。MCP servers 讓 Claude Code 能夠存取您的工具、資料庫和 API。當您發現自己從另一個工具（例如問題追蹤器或監控儀表板）複製資料到聊天中時，請連接一個 server。連接後，Claude 可以直接讀取和操作該系統，而不是根據您貼上的內容進行工作。如果您是第一次連接 server，請從 MCP 快速入門開始，以取得逐步說明。本頁面是完整參考。

使用 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，將訊息推送到您的 session 中，因此當您不在時，Claude 可以回應 Telegram 訊息、Discord 聊天或 webhook 事件。

尋找並建立 MCP servers

在 Anthropic Directory 中瀏覽已審核的連接器。Directory 連接器使用與 Claude Code 相同的 MCP 基礎設施，因此您可以使用 claude mcp add 新增任何列在其中的遠端伺服器。

在連接伺服器之前，請驗證您信任每個伺服器。取得外部內容的伺服器可能會使您面臨提示注入風險。

若要建立您自己的伺服器，請參閱 MCP server 指南以了解協議基礎知識，以及 Claude 連接器建立文件以了解身份驗證、測試和 Directory 提交。您也可以使用官方的 mcp-server-dev plugin 讓 Claude 為您建立伺服器。

安裝外掛

在 VS Code 擴充功能或桌面應用程式中，請改為依照安裝外掛操作，而非執行此步驟。在終端機中，執行 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 "<name>" not found in marketplace "claude-plugins-official"：您本機的市集目錄副本可能已過時。請使用 /plugin marketplace update claude-plugins-official 重新整理，然後重試安裝。如果重試後顯示相同的訊息，請參閱 Plugin not found in marketplace。

如果安裝摘要報告 Run /reload-plugins to apply.，Claude Code 會為您執行該重新載入。如果重新載入警告您的下一則訊息會重新讀取對話，請執行 /reload-plugins --force。

執行建立 skill

/mcp-server-dev:build-mcp-server

Claude 會詢問您的使用案例，並建立遠端 HTTP 或本機 stdio 伺服器。

安裝 MCP 伺服器

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

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

HTTP 伺服器是連接到遠端 MCP 伺服器的建議選項。這是雲端服務最廣泛支援的傳輸方式。

# 基本語法
claude mcp add --transport http <name> <url>

# 實際範例：連接到 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 "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry。只有 SDK 主機應用程式（例如 Agent SDK 應用程式或桌面應用程式）可以註冊進程內 "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。在 --output-format stream-json 執行中，Claude Code 也會在 system/init 事件的 mcp_server_errors 欄位中報告跳過的 --mcp-config 項目，以便指令碼可以偵測伺服器從未載入。這需要 Claude Code v2.1.219 或更新版本。

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

SSE (Server-Sent Events) 傳輸已棄用。請改用 HTTP 伺服器（如果可用）。

某些服務仍然只公開 SSE 端點。使用與 HTTP 伺服器相同的 claude mcp add --transport http <name> <url> 命令新增這些。Claude Code 首先嘗試 HTTP 傳輸，當伺服器不接受時切換到 SSE。自動切換需要 Claude Code v2.1.265 或更新版本。在較早版本上，或直接透過 SSE 連接，請改為傳遞 --transport sse：

# 基本語法
claude mcp add --transport sse <name> <url>

# 實際範例：連接到 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 設定授予的每個額外工作目錄來回答 roots/list。當該集合變更時，Claude Code 會傳送 notifications/roots/list_changed。此變數設定在伺服器的環境中，而不是在 Claude Code 自身的環境中，因此在專案範圍的 .mcp.json 項目或 ~/.claude.json 中的本機或使用者範圍伺服器項目的 command 或 args 中透過 ${VAR} 擴展參考它需要預設值，例如 ${CLAUDE_PROJECT_DIR:-.}。外掛提供的 MCP 設定直接替換 ${CLAUDE_PROJECT_DIR}，不需要預設值。

# 基本語法
claude mcp add [options] <name> -- <command> [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 伺服器：

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 產生 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 伺服器中四個選項之一接受的輸入。在下面找到您擁有的形狀，將其轉換為 Claude Code 接受的命令。除非您新增 --scope project 或 --scope user，否則每個命令都會寫入本機範圍。

從 URL 新增伺服器

URL 表示伺服器是遠端的。對於 https:// 端點，使用 --transport http 新增它，或在指示說端點使用 SSE 時遵循選項 2。對於 wss:// 端點，改為使用選項 4，因為 --transport 不接受 ws：

claude mcp add --transport http example https://mcp.example.com/mcp

如果指示也提供 API 金鑰或 token 標頭，請使用 --header 傳遞它，如選項 1所示。

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

啟動命令表示伺服器作為本機 stdio 程序執行。將整個命令放在 -- 之後，以便 Claude Code 將旗標（例如 -y）傳遞給啟動伺服器的命令，而不是將其讀取為自身的選項。使用 --env 傳遞指示要求的任何環境變數，在伺服器名稱之後和 -- 之前：

claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

選項 3完整涵蓋 -- 分隔符。

從 `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 項目會失敗。
金鑰包含字母、數字、連字號和底線以外的字元：選擇僅使用這些字元的伺服器名稱。否則金鑰是伺服器名稱。

例如，此區塊：

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

變成此命令：

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

從 JSON 設定新增 MCP 伺服器涵蓋 add-json 的 shell 逃逸和 --scope 旗標。若要與您的團隊共享伺服器，請改為新增 --scope project，或在您的專案根目錄的 .mcp.json 下的 mcpServers 下新增項目並提交它。專案範圍涵蓋 Claude Code 如何載入和核准該檔案。每個 claude mcp add 和 claude mcp add-json 命令在成功時列印 Added ... 行。若要檢查 Claude Code 是否已連接，請執行 claude mcp get <name>；伺服器狀態涵蓋它顯示的狀態和 .mcp.json 伺服器的核准步驟。

管理您的伺服器

設定後，您可以使用這些命令管理您的 MCP 伺服器：

# 列出所有已設定的伺服器
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 伺服器未儲存或移除；對於 may not have been saved 訊息，請參閱 MCP 伺服器可能未儲存或移除。 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 <name> 中都顯示它。執行 claude 互動式地檢查並核准它。
✘ Rejected (see disabledMcpjsonServers in settings)：由 disabledMcpjsonServers 項目拒絕的 .mcp.json 伺服器。Claude Code 只在 claude mcp get <name> 中顯示它。
⊘ Disabled for this project (re-enable via /mcp)：專案的 disabledMcpServers 列表命名的伺服器。Claude Code 在 claude mcp list 和 claude mcp get <name> 中都顯示它。從 /mcp 面板重新開啟伺服器。

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

claude mcp list 和 claude mcp get 只從未簽入儲存庫的設定檔讀取 .mcp.json 核准，直到您透過在工作區中執行 claude 並接受工作區信任對話來信任工作區。複製的儲存庫無法核准自身的伺服器：提交到專案的 .claude/settings.json 的 enableAllProjectMcpServers 或 enabledMcpjsonServers 在不受信任的資料夾中被忽略，伺服器保持在 ⏸ Pending approval 而不是被連接和健康檢查。這些來源的核准在不受信任的資料夾中仍然適用：

您的使用者 ~/.claude/settings.json
受管設定
使用 --settings 傳遞的設定

Claude Code 也應用來自未追蹤 .claude/settings.local.json 的核准，但它執行 git 來檢查檔案是否被追蹤，並且只在受信任的資料夾中執行該檢查。在您從未信任的資料夾中，Claude Code 會等待信任對話，然後才應用檔案的核准，除非資料夾是您自己的設定主目錄：您的家目錄，或其 .claude 您已設定為 CLAUDE_CONFIG_DIR 的目錄。在 v2.1.207 之前，Claude Code 即使在您從未信任的資料夾中也應用來自未追蹤 .claude/settings.local.json 的核准。任何設定檔中的 disabledMcpjsonServers 項目仍然拒絕伺服器。

伺服器狀態詳細資訊

在 /mcp 中（包括伺服器的選單）和 /plugin 管理員中，您之前使用過的遠端 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 以開啟它，或設定 0 以在推出啟用它時保持關閉。在 v2.1.238 之前，快取預設開啟。當您從 /mcp 中的伺服器選單選擇 Disable 或 Clear authentication 時，Claude Code 也會捨棄該伺服器的快取項目。Reconnect 在已連接或失敗的伺服器上也會捨棄它；在 cached 伺服器上，Reconnect 現在連接伺服器並保留項目。Claude Code 在捨棄項目後下次連接到伺服器時，它會從伺服器而不是從快取中擷取工具列表。當伺服器的狀態為 ✘ 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 之前，兩個命令都只顯示裸露的失敗狀態，沒有狀態代碼或伺服器的錯誤文字。當您從 /mcp 完成身分驗證且連接仍然因 HTTP 狀態或傳輸錯誤代碼而失敗時，Claude Code 會在嘗試後列印的訊息中新增該代碼和伺服器 URL 的來源。來源是方案和主機，加上 URL 命名的連接埠（例如 https://mcp.example.com）。

路徑和查詢永遠不會出現在該訊息中。
對於本機、專案或使用者範圍中的伺服器或受管 MCP 設定，來源顯示該設定中寫入的主機，因此主機中的 ${VAR} 參考在訊息中不會展開。
對於沒有狀態或錯誤代碼的失敗，Claude Code 顯示錯誤文字而不顯示來源。

設定為空 url 的遠端伺服器在 /mcp、claude mcp list 和 /plugin 管理員中顯示為 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 不會修剪空白並完全按照寫入的方式使用值，因此編輯設定以移除它。
在多個範圍中使用相同名稱：如果您在多個範圍中定義相同的伺服器名稱，但端點不同，Claude Code 會在 claude mcp list 輸出和 /mcp 中警告衝突。Claude Code 按端點儲存 OAuth 登入，因此當您驗證在一個專案中載入的定義時，您仍然需要在不同定義載入的專案中單獨登入。保留您想要的端點並使用 claude mcp remove <name> --scope <scope> 移除其他端點。在警告中，Claude Code 引用每個範圍的端點，如您的設定中所寫，帶有 ${VAR} 參考未展開，因此它永遠不會顯示已解析的值，例如 API 金鑰。
保留名稱：Claude Code 保留其內建伺服器的名稱，包括 workspace、claude-in-chrome、computer-use、Claude Preview 和 Claude Browser。如果您的設定定義具有保留名稱的伺服器，Claude Code 會在載入時跳過它並顯示警告，要求您重新命名它。claude mcp add 拒絕帶有錯誤的保留名稱。Claude Preview 和 Claude Browser 都命名 Claude Code 桌面應用程式的預覽窗格使用的內建伺服器。
遺漏環境變數：如果伺服器設定中的 ${VAR} 參考命名未設定且沒有 :-default 的變數，Claude Code 會在 claude mcp list 輸出和 /mcp 中警告，命名變數，並仍然載入伺服器，${VAR} 文字未展開。設定變數或新增 ${VAR:-default} 備援。在遠端伺服器的 url 和 headers 中，某些憑證變數讀取為空，沒有警告。

工具可用性

/mcp 面板在每個已連接伺服器旁邊顯示工具計數，並標記宣傳工具功能但不公開工具的伺服器。如果您的請求需要仍在背景連接的伺服器中的工具，Claude 會在繼續之前等待該伺服器。等待的方式取決於您的設定：

使用工具搜尋（預設）：等待發生在 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 上：Claude 開始於工具搜尋路徑而不是 WaitForMcpServers，因為 Claude Code 只從 API 發現部署的伺服器端拒絕。Claude Code 將該部署切換到前期載入後，來自完成連接的伺服器的工具在 Claude 的下一個請求上變得可用。

啟用工具搜尋後，當伺服器在 Claude 工作時完成連接時，Claude Code 在同一回合中的下一個請求上將伺服器的工具名稱列出給 Claude。Claude 然後可以搜尋並呼叫這些工具，而無需等待您的下一條訊息。恢復工作階段後，Claude 可以在工具的 MCP 伺服器仍在連接時呼叫已儲存對話中的工具。當伺服器正在進行首次連接嘗試時，Claude Code 會保留該呼叫最多 10 秒，並在工具可用後執行它。如果伺服器未及時連接，或它已在失敗嘗試後重試，該呼叫會以 No such tool available 工具錯誤失敗。

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

在 /mcp 面板中切換伺服器關閉，以停止 Claude Code 連接到它，而不會失去其設定。Claude Code 仍然在 /mcp 中列出伺服器，標記為已停用。當您切換伺服器時，Claude Code 在 ~/.claude.json 中按專案記錄您的選擇，在兩個涵蓋不相交伺服器集合的列表之一中：

disabledMcpServers：使用者設定伺服器、外掛伺服器、您的組織透過受管設定提供的伺服器、Claude Code 自身擷取的 claude.ai 連接器以及預設開啟的內建伺服器的選擇退出列表。Claude Code 不連接您在此列出的伺服器。當您使用停用 claude.ai 連接器中描述的按專案 /mcp 切換停用 claude.ai 連接器時，Claude Code 在此列表下使用其顯示名稱寫入它，例如 claude.ai Slack。
enabledMcpServers：預設關閉的內建伺服器（例如 computer-use）的選擇加入列表。Claude Code 只在您在此列出時連接預設關閉的伺服器。

Claude Code 為每個伺服器查詢恰好兩個列表之一，因此兩個列表都不會覆寫另一個。如果您將常規伺服器新增到 enabledMcpServers，或將預設關閉的內建伺服器新增到 disabledMcpServers，Claude Code 會忽略該項目。 disabledMcpServers 和 enabledMcpServers 與 enabledMcpjsonServers 和 disabledMcpjsonServers 無關，它們控制專案的 .mcp.json 檔案中定義的伺服器的核准。

MCP 用戶端執行時

Claude Code 透過兩個用戶端執行時之一連接到 MCP 伺服器。v1 執行時建立在 MCP TypeScript SDK 1.x 上。v2 執行時是 MCP TypeScript SDK 2.0 上的相同程式碼，它新增 MCP 協議修訂 2026-07-28。此頁面的其餘部分適用於兩個執行時，除非某個部分命名 v2 執行時。 Claude Code 每次啟動時選擇執行時，並保持到您退出。在擷取功能旗標的工作階段中，它在 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
透過 Claude 應用程式閘道登入的工作階段
您關閉遙測或功能旗標擷取的工作階段，例如使用 DISABLE_TELEMETRY

在 v2 上，Claude Code 也：

詢問 HTTP、stdio 和 claude.ai 連接器伺服器是否支援較新的修訂，並與支援的伺服器一起使用它。它連接到每個其他伺服器，如 v1 所做的那樣。
在它保持開啟的流上從較新修訂上的伺服器接收 list_changed 通知。
不註冊在較新修訂上連接的頻道伺服器，因為該修訂無法攜帶頻道訊息。
失敗 MCP OAuth 登入，其授權回應命名意外發行者。
僅將 MCP OAuth 憑證傳送到透過 HTTPS 或在 localhost、127.0.0.1 或 ::1 上提供的 token 端點。對於 token 端點為其他地方（例如本機網路上的裝置）的純 http:// 的伺服器，登入失敗。請參閱拒絕將憑證傳送到非 https token 端點。

Anthropic 可以使用 Claude Code 擷取的功能旗標將特定伺服器保持在較早的協議上，或關閉該流。若要自行選擇執行時，請設定 MCP_SDK_GENERATION 為 v1 或 v2。若要決定 Claude Code 是否詢問，請設定 MCP_PROTOCOL_NEGOTIATION 為 auto 或 legacy。

動態工具更新

MCP 伺服器可以在連接期間變更其提供的工具、提示詞或資源，並傳送 list_changed 通知。當收到通知時：

在互動式終端機工作階段中，Claude Code 會從該伺服器擷取更新後的列表，因此您無需重新連接它。
在使用 -p 旗標的非互動模式中以及在 Agent SDK 中，Claude Code 在收到這些通知時只重新整理工具列表。

如果重新整理請求失敗，Claude Code 會保留伺服器之前發現的工具、提示詞和資源，直到稍後的重新整理成功。在 v2.1.214 之前，重新整理期間的暫時性錯誤會將伺服器的工具、提示詞和資源替換為空列表。

v2 執行時上的通知流

在 v2 執行時上，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 "<name>" disconnected · open /mcp to reconnect 通知。您可以從 /mcp 手動重試。
在 claude -p 執行和 Agent SDK 工作階段中：Claude Code 進行相同的五次嘗試，沒有 /mcp 面板顯示這些嘗試。當 HTTP 或 SSE 伺服器的嘗試因暫時性錯誤而失敗時，它會在背景中持續重試最多約半小時，當某次重試連接成功時，伺服器及其工具會再次可用。

失敗的首次連接

當 HTTP 或 SSE 伺服器的首次連接因暫時性錯誤（例如 5xx 回應、連接被拒絕或逾時）失敗時，Claude Code 最多重試三次。如果連接仍然失敗，Claude Code 將伺服器標記為失敗。 Claude Code 在這些情況下不重試：

WebSocket 伺服器的首次連接
身分驗證或找不到錯誤，因為它需要設定變更才能解決。當 headersHelper 是伺服器唯一的 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 關於失敗連接的已設定伺服器取決於工具搜尋（預設開啟）：

使用工具搜尋，Claude Code 告訴 Claude 哪個伺服器失敗及其連接錯誤，因此 Claude 在其回應中報告連接失敗。Claude Code 在找不到符合工具的 ToolSearch 結果中包含相同的資訊。
在任何沒有工具搜尋的設定中，Claude Code 不向 Claude 報告失敗的伺服器連接。

使用頻道推送訊息

MCP 伺服器也可以直接將訊息推送到您的工作階段，以便 Claude 可以對外部事件（如 CI 結果、監控警報或聊天訊息）做出反應。若要啟用此功能，您的伺服器宣告 claude/channel 功能，您在啟動時使用 --channels 旗標選擇加入。請參閱頻道以使用官方支援的頻道，或頻道參考以建立您自己的。在 v2 執行時上，協商 MCP 協議修訂 2026-07-28 的頻道伺服器無法傳遞頻道訊息，因此 Claude Code 不會將其註冊為頻道。不支援該修訂的頻道伺服器會在較早的握手上連接，並如以往一樣註冊。 Claude Code 預設會向 stdio 伺服器詢問該修訂。若要將 stdio 頻道伺服器保持在較早的握手上，請設定 MCP_PROTOCOL_NEGOTIATION 為 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 對需要 OAuth 2.0 身分驗證的遠端伺服器進行驗證

按伺服器 timeout 是每個工具呼叫的硬牆鐘限制，來自伺服器的進度通知不會延長它。低於 1000 的值被忽略並落回 MCP_TOOL_TIMEOUT，或在該變數未設定時落回其約 28 小時的預設值。對於 HTTP、SSE 或 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 連接器伺服器的五分鐘，以及 stdio 伺服器的 30 分鐘。以毫秒為單位設定 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT 環境變數以變更空閒視窗，或設定為 0 以停用檢查。這些逾時限制呼叫可以執行多長時間，不總是它阻止工作階段多長時間：執行超過兩分鐘的主對話呼叫首先移動到背景任務。請參閱長工具呼叫的自動背景化。

長工具呼叫的自動背景化

主對話中仍在執行兩分鐘後的 MCP 工具呼叫移動到背景任務，而不是阻止工作階段。Claude 立即接收任務 ID 並繼續工作，結果在呼叫解決時作為任務通知到達。自動背景化需要 Claude Code v2.1.212 或更新版本。任務出現在 /tasks中，您也可以在其中停止它，它不會在退出工作階段時存活。任務的項目顯示伺服器報告的最新進度。如果您停止任務，Claude Code 會取消該呼叫並告知 Claude 不會有結果。停止並不保證伺服器會停止：它可能已經完成部分工作，或仍可能完成它。按呼叫限制仍然適用於呼叫在背景中執行時：由按伺服器 timeout 或 MCP_TOOL_TIMEOUT設定的牆鐘限制，以及由 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT設定的空閒逾時。以毫秒為單位設定 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 環境變數以變更閾值，或設定為 0 以關閉自動背景化。設定 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 為 1 也會關閉它，以及所有其他背景任務功能。某些呼叫永遠不會移動到背景：

來自 subagent 的呼叫；Claude Code 只背景化主對話呼叫
對 IDE 伺服器的呼叫
在非互動模式中的呼叫，除非 CLAUDE_AUTO_BACKGROUND_TASKS 設定為 1，因為一次性執行可能在結果到達之前結束

等待開啟引出對話的呼叫在對話開啟時不會背景化；伺服器被阻止在您的輸入上，而不是緩慢，因此 Claude Code 將移動延遲到對話關閉。

外掛提供的 MCP 伺服器

外掛可以捆綁 MCP 伺服器，在您啟用外掛時提供工具和整合。 外掛 MCP 伺服器如何工作：

外掛在外掛根目錄的 .mcp.json 中或內聯在 plugin.json 中定義 MCP 伺服器
當您啟用外掛時，Claude Code 自動啟動其 MCP 伺服器
Claude Code 將外掛 MCP 工具與手動設定的 MCP 工具一起提供
您透過安裝或解除安裝外掛新增和移除外掛伺服器，而不是使用 /mcp 命令。您仍然可以在 /mcp 中切換已安裝的外掛伺服器關閉，這會停止 Claude Code 連接到它，而不會移除外掛

範例外掛 MCP 設定：在外掛根目錄的 .mcp.json 中：

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

或內聯在 plugin.json 中：

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

外掛 MCP 功能：

自動生命週期：伺服器在這些點連接和斷開連接：
- 在工作階段啟動時，Claude Code 自動連接已啟用外掛的伺服器。在 /mcp 中，您之前使用過的遠端（HTTP 或 SSE）外掛伺服器可以改為顯示 cached 狀態；Claude Code 在 Claude 首次呼叫其工具之一時連接它
- 如果您在工作階段期間啟用或停用外掛，Claude Code 在變更適用時連接或斷開其 MCP 伺服器。在不重新啟動的情況下應用外掛變更描述何時發生。在沒有互動式終端機的工作階段中，/reload-plugins 不連接或斷開外掛 MCP 伺服器；這些變更在您的下一個工作階段中生效
- 當您重新載入時，Claude Code 保留設定未變更的外掛伺服器的即時連接，並在您從 Agent SDK 替換工作階段的 MCP 伺服器列表而不命名它們時執行相同操作
- 當您在 v2.1.246 或更新版本上使用 /cd 移動工作階段時，Claude Code 連接新目錄的設定啟用的外掛的伺服器，並斷開不再啟用的外掛的伺服器，因此您不需要在移動後執行 /reload-plugins
- 在雲端工作階段中，對尚未連接的外掛伺服器的 MCP 呼叫（例如空閒工作階段喚醒後）按需啟動伺服器並等待它連接
路徑佔位符：${CLAUDE_PLUGIN_ROOT} 解析為外掛的安裝目錄，${CLAUDE_PLUGIN_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_<plugin-name>_<server-name>__<tool-name>，其中 A-Z、a-z、0-9、_ 和 - 以外的任何字元都被替換為 _。對於名為 my-plugin 的外掛中捆綁的 database-tools 伺服器，query 工具可呼叫為：

mcp__plugin_my-plugin_database-tools__query

在權限規則、skill 的 allowed-tools 列表、subagent 的 tools 欄位或 hook matcher 中參考工具時使用此完整名稱。針對裸伺服器金鑰編寫的 hook matcher（例如 mcp__database-tools__.*）永遠不會針對外掛捆綁的伺服器觸發。伺服器本身在範圍名稱 plugin:<plugin-name>:<server-name> 下註冊，例如 plugin:my-plugin:database-tools。在預期已設定伺服器名稱的地方使用該名稱，例如 mcp_tool hook 的 server 欄位。請參閱外掛元件參考以取得有關使用外掛捆綁 MCP 伺服器的詳細資訊。

MCP 安裝範圍

MCP servers 可以在三個不同的範圍級別進行配置。您選擇的範圍控制 server 在哪些專案中載入，以及配置是否與您的團隊共享。管理員也可以透過受管配置為每個使用者部署或提供 servers。

範圍	載入位置	與團隊共享	儲存位置
Local	僅目前專案	否	`~/.claude.json`
Project	僅目前專案	是，透過版本控制	專案根目錄中的 `.mcp.json`
User	您的所有專案	否	`~/.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 了解設定檔案位置的詳細資訊。

# 新增本機範圍的 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 中您目前專案的項目。下面的範例顯示結果：

{
  "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 工具和服務。

# 新增 project scope 的 server
claude mcp add --transport http shared-server --scope project https://example.com/mcp

產生的 .mcp.json 檔案遵循標準化格式：

{
  "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 工作階段和雲端工作階段中，Claude Code 無法顯示該提示：它會載入 project scope servers 而不詢問。Claude Code 也會在您以 bypassPermissions 模式啟動的工作階段中跳過提示，其中在您的使用者設定或受管設定中設定了 skipDangerousModePermissionPrompt。若要無論如何保持 server 不被使用：

將其新增到 disabledMcpjsonServers，這會在每個權限模式中阻止它。
使用 --setting-sources 或 SDK 的 settingSources 選項完全排除專案設定。
使用 --strict-mcp-config 啟動工作階段。Claude Code 隨後只使用您透過 --mcp-config 傳遞的 MCP servers。跳過 Claude Code 未載入的 project scope servers 的批准提示需要 Claude Code v2.1.246 或更新版本；在 v2.1.246 之前，嚴格工作階段仍會等待它們的批准，這會導致背景工作階段在啟動時等待。請參閱使用 managed-mcp.json 進行獨佔控制了解該旗標在受管 MCP 檔案下的作用。

Project server 批准和工作區信任涵蓋提交到儲存庫的批准如何與工作區信任互動。

User scope

User scope 的 servers 儲存在 ~/.claude.json 中，並提供跨專案可存取性，使其在您機器上的所有專案中可用，同時對您的使用者帳戶保持私密。此範圍非常適合個人公用程式 servers、開發工具或您在不同專案中經常使用的服務。

# 新增使用者 server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Scope 階層和優先順序

當相同的 server 在多個位置定義時，Claude Code 連接到它一次，使用來自最高優先順序來源的定義。整個 server 項目來自該來源；欄位不會跨範圍合併。

Local scope
Project scope
User scope
Plugin-provided servers
claude.ai connectors

Claude Code 按名稱符合三個範圍中的重複項。它按端點符合 plugins 和 connectors，因此指向與上述 server 相同 URL 或命令的端點被視為重複項。當兩個 URL 拼寫僅在配置或主機的字母大小寫、配置的預設連接埠 (例如 https 上的 :443) 或尾部斜線上有所不同時，它們被視為相同的端點。不同的路徑、查詢字串、使用者資訊或非預設連接埠會使兩個 servers 不同。您的組織透過 managedMcpServers 受管設定提供的 server 排名高於所有這些，因此當其中一個重複它時，Claude Code 連接組織的定義。需要 Claude Code v2.1.259 或更新版本。如果您在桌面應用程式的 Code 標籤中開啟本機工作階段，其中 ~/.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 驗證

使用變數擴展的範例

{
  "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 中，某些認證變數讀取為空，沒有警告。

讀取為空的認證變數

在遠端 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 輸出中的顯示方式

對於本機、專案或使用者範圍中的 server，以下表面按名稱而不是其解析值顯示 ${VAR} 參考：

server 的 /mcp 詳細檢視中的 URL 或命令行
claude mcp list 和 claude mcp get 輸出

/mcp 詳細檢視在 Claude Code v2.1.268 或更新版本中以這種方式顯示參考。對於您的組織透過 managedMcpServers 設定提供的 server，這些表面顯示僅 URL 的主機。若要檢查當連接失敗時 claude mcp list、claude mcp get 和 /mcp 顯示的內容，請參閱 Server 狀態詳細資訊。

實用範例

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

GitHub 的遠端 MCP server 使用作為標頭傳遞的 GitHub 個人存取 token 進行驗證。若要取得一個，請開啟您的 GitHub token 設定，產生一個新的細粒度 token，具有對您希望 Claude 使用的儲存庫的存取權，然後新增 server：

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 並檢查該伺服器的列是否顯示核取記號。具有錯誤憑證的伺服器則會顯示 ✘，其失敗詳細資訊包括伺服器傳回的 HTTP 狀態，例如 401。然後使用 GitHub：

審查 PR #456 並建議改進

為我們剛發現的錯誤建立新問題

顯示所有指派給我的開放 PRs

範例：查詢您的 PostgreSQL 資料庫

DBHub，@bytebase/dbhub 套件，是一個 MCP server，可將 Claude 連接到您在 --dsn 中傳遞的連接字串的關聯式資料庫。在連接字串中使用唯讀資料庫使用者，以便 Claude 執行的查詢無法修改資料：

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

若要確認伺服器已啟動，請執行 /mcp 並檢查 db 列是否顯示核取記號。然後自然地查詢您的資料庫：

本月我們的總收入是多少？

顯示 orders 表的 schema

找到 90 天內未進行購買的客戶

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

許多雲端 MCP 伺服器需要身分驗證。Claude Code 支援 OAuth 2.0 以進行安全連線。當伺服器回應 401 Unauthorized 或 403 Forbidden 時，Claude Code 會將遠端伺服器標記為需要身分驗證。Claude Code 顯示的內容取決於伺服器：

對於您尚未登入的伺服器，任一狀態碼都會在 /mcp 中標記它，以便您完成 OAuth 流程。
對於 claude.ai 連接器，由 claude.ai 拒絕您的工作階段 token 導致的 401 不會標記連接器，因為重新授權連接器無法修復您的登入。Claude Code 改為顯示工作階段 token 被拒絕狀態。
對於您在 headers 中或透過 headersHelper 設定 Authorization 標頭的伺服器，連線時的 401 或 403 不會標記伺服器，因為要修復的憑證是您設定的憑證。Claude Code 改為報告連線失敗。如果您從 ${VAR} 參考設定該標頭，請檢查該變數是否是 Claude Code 讀取為空的變數之一。
對於傳遞到雲端工作階段的連接器，Claude Code 不會執行登入流程，因為工作階段的代理伺服器使用您在 claude.ai 中授予的授權向連接器進行身分驗證。當那裡的連接器需要再次授權時，請在 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 連接器，您只能從 claude.ai 設定進行連接。該通知會宣佈每個伺服器一次，並在後續啟動時將其排除在計數之外，直到該伺服器已連接並再次需要登入。/mcp 仍會列出每個需要登入的伺服器。 claude -p 或 Agent SDK 執行沒有 /mcp 面板，因此 Claude Code 無法在其中執行 OAuth 流程。若要使用需要身分驗證的伺服器，請先從互動式工作階段完成登入：在工作階段中執行 /mcp，或在您的 shell 中執行 claude mcp login <name>。當已設定的伺服器在啟用工具搜尋的 claude -p 或 Agent SDK 執行期間需要身分驗證時，Claude Code 會告訴 Claude 該伺服器的工具在您授權之前無法使用。如果您為伺服器設定了 headers.Authorization 且伺服器拒絕該標頭，Claude Code 會報告連線失敗，而不是回退到 OAuth。檢查 token 對 MCP 端點是否有效，或移除標頭以使用 OAuth 流程。

新增需要身分驗證的伺服器

如果您已在 MCP 快速入門中新增了 sentry 伺服器，請跳過此步驟：在相同範圍使用相同伺服器名稱再次執行 claude mcp add 會失敗，並顯示 MCP server sentry already exists in local config。否則，執行：

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

在 Claude Code 中使用 /mcp 命令

在 Claude Code 中，使用命令：

/mcp

然後按照瀏覽器中的步驟登入。

提示：

身分驗證 token 會安全地儲存並自動重新整理
使用 /mcp 功能表中的「Clear authentication」撤銷存取權
如果瀏覽器未自動開啟，請複製提供的 URL 並手動開啟
如果瀏覽器重新導向在驗證後因連線錯誤而失敗，請將瀏覽器位址列中的完整回呼 URL 貼到 Claude Code 中出現的 URL 提示中
OAuth 身分驗證適用於 HTTP 伺服器

從命令列進行身分驗證

claude mcp login <name> 命令直接從您的 shell 執行已設定伺服器的 OAuth 流程，因此您不需要在工作階段內開啟 /mcp 面板。對於 claude.ai 連接器，請按照從您的 shell 再次授權連接器操作。

claude mcp login sentry

若要稍後清除儲存的憑證，請執行 claude mcp logout <name>。 claude mcp login 會偵測何時沒有本機瀏覽器可用（例如在 SSH 工作階段期間或在沒有顯示伺服器的 Linux 上），並列印授權 URL，而不是嘗試開啟瀏覽器。在您的本機機器上開啟 URL，然後將瀏覽器位址列中的完整重新導向 URL 貼回提示。該命令需要互動式終端機進行貼上步驟，因此請使用 ssh -t 連接。傳遞 --no-browser 以強制 URL 提示，即使偵測到本機瀏覽器。

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 憑證下的版本說明。您可以單獨使用 --callback-port（使用動態用戶端註冊）或與 --client-id 一起使用（使用預先設定的憑證）。

# 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 應用程式，然後在新增伺服器時提供憑證。

使用伺服器註冊 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 中的連接埠。

claude mcp add
claude mcp add-json
claude mcp add-json (僅回呼連接埠)
CI / 環境變數

使用 --client-id 傳遞您應用程式的用戶端 ID。--client-secret 旗標會以遮罩輸入提示輸入密碼：

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 作為單獨的旗標傳遞：

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：

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

透過環境變數設定密碼以跳過互動式提示：

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 中進行身分驗證

在 Claude Code 中執行 /mcp 並按照瀏覽器登入流程。

提示：

用戶端密碼安全地儲存在您的系統鑰匙圈 (macOS) 或憑證檔案中，而不是在您的設定中
您只能在新增伺服器時設定用戶端密碼。當您使用 claude mcp login 或從 /mcp 進行身分驗證時，Claude Code 會使用儲存的密碼，不會提示輸入密碼或讀取 MCP_CLIENT_SECRET
若要稍後新增或變更密碼，請使用 claude mcp remove <name> 移除伺服器，然後使用 --client-secret 和相同的 --scope 再次新增它
如果伺服器使用沒有密碼的公開 OAuth 用戶端，請僅使用 --client-id 而不使用 --client-secret
這些旗標僅適用於 HTTP 和 SSE 傳輸。它們對 stdio 伺服器沒有影響
使用 claude mcp get <name> 驗證為伺服器設定了 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：

{
  "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 參數格式。

{
  "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 訊息，該訊息指出伺服器請求的範圍。伺服器在 /mcp 中顯示為需要身分驗證。如果該範圍不在您的固定 oauth.scopes 中，請新增它，然後執行 /mcp 並再次驗證伺服器。Claude Code 請求固定範圍而不是伺服器指出的範圍，因此如果您在不新增它的情況下再次驗證，您獲得的 token 仍然缺少它。

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

如果您的 MCP 伺服器使用 OAuth 以外的身分驗證方案，例如 Kerberos、短期 token 或內部 SSO，請使用 headersHelper 在連線時產生請求標頭。Claude Code 執行命令並將其輸出合併到連線標頭中。

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

該命令也可以是內聯的：

{
  "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 根據您設定伺服器的位置選擇命令的工作目錄，因此請將指令碼作為絕對路徑提供或將其放在 PATH 上
動態標頭會覆寫任何具有相同名稱的靜態 headers

一旦專案和本機範圍伺服器的信任規則允許 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`	外掛程式的根目錄。僅當外掛程式提供伺服器時設定

使用這些來編寫為多個 MCP 伺服器服務的單個 helper 指令碼。外掛程式提供的 headersHelper 無法參考外掛程式的 ${user_config.*} 值，因為命令透過 shell 執行。Claude Code 報告伺服器設定錯誤，並顯示錯誤，不會替換該值。改為將 ${user_config.KEY} 放在伺服器的 headers 欄位中，該欄位不會進行 shell 解析，或讓 helper 指令碼從設定檔讀取該值。在 v2.1.207 之前，headersHelper 會替換 ${user_config.*} 值。

Helper 執行的位置

Claude Code 從宣告伺服器的設定中選擇 headersHelper 命令的工作目錄。Claude 在 Bash 中執行的 cd 不會移動它，/cd 僅對從工作階段主要工作目錄執行的伺服器移動它。下表中的每一行給出您的 headersHelper 命令中相對路徑解析的目錄。

您設定伺服器的位置	工作目錄
外掛程式	外掛程式的根目錄
專案 `.mcp.json` 或本機範圍伺服器	宣告伺服器的專案目錄
您專案中的 agent 檔案、來自 SDK 的 `mcpServers` 選項或 `setMcpServers()` 方法的伺服器，或 `--mcp-config`	工作階段的主要工作目錄
使用者範圍、受管 MCP、claude.ai 連接器，或來自您專案外的 agent 檔案，包括來自 `--add-dir` 目錄的檔案	您的設定目錄，`~/.claude`，除非您設定 `CLAUDE_CONFIG_DIR`

在 v2.1.238 之前，Claude Code 也從您啟動它的目錄執行使用者範圍、受管和 claude.ai 連接器伺服器的 helper，以及來自您專案外的 agent 檔案的 helper。

Helper 可以讀取哪些變數

儲存庫或外掛程式提供的 headersHelper 是您未編寫的命令，因此 Claude Code 執行它時不會從您的環境中提供憑證變數，例如 ANTHROPIC_API_KEY。您設定伺服器的位置決定是否適用：

已移除：專案 .mcp.json 或外掛程式中的伺服器，以及來自您專案或 --add-dir 目錄的 agent 檔案中的內聯伺服器
未移除：使用者或本機範圍的伺服器、受管 MCP 中的伺服器、來自 claude.ai 連接器的伺服器、由 SDK 或 --mcp-config 提供的伺服器，以及來自 ~/.claude/agents/、受管設定或使用 --agents 傳遞的 agent 檔案中的內聯伺服器

除了 Git 的 GIT_CONFIG_KEY_<n> 變數外，Claude Code 會從您的環境中移除名稱看起來像憑證的每個變數，例如名稱中包含 TOKEN、SECRET、PASSWORD、KEY 或 AUTH 的名稱（無論大小寫），因此 ANTHROPIC_API_KEY 和 MY_REGISTRY_TOKEN 都會被移除。Claude Code 也會移除名稱不遵循該模式的固定憑證變數清單，例如 ANTHROPIC_CUSTOM_HEADERS。當這適用於您的 helper 時，讓指令碼從檔案或憑證存放區讀取其憑證。如果伺服器的 url 帶有這些變數之一的即時值，例如 MY_REGISTRY_TOKEN，helper 接收的 CLAUDE_CODE_MCP_SERVER_URL 值也會將該部分替換為 REDACTED。

在 headersHelper 執行之前信任資料夾

Claude Code 將 headersHelper 作為任意 shell 命令執行。對於專案 .mcp.json 中或本機範圍的伺服器，它只在您接受宣告伺服器的專案目錄的信任對話方塊後執行 helper。在 v2.1.238 之前，claude -p 或 SDK 工作階段執行這些 helper 而不檢查信任，互動式工作階段在您信任父資料夾後執行它們。

不計算的信任：父資料夾的信任，以及 claude -p 或 SDK 工作階段為設定檔中的 hook 獲得的自動信任
直到您信任資料夾：Claude Code 僅使用其靜態 headers 連接伺服器。在 claude -p 或 SDK 工作階段中，它也會為每個伺服器將一行 headersHelper not run 列印到 stderr，告訴您如何授予信任。
無對話方塊的信任：在 ~/.claude.json 中將 projects["<path>"].hasTrustDialogAccepted 設定為 true。<path> 是專案允許規則和工作區信任所說明 Claude Code 用來作為信任鍵的資料夾。

Claude Code 將相同規則應用於在 agent 檔案中內聯宣告的伺服器，檢查該 agent 檔案來自何處：您的專案（對於其 .claude/agents/ 目錄中的檔案）或 --add-dir 目錄。直到您信任該專案或目錄本身，Claude Code 完全不會載入伺服器，因此其 helper 也永遠不會執行。

從 JSON 配置新增 MCP servers

如果您有 MCP server 的 JSON 配置，您可以直接新增它：

從 JSON 新增 MCP server

# 基本語法
claude mcp add-json <name> '<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

驗證 server 已新增

claude mcp get weather-api

提示：

確保 JSON 在您的 shell 中正確逸出
JSON 必須符合 MCP server 配置架構
您可以使用 --scope user 將 server 新增到您的使用者配置，而不是專案特定的配置

從 Claude Desktop 匯入 MCP servers

如果您已在 Claude Desktop 中配置了 MCP servers，您可以匯入它們：

從 Claude Desktop 匯入 servers

# 基本語法 
claude mcp add-from-claude-desktop 

選擇要匯入的 servers

執行命令後，您會看到一個互動式對話框，允許您選擇要匯入的 servers。

驗證 servers 已匯入

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 帳戶登入 Claude Code，您在 claude.ai 中新增的 MCP 伺服器（稱為 connectors）會自動在 Claude Code 中可用：

在 claude.ai 中設定 MCP 伺服器

在 claude.ai/customize/connectors 新增伺服器。在 Team 和 Enterprise 方案上，只有管理員可以新增伺服器。

驗證 MCP 伺服器

在 claude.ai 中完成任何必要的驗證步驟。

在 Claude Code 中檢視和管理伺服器

在 Claude Code 中，使用命令：

/mcp

來自 claude.ai 的伺服器會出現在清單中，並有指示器顯示它們來自 claude.ai。

Anthropic 也自行提供一些 connectors，無需您或管理員新增。在可使用 Claude Docs 的帳戶上，/mcp 會列出 claude.ai Claude Docs，無需設定，當您要求建立供他人使用的文件時，Claude 會使用它。若要關閉它，請將 "claude.ai Claude Docs" 的 serverName 項目新增至 deniedMcpServers，或使用 /mcp 切換，兩者都在停用 claude.ai connectors 中說明。當您的組織在 claude.ai 中管理其驗證時，Claude Code 會在 /mcp 和 /plugin 管理員中將 connector 標記為 managed。Managed 狀態不會改變 Claude Code 連接到 connector 的方式，也不會改變您組織的工具控制的應用方式。您從未登入過的 Connectors 會在 claude.ai 區段末尾的 Show unused connectors 列後面摺疊，因此組織佈建的清單不會填滿面板。選擇該列以展開它們。您之前登入過的 connector 即使目前需要重新驗證，仍會保持可見。 Connectors 來自 claude.ai 時，只有在您的作用中驗證方法是 claude.ai 訂閱登入時才會擷取。即使您之前執行過 /login，在以下情況下也不會載入：

ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 處於作用中
Amazon Bedrock 或 Google Cloud 的 Agent Platform 等第三方提供者處於作用中
ANTHROPIC_PROFILE、federation 變數或作用中的 Anthropic 設定檔提供認證
CLAUDE_CODE_OAUTH_TOKEN 持有來自 claude setup-token 的權杖，該權杖只能進行模型請求

如果 /mcp 未列出您新增的 connector，請執行 /status 以確認哪個驗證方法處於作用中。取消設定該環境變數、移除 apiKeyHelper 設定，或關閉設定檔，然後執行 /login 以選擇您的 claude.ai 帳戶。如果暫時性網路問題導致您的工作階段啟動時無法載入 connector 清單，Claude Code 會在背景中重試擷取最多三次，一旦重試成功，connectors 就會出現。如果它們仍未出現，請重新啟動 Claude Code 以再次擷取清單。如果 /mcp 顯示 connector 為 session token rejected，或其詳細檢視顯示 claude.ai rejected the session token，則 claude.ai 拒絕了來自您 Claude Code 登入的權杖。再次授權 connector 不會清除此狀態，因為被拒絕的不是 connector 在 claude.ai 中的授權。若要清除它：

執行 /login 以再次登入。
從 /mcp 重新連接 connector。

在 v2.1.222 之前，Claude Code 將 connectors 標記為需要驗證，授權它們無法解決此問題。您在 Claude Code 中新增的伺服器會優先於指向相同 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，指導您改為在 claude.ai/customize/connectors 連接服務。在您使用 claude mcp remove <name> 移除您的項目並在 claude.ai 上連接服務後，connector 會自動出現在 Claude Code 中。

Connectors 如何到達 Claude Code

哪些設定控制 claude.ai connector 取決於您的工作階段在何處執行，因為只有某些工作階段本身從 claude.ai 擷取 connectors。下表中的每一列命名 connectors 在一種工作階段中的到達方式及其控制方式。桌面應用程式的 WSL 工作階段沒有列，因為 connectors 在其中尚不可用。

工作階段執行位置	Connectors 如何到達	控制它們的因素
Terminal、VS Code、JetBrains 和 Agent SDK 工作階段	Claude Code 從 claude.ai 擷取它們	本節中的設定和 managed MCP 設定
Cloud 工作階段	雲端主機傳入它們	您的 claude.ai 組織設定，加上到達工作階段的 allowlist 和 denylist 設定，以及執行它的主機上的任何 `managed-mcp.json`
桌面應用程式的本機和 SSH 工作階段	桌面應用程式在程序中傳遞它們	您組織的 connector 工具控制中的 `blocked` 項目

disableClaudeAiConnectors、ENABLE_CLAUDEAI_MCP_SERVERS 和 allowAllClaudeAiMcps 只作用於第一列，Claude Code 本身擷取的 connectors。其他兩列在以下方面與其不同：

Cloud 工作階段：到達工作階段的 allowedMcpServers 和 deniedMcpServers 項目（例如透過 server-managed 設定）也會篩選傳遞的 connectors。工作階段的代理會重寫每個 connector 的 URL，因此為 connector 自己的 URL 編寫的 serverUrl 模式不會符合它。若要在自託管環境中的 URL allowlist 旁邊允許傳遞的 connectors，請新增 Connector 流量離開您的網路下列出的 serverUrl 項目。當執行工作階段的主機上存在 managed-mcp.json 時（例如 self-hosted runner 主機），Claude Code 會捨棄傳遞的 connectors，無論您是否設定 allowAllClaudeAiMcps。
桌面應用程式本機和 SSH 工作階段：桌面應用程式將 connectors 註冊為程序內 type: "sdk" 伺服器，沒有 MCP 設定或 managed-mcp.json 到達它們。使用者可以透過在 claude.ai/customize/connectors 斷開連接來將 connector 排除在自己的工作階段之外。組織可以阻止 connector 的工具或完全關閉桌面應用程式中的 Claude Code。

組織對 connector 工具的控制

您的組織可以在 claude.ai connectors 上設定每個工具的控制。Claude Code 在啟動時讀取這些設定並在本機強制執行，除了桌面應用程式的本機和 SSH 工作階段。在那裡，桌面應用程式在傳遞 connector 之前會隱藏 blocked 工具，ask 設定不會到達 Claude Code，因此它會將工作階段的普通權限規則應用於這些工具，而不是在每次呼叫時提示。在 Claude Code 本身擷取 connectors 的工作階段中，執行 /mcp 以查看哪個設定適用於 connector 上的每個工具。

工具設定為 ask：Claude Code 會在每次呼叫時提示，原因為 Your organization requires approval for this tool。即使在 acceptEdits、auto 和 bypassPermissions 權限模式中，提示也會出現，且永遠不會提供記住您選擇的選項。符合工具的 Allow 規則也不會跳過提示。在 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 應用於它本身擷取的 connectors，而不是雲端主機或桌面應用程式傳遞的 connectors。若要關閉它擷取的 connectors，請在任何設定範圍中將設定設為 true：

{
  "disableClaudeAiConnectors": true
}

此設定使用任何來源為真的語義：任何設定來源中的 true 優先。簽入的專案 .claude/settings.json 可以選擇退出 Claude Code 本身擷取的 connectors，但專案層級的 false 無法重新啟用使用者或原則層級 true 已停用的 connectors。透過 --mcp-config 明確傳遞的伺服器不受影響。您也可以將 ENABLE_CLAUDEAI_MCP_SERVERS 環境變數設為 false，這對目前的 shell 工作階段有相同的效果：

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

若要阻止個別 claude.ai connectors 而不是全部，請按名稱或 URL 模式將它們新增至 deniedMcpServers。例如，"claude.ai Slack" 的 serverName 項目會阻止 Slack connector。您也可以執行 /mcp 以針對目前專案切換 Claude Code 擷取的任何 connector。

將 Claude Code 用作 MCP 伺服器

您可以將 Claude Code 本身用作 MCP 伺服器，其他應用程式可以連接到它：

# Start Claude as a stdio MCP server
claude mcp serve

該命令在啟動時不會列印任何內容。stdio MCP 伺服器透過 stdin 和 stdout 進行通訊，因此沉默、被阻止的終端機表示伺服器正在執行並等待用戶端連接。您可以透過將此設定新增到 claude_desktop_config.json 在 Claude Desktop 中使用它：

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

設定可執行檔路徑：command 欄位必須參考 Claude Code 可執行檔。如果 claude 命令不在您系統的 PATH 中，您需要指定可執行檔的完整路徑。若要找到完整路徑：

which claude

然後在您的設定中使用完整路徑：

{
  "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 欄位時，表示該呼叫讓其命令在背景中持續執行，例如呼叫設定了 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 的工具會針對文字內容使用該值，無論 MAX_MCP_OUTPUT_TOKENS 設定為何。傳回影像資料的工具仍受 MAX_MCP_OUTPUT_TOKENS 限制
超過限制：當沒有影像內容的成功結果超過 token 限制時，Claude Code 會將其儲存到檔案，並在對話中用命名檔案路徑的訊息取代它，以便 Claude 在需要內容時讀取該檔案。該檔案位於 ~/.claude/projects/ 下的工作階段 tool-results 目錄中。
來自 HTTP 和 SSE 伺服器的回應大小：當來自 HTTP 或 SSE 伺服器的回應超過 16 MiB 時，Claude Code 會停止讀取該回應，且請求會失敗。此限制適用於解壓縮後的單一 JSON 回應主體或事件串流中的單一事件。如果您負責維護該伺服器，請減少每個回應傳回的資料量以維持在限制之內，例如將結果分頁
來自 WebSocket 伺服器的訊息大小：當 WebSocket 伺服器傳送單一超過 16 MiB 的訊息時，Claude Code 會關閉連線，且該伺服器上進行中的呼叫會失敗。如果您負責維護該伺服器，請減少每則訊息傳回的資料量以維持在限制之內

Claude Code 已移至背景任務的呼叫會透過任務通知回報其結果。對於在前景完成的呼叫，另有兩項限制適用：

文字結果的字元限制：對於未聲明 anthropic/maxResultSizeChars 的工具，沒有影像內容的成功結果一旦超過 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：

export MAX_MCP_OUTPUT_TOKENS=50000
claude

提高特定工具的限制

如果您正在建置 MCP 伺服器，可以透過在工具的 tools/list 回應項目中設定 _meta["anthropic/maxResultSizeChars"]，允許個別工具傳回超過預設持久化到磁碟閾值 50,000 個字元的結果。Claude Code 會將該工具的閾值提高到註解值，最高可達 500,000 個字元的硬性上限。這對於傳回本質上很大但必要的輸出的工具很有用，例如資料庫 schema 或完整檔案樹。沒有註解的情況下，超過預設閾值的成功結果會被持久化到磁碟，並在對話中被檔案參考取代。

{
  "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/ 下的工作階段 tool-results 目錄中的檔案，並提供 Claude 路徑。Claude 隨後可以使用 Bash 等工具裁剪、轉換或重複使用完整解析度檔案。如果您使用 --no-session-persistence 或 CLAUDE_CODE_SKIP_PROMPT_HISTORY 停用工作階段持久性，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 取得的功能旗標來開啟排除功能。在停用旗標取得的部署上，或在旗標從未到達的機器上（例如隔離的機器），Claude Code 仍會執行檢查並在伺服器的日誌中記錄哪個工具會被拒絕，但仍會將工具的綱要傳送給 API。API 會拒絕包含該綱要的請求，並返回 400 錯誤，按位置命名工具。在 v2.1.216 之前，沒有部署執行這些檢查。根層級組合子處理是獨立的，當旗標取得關閉或旗標從未到達時，會保持自己的行為。

名稱超過 128 個字元的工具

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

要求特定工具的核准

如果您正在建立 MCP 伺服器，可以透過在工具的 tools/list 回應項目中將 _meta["anthropic/requiresUserInteraction"] 設定為 true，來標記工具在每次呼叫時都需要明確核准。該值必須是 JSON 布林值 true；任何其他值都會被忽略。 Claude Code 會在每次呼叫時顯示該工具的權限提示，即使在 acceptEdits、auto 和 bypassPermissions 權限模式中也是如此，並且不會為其提供「不再詢問」選項。與該工具相符的允許規則也不會跳過提示。在 dontAsk 模式中（從不提示），Claude Code 會改為拒絕該呼叫。提示必須到達一個人。在非互動模式下使用 --permission-prompt-tool，來自提示工具的 allow 結果對於標記的工具會被轉換為拒絕，並顯示訊息 MCP tool requires user interaction; not supported via --permission-prompt-tool。Agent SDK 的 canUseTool 回呼確實會接收這些呼叫並可以核准它們，因為您的 SDK 應用程式應該會將它們顯示給使用者。將此用於權限提示本身就是重點的工具，例如同意或存取授予步驟，其中自動核准意味著沒有人類曾經同意。來自同一伺服器的其他工具保持其正常的權限行為。以下 tools/list 項目將一個工具標記為始終需要核准。

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

某些使用介面，例如 Remote Control 和基於 Agent SDK 建立的應用程式，通常允許您透過一次點擊來核准工具呼叫。對於使用此註解標記的工具，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。如果您正在建置使用徵詢功能的 MCP 伺服器，請參閱 MCP 徵詢規格以了解協定詳細資訊和結構描述範例。在使用 protocol revision 2026-07-28 的連線上，Claude Code 在其用戶端功能中宣告 elicitation: {form: {}, url: {}}，因此該處的伺服器可以透過協定的標準徵詢請求來請求任一模式。

使用 MCP 資源

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

參考 MCP 資源

列出可用資源

在您的提示中輸入 @ 以查看來自所有已連接 MCP 伺服器的可用資源。資源會與檔案一起出現在自動完成選單中。

參考特定資源

使用格式 @server:protocol://resource/path 來參考資源：

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

多個資源參考

您可以在單一提示中參考多個資源：

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 資源仍然有效。

使用 MCP 工具搜尋進行擴展

工具搜尋透過延遲工具定義直到 Claude 需要時才載入，來保持 MCP 上下文使用量較低。只有工具名稱和伺服器指令在工作階段開始時載入，因此新增更多 MCP 伺服器對您的上下文視窗影響最小。Claude Code 不會對每個伺服器施加固定的工具上限；實際限制是您的上下文視窗預算。

工具搜尋在 Microsoft Foundry 部署於 Azure 的部署上不受支援，該部署在伺服器端拒絕它：Claude Code 偵測到拒絕並改為對該部署預先載入 MCP 工具。ENABLE_TOOL_SEARCH 無法覆寫此設定，因為拒絕來自部署本身。

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

如果您正在建立 MCP 伺服器，啟用工具搜尋時伺服器指令欄位會變得更有用。伺服器指令幫助 Claude 瞭解何時搜尋您的工具，類似於 skills 的運作方式。新增清晰、描述性的伺服器指令，說明：

您的工具處理的任務類別
Claude 應何時搜尋您的工具
您的伺服器提供的關鍵功能

Claude Code 會截斷超過下列預設限制的工具描述或伺服器指令，Claude 只會看到截斷點之前的文字：

伺服器指令，以及預先載入之工具的描述：4,096 個字元
Claude 透過工具搜尋載入之工具的描述：16,384 個字元

請保持描述和指令簡潔，並將關鍵詳細資訊放在開頭。當工具搜尋將 Claude 的查詢與工具描述比對時，只會讀取較短限制內的部分，因此也請將 Claude 會搜尋的字詞放在開頭附近。只要工具未被延遲，就會預先載入並適用較短的限制，例如當工具搜尋關閉、工具被標記為預先載入，或其伺服器豁免延遲時。在 v2.1.296 之前，較短的限制為 2,048 個字元；在 v2.1.295 之前，該限制適用於每個工具描述，包括透過工具搜尋載入的描述。 Anthropic 在 api.anthropic.com 託管的部分 MCP 伺服器，其描述和指令會完整傳送給 Claude。若要變更工作階段中其他 MCP 伺服器的限制，請將 CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH 設定為字元數。您設定的數字會取代這兩個限制：例如 8192 會提高較短的限制並降低較長的限制。此變數需要 Claude Code v2.1.280 或更新版本。

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

若要控制伺服器中某個工具的載入方式，請在該工具的 _meta 物件中設定 "anthropic/alwaysLoad"。將您的伺服器新增到 Claude Code 的人也可以在其設定中為整個伺服器設定 alwaysLoad，而其設定可以覆寫您的設定：

您的工具的值	結果
`true`	該工具會預先載入。啟動不會因為此值而等待您的伺服器。設定您伺服器的人仍可以延遲其所有工具
`false`	當對方的設定指定 `"alwaysLoad": true` 時，該工具仍保持延遲。這適用於您的伺服器透過 `--mcp-config` 傳入、由 Agent SDK 應用程式提供，或由外掛提供的情況。在其他伺服器上，該工具會預先載入。需要 Claude Code v2.1.285 或更新版本

以下 tools/list 項目要求某個工具預先載入：

{
  "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 會保持工具搜尋關閉。您無法透過自己設定 ENABLE_TOOL_SEARCH 來覆寫它。在 Claude Code v2.1.227 或更新版本上，您的組織可以透過受管設定在此變數之下保持工具搜尋開啟。在套用 HIPAA 設定的工作階段中，工具搜尋會關閉，且 ENABLE_TOOL_SEARCH 和受管設定都無法將其重新開啟。停用預發行功能涵蓋覆寫適用的位置以及變數移除的內容。 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 工具預先載入，無延遲

# Use a custom 5% threshold
ENABLE_TOOL_SEARCH=auto:5 claude

# Disable tool search entirely
ENABLE_TOOL_SEARCH=false claude

或在您的 settings.json env 欄位中設定值。您也可以特別停用 ToolSearch 工具：

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

豁免伺服器不延遲

如果伺服器的工具應始終對 Claude 可見而無需搜尋步驟，請在該伺服器的設定中將 alwaysLoad 設定為 true。該伺服器的工具隨後會載入到上下文中，無論 ENABLE_TOOL_SEARCH 設定如何。對於 Claude 在每個回合都需要的少量工具使用此設定，因為每個預先載入的工具會消耗原本可用於您的對話的上下文。以下 .mcp.json 項目豁免一個 HTTP 伺服器，同時保持其他伺服器延遲：

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

alwaysLoad 欄位在所有伺服器類型上都可用。設定 alwaysLoad: true 也會使啟動等待伺服器的工具，上限為標準 5 秒連線逾時，因為它們必須在建立第一個提示詞時存在。具有有效 cached 項目的遠端伺服器從快取提供其工具而無需連線，因此它不會延遲啟動。其他伺服器預設在背景連線；設定 MCP_CONNECTION_NONBLOCKING=0 也使啟動等待它們。

延遲伺服器的工具

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

使用 MCP 提示作為命令

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

執行 MCP 提示

探索可用的提示

輸入 / 以查看您可用的命令，包括來自 MCP 伺服器的命令。Claude Code 將每個 MCP 提示列為 /servername:promptname (MCP)。輸入 /mcp__servername__promptname 也會執行它。

執行沒有引數的提示

/mcp__github__list_prs

執行帶有引數的提示

許多提示接受引數。在命令後以空格分隔的方式傳遞它們。Claude Code 在空白處分割引數，因此每個引數是單一令牌：

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

提示：

MCP 提示從連接的伺服器動態探索
引數根據提示的定義參數進行解析
提示結果直接注入到對話中
在 /mcp__servername__promptname 形式中，Claude Code 將伺服器名稱中 A-Z、a-z、0-9、_ 和 - 之外的任何字元替換為 _，並使用伺服器聲明的提示名稱

Managed MCP 設定

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

​使用 MCP 可以做什麼

​尋找並建立 MCP servers

​安裝 MCP 伺服器

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

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

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

​Claude Code 如何停止 stdio 伺服器

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

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

​從 URL 新增伺服器

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

​從 mcpServers JSON 區塊新增伺服器

​管理您的伺服器

​伺服器狀態

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

​伺服器狀態詳細資訊

​設定警告

​工具可用性

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

​MCP 用戶端執行時

​動態工具更新

​v2 執行時上的通知流

​自動重新連接

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

​失敗的首次連接

​失敗的發現請求

​自行重試失敗的伺服器

​Claude 如何了解伺服器失敗

​使用頻道推送訊息

​長工具呼叫的自動背景化

​外掛提供的 MCP 伺服器

​MCP 安裝範圍

​Local scope

​Project scope

​User scope

​Scope 階層和優先順序

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

​支援的語法

​擴展位置

​使用變數擴展的範例

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

​讀取為空的認證變數

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

​實用範例

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

​範例：查詢您的 PostgreSQL 資料庫

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

​從命令列進行身分驗證

​使用固定的 OAuth 回呼連接埠

​使用預先設定的 OAuth 憑證

​覆寫 OAuth 中繼資料探索

​限制 OAuth 範圍

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

​Helper 執行的位置

​Helper 可以讀取哪些變數

​在 headersHelper 執行之前信任資料夾

​從 JSON 配置新增 MCP servers

​從 Claude Desktop 匯入 MCP servers

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

​Connectors 如何到達 Claude Code

​組織對 connector 工具的控制

​停用 claude.ai connectors

​將 Claude Code 用作 MCP 伺服器

​MCP 輸出限制和警告

​提高特定工具的限制

​工具結果中的影像

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

​具有無效輸入綱要的工具

​名稱超過 128 個字元的工具

​要求特定工具的核准

​回應 MCP 徵詢請求

​使用 MCP 資源

​參考 MCP 資源

​使用 MCP 工具搜尋進行擴展

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

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

​設定工具搜尋

​豁免伺服器不延遲

​延遲伺服器的工具

​使用 MCP 提示作為命令

使用 MCP 可以做什麼

尋找並建立 MCP servers

安裝 MCP 伺服器

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

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

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

Claude Code 如何停止 stdio 伺服器

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

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

從 URL 新增伺服器

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

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

管理您的伺服器

伺服器狀態

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

伺服器狀態詳細資訊

設定警告

工具可用性

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

MCP 用戶端執行時

動態工具更新

v2 執行時上的通知流

自動重新連接

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

失敗的首次連接

失敗的發現請求

自行重試失敗的伺服器

Claude 如何了解伺服器失敗

使用頻道推送訊息

長工具呼叫的自動背景化

外掛提供的 MCP 伺服器

MCP 安裝範圍

Local scope

Project scope

User scope

Scope 階層和優先順序

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

支援的語法

擴展位置

使用變數擴展的範例

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

讀取為空的認證變數

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

實用範例

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

範例：查詢您的 PostgreSQL 資料庫

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

從命令列進行身分驗證

使用固定的 OAuth 回呼連接埠

使用預先設定的 OAuth 憑證

覆寫 OAuth 中繼資料探索

限制 OAuth 範圍

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

Helper 執行的位置

Helper 可以讀取哪些變數

在 headersHelper 執行之前信任資料夾

從 JSON 配置新增 MCP servers

從 Claude Desktop 匯入 MCP servers

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

Connectors 如何到達 Claude Code

組織對 connector 工具的控制

停用 claude.ai connectors

將 Claude Code 用作 MCP 伺服器

MCP 輸出限制和警告

提高特定工具的限制

工具結果中的影像

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

具有無效輸入綱要的工具

名稱超過 128 個字元的工具

要求特定工具的核准

回應 MCP 徵詢請求

使用 MCP 資源

參考 MCP 資源

使用 MCP 工具搜尋進行擴展

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

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

設定工具搜尋

豁免伺服器不延遲

延遲伺服器的工具

使用 MCP 提示作為命令