SpyBara
Go Premium

mcp.md 2026-09-28 22:59 UTC to 2026-09-29 05:02 UTC

This page contains 660 additions and 273 deletions.

2026
Mon 28 22:59 Tue 29 05:02

透過 MCP 將 Claude Code 連接到工具

了解如何使用 Model Context Protocol 將 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 為您建立伺服器。

1

安裝 plugin

在 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 新增 marketplace，然後重試安裝。
  • plugin 在 marketplace 中找不到：檢查 plugin 名稱。

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

2

執行建立 skill

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

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

安裝 MCP servers

MCP servers 可以根據您的需求以多種方式進行配置：

選項 1：新增遠端 HTTP server

HTTP servers 是連接到遠端 MCP servers 的推薦選項。這是雲端服務最廣泛支援的傳輸方式。

# 基本語法
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 servers 時，type 欄位接受 streamable-http 作為 http 的別名。MCP 規範使用名稱 streamable-http 作為此傳輸，因此從 server 文件複製的配置無需修改即可運作。

沒有 type 但有 url 的 JSON 項目是配置錯誤，因為 Claude Code 將沒有 type 的項目讀取為 stdio server。Claude Code 會跳過該 server 並報告 MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry。在 v2.1.202 之前，Claude Code 將此配置錯誤報告為 command: expected string, received undefined。

只有 SDK 主機應用程式（例如 Agent SDK 應用程式或 桌面應用程式）可以註冊進程內 "type": "sdk" server。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 項目，因此指令碼可以偵測到 server 從未載入。這需要 Claude Code v2.1.219 或更新版本。

選項 2：新增遠端 SSE server

某些服務仍然只公開 SSE 端點。使用與 HTTP server 相同的 claude mcp add --transport http <name> <url> 命令新增這些。Claude Code 首先嘗試 HTTP 傳輸，當 server 不接受時切換到 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 server

Stdio servers 在您的機器上作為本機程序執行。它們非常適合需要直接系統存取或自訂指令碼的工具。

Claude Code 在生成的 server 環境中設定 CLAUDE_PROJECT_DIR 為專案根目錄，因此您的 server 可以解析專案相對路徑，而無需依賴工作目錄。這與 hooks 在其 CLAUDE_PROJECT_DIR 變數中接收的目錄相同。從您的 server 程序內部讀取它，例如 Node 中的 process.env.CLAUDE_PROJECT_DIR 或 Python 中的 os.environ["CLAUDE_PROJECT_DIR"]。

CLAUDE_PROJECT_DIR 是穩定的專案根目錄，在 session 中途新增或移除工作目錄時不會變更。限制自身檔案系統存取到一組允許目錄的 server 應該改為實作 MCP roots/list 請求。Claude Code 使用 session 的啟動目錄加上您透過 --add-dir、/add-dir 或 additionalDirectories 設定授予的每個額外工作目錄來回答 roots/list。當該集合變更時，Claude Code 會傳送 notifications/roots/list_changed。在 v2.1.203 之前，roots/list 只傳回啟動目錄，Claude Code 不會傳送 notifications/roots/list_changed。

此變數在 server 的環境中設定，而不是在 Claude Code 自己的環境中，因此在專案範圍的 .mcp.json 項目或本機或使用者範圍的 server 項目中透過 ${VAR} 擴展參考它需要預設值，例如 ${CLAUDE_PROJECT_DIR:-.}。Plugin 提供的 MCP 配置直接替換 ${CLAUDE_PROJECT_DIR}，不需要預設值。

# 基本語法
claude mcp add [options] <name> -- <command> [args...]

# 實際範例：新增 Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

選項 4：新增遠端 WebSocket server

WebSocket servers 保持持久的雙向連接，適合遠端 MCP servers 主動向 Claude 推送事件。當您的 server 只回應請求時，請改用 HTTP，因為 HTTP 支援 OAuth 和 claude mcp add --transport 旗標，而 WebSocket 都不支援。

在 .mcp.json 中或使用 claude mcp add-json 配置 WebSocket servers：

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 生成一個。claude mcp add --transport 旗標不接受 ws。

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

MCP servers 不是 Claude Code 特有的，因此 server 的設定指示可能是為 Claude Desktop、Cursor 或另一個 MCP 用戶端編寫的，並且不提供 claude mcp add 命令。若要新增 server，請在這些指示中尋找 URL、啟動命令或 JSON 區塊：

  • URL，例如 https://mcp.example.com/mcp：server 是遠端的。
  • 啟動命令，例如 npx -y @example/mcp-server：server 在您的機器上執行。
  • mcpServers JSON 區塊：為另一個用戶端的設定檔案編寫的配置。

每一個都是 安裝 MCP servers 中四個選項之一所採用的輸入。在下面找到您擁有的形狀，以將其轉換為 Claude Code 接受的命令。除非您新增 --scope project 或 --scope user，否則每個命令都會寫入本機範圍。

從 URL

URL 表示 server 是遠端的。對於 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` 或二進位命令

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

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，而不是包裝器。兩個項目需要先修復：

  • 沒有 type 的 url：新增 "type": "http"、"type": "sse" 或 "type": "ws" 以符合端點。Claude Code 將沒有 type 的項目讀取為 stdio server，因此沒有 type 的 url 項目會失敗。
  • 具有字母、數字、連字號和底線以外字元的金鑰：選擇僅使用這些字元的 server 名稱。否則金鑰是 server 名稱。

例如，此區塊：

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

變成此命令：

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

從 JSON 配置新增 MCP servers 涵蓋 add-json 的 shell 逃逸和 --scope 旗標。若要改為與您的團隊共享 server，請新增 --scope project，或在您的專案根目錄的 .mcp.json 中的 mcpServers 下新增項目並提交它。專案範圍涵蓋 Claude Code 如何載入和批准該檔案。

每個 claude mcp add 和 claude mcp add-json 命令都會列印一行 Added ...。若要檢查 Claude Code 是否已連接，請執行 claude mcp get <name>；Server 狀態涵蓋它顯示的狀態和 .mcp.json servers 的批准步驟。

管理您的 servers

配置後，您可以使用這些命令管理您的 MCP servers：

# 列出所有已配置的 servers
claude mcp list

# 取得特定 server 的詳細資訊
claude mcp get notion

# 移除 server
claude mcp remove notion

# (在 Claude Code 中) 檢查 server 狀態
/mcp

當您移除遠端 server 時，Claude Code 也會刪除為該 server 儲存的 OAuth tokens 和用戶端註冊。

Server 狀態

claude mcp add 透過列印 Added ... 行確認成功新增，這表示配置已寫入。claude mcp list 然後在它列出的每個 server 旁邊顯示健康狀態，例如 ✔ Connected、! Needs authentication 或 ✘ Failed to connect。失敗狀態表示 Claude Code 無法連接到該 server，而不是列表命令失敗。

此列表中的狀態報告配置決定而不是連接嘗試，因此 Claude Code 在不連接到 server 的情況下列印它們：

  • ⏸ Pending approval (run `claude` to approve)：來自 .mcp.json 的專案範圍 server，您尚未批准。Claude Code 在 claude mcp list 和 claude mcp get <name> 中都顯示它。執行 claude 互動式命令以檢查和批准它。
  • ✘ Rejected (see disabledMcpjsonServers in settings)：由 disabledMcpjsonServers 項目拒絕的 .mcp.json server。Claude Code 只在 claude mcp get <name> 中顯示它。
  • ⊘ Disabled for this project (re-enable via /mcp)：專案的 disabledMcpServers 列表命名的 server。Claude Code 在 claude mcp list 和 claude mcp get <name> 中都顯示它。從 /mcp 面板重新開啟 server。在 v2.1.238 之前，兩個命令都連接到已停用的 server 以進行健康檢查並報告連接結果。

WebSocket servers 不會出現在 claude mcp list 輸出中。使用 claude mcp get <name> 或 /mcp 面板檢查它們。

專案 server 批准和工作區信任

自 v2.1.196 起，claude mcp list 和 claude mcp get 只從未簽入儲存庫的設定檔案中讀取 .mcp.json 批准，直到您透過在其中執行 claude 並接受工作區信任對話框來信任工作區。複製的儲存庫無法批准自己的 servers：提交到專案 .claude/settings.json 的 enableAllProjectMcpServers 或 enabledMcpjsonServers 在不受信任的資料夾中被忽略，server 保持在 ⏸ Pending approval 而不是被連接和健康檢查。

這些來源的批准仍然適用於不受信任的資料夾：

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

Claude Code 也會套用來自未追蹤 .claude/settings.local.json 的批准，但它執行 git 以檢查檔案是否被追蹤，並且它只在受信任的資料夾中執行該檢查。在您從未信任的資料夾中，Claude Code 會等待信任對話框，然後才能套用檔案的批准，除非該資料夾是您自己的配置主目錄：您的主目錄，或您已設定為 CLAUDE_CONFIG_DIR 的 .claude 的目錄。在 v2.1.207 之前，Claude Code 在您從未信任的資料夾中套用了來自未追蹤 .claude/settings.local.json 的批准。

任何設定檔案中的 disabledMcpjsonServers 項目仍然會拒絕 server。

Server 狀態詳細資訊

在 /mcp 中（包括 server 的選單）和 /plugin 管理器中，您之前使用過的遠端 HTTP 或 SSE server 可以顯示 cached 狀態，例如 cached 2h ago · connects on first use · 5 tools。Claude Code 從發現快取（在上一個 session 中儲存）載入了 server 的工具列表，而不是在啟動時連接，Claude Code 在 Claude 首次呼叫 server 的其中一個工具時連接 server。工具從您的第一條訊息開始可用，因此您無需執行任何操作。發現快取及其 cached 狀態需要 Claude Code v2.1.221 或更新版本。

發現快取預設為關閉，除非逐步推出已為您的帳戶啟用它。設定 MCP_DISCOVERY_CACHE=1 以開啟它，或設定 0 以在推出啟用它時保持關閉。在 v2.1.238 之前，快取預設為開啟。

當您從 server 選單中選擇 Disable 或 Clear authentication 時，Claude Code 也會捨棄該 server 的快取項目。Reconnect 在已連接或失敗的 server 上也會捨棄它；在 cached server 上，Reconnect 現在連接 server 並保留項目。捨棄項目後，Claude Code 從 server 而不是從快取中擷取 server 的工具列表。

當 server 的狀態為 ✘ Failed to connect 時，claude mcp list 會將失敗詳細資訊附加到該狀態行，claude mcp get <name> 在 Issue: 行上顯示它：HTTP 狀態或錯誤代碼，加上 server 傳回的任何錯誤文字。server 在 /mcp 中的詳細檢視在其 Issue: 列中包含相同的 server 報告文字。Claude Code 從此詳細資訊中編輯類似認證的文字，並且永遠不會包含擴展的 server URL，它可能攜帶機密。Claude Code 不會將詳細資訊附加到 ✘ Connection error 狀態，因為它會列印的例外文字可以嵌入該 URL。在 v2.1.219 之前，兩個命令都只顯示裸失敗狀態，沒有狀態代碼或 server 的錯誤文字。

當您從 /mcp 完成驗證且連接仍然因 HTTP 狀態或傳輸錯誤代碼而失敗時，Claude Code 會在嘗試後列印的訊息中新增該代碼和 server URL 的來源。來源是方案和主機，加上 URL 命名時的連接埠，例如 https://mcp.example.com。

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

配置為空 url 的遠端 server 在 /mcp、claude mcp list 和 /plugin 管理器中顯示為 not configured，Claude Code 不會嘗試連接到它。Plugin 可以包含一個佔位符項目，例如此項目，用於您稍後配置的連接器，因此 Claude Code 不會將其報告為錯誤或設定問題。server 在 /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 不會修剪空白，並完全按照寫入的方式使用值，因此編輯配置以移除它。
  • 在多個範圍中具有相同名稱：如果您在多個範圍中定義相同的 server 名稱，具有不同的端點，Claude Code 會在 claude mcp list 輸出和 /mcp 中警告衝突。Claude Code 按端點儲存 OAuth 登入，因此當您驗證在一個專案中載入的定義時，您仍然需要在不同定義載入的專案中單獨登入。保留您想要的端點並使用 claude mcp remove <name> --scope <scope> 移除其他端點。在警告中，Claude Code 引用每個範圍的端點，如在您的配置中寫入的，具有${VAR} 參考未展開，因此它永遠不會顯示已解析的值，例如 API 金鑰。
  • 保留名稱：Claude Code 保留其內建 servers 的名稱，包括 workspace、claude-in-chrome、computer-use、Claude Preview 和 Claude Browser。如果您的配置定義了具有保留名稱的 server，Claude Code 會在載入時跳過它，並顯示警告要求您重新命名它。claude mcp add 會以錯誤拒絕保留名稱。Claude Preview 和 Claude Browser 都命名了 Claude Code 桌面應用程式的預覽窗格使用的內建 server。在 v2.1.205 之前，Claude Browser 未被保留，因此使用者配置的 server 可以在該名稱下註冊。
  • 遺漏的環境變數：如果配置中的 ${VAR} 參考命名未設定且沒有 :-default 的變數，Claude Code 會在 claude mcp list 輸出和 /mcp 中警告，命名變數，並仍然使用 ${VAR} 文字未展開載入 server。設定變數或新增 ${VAR:-default} 後備。在遠端 server 的 url 和 headers 中，某些認證變數讀取為空，沒有警告。

工具可用性

/mcp 面板在每個已連接的 server 旁邊顯示工具計數，並標記宣告工具功能但未公開任何工具的 servers。

如果您的請求需要來自仍在背景連接的 server 的工具，Claude 會在繼續之前等待該 server。等待如何發生取決於您的配置：

  • 使用工具搜尋（預設）：等待發生在 ToolSearch 呼叫內。
  • 沒有工具搜尋：Claude 改為使用 WaitForMcpServers 工具。沒有工具搜尋的配置包括自訂 ANTHROPIC_BASE_URL、ENABLE_TOOL_SEARCH=false 和 Google Cloud 的 Agent Platform 上早於 Claude 4.5 世代的模型。
  • 在 Microsoft Foundry 部署託管在 Azure 上：Claude 在工具搜尋路徑上啟動，而不是使用 WaitForMcpServers，因為 Claude Code 只從 API 發現部署的伺服器端拒絕。Claude Code 將該部署切換到前期載入後，來自完成連接的 server 的工具在 Claude 的下一個請求上變得可用。

啟用工具搜尋後，當 server 在 Claude 工作時完成連接時，Claude Code 在同一輪的下一個請求中將 server 的工具名稱列出給 Claude。Claude 然後可以搜尋和呼叫這些工具，而無需等待您的下一條訊息。

停用 server 而不移除它

在 /mcp 面板中切換 server 關閉，以停止 Claude Code 連接到它，而不會失去其配置。Claude Code 仍然在 /mcp 中列出 server，標記為已停用。

當您切換 server 時，Claude Code 在 ~/.claude.json 中按專案記錄您的選擇，在兩個涵蓋不相交 server 集合的列表之一中：

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

Claude Code 為每個 server 查詢恰好兩個列表之一，因此兩個列表都不會覆蓋另一個。如果您將常規 server 新增到 enabledMcpServers，或將預設關閉的內建 server 新增到 disabledMcpServers，Claude Code 會忽略該項目。

disabledMcpServers 和 enabledMcpServers 與 enabledMcpjsonServers 和 disabledMcpjsonServers 無關，它們控制專案 .mcp.json 檔案中定義的 servers 的批准。

MCP 用戶端執行時

Claude Code 透過兩個用戶端執行時之一連接到 MCP servers。v1 執行時建立在 MCP TypeScript SDK 1.x 上。v2 執行時是 MCP TypeScript SDK 2.0 上的相同代碼，它新增了 MCP 協議修訂版 2026-07-28。此頁面的其餘部分適用於兩個執行時，除非某個部分命名 v2 執行時。

Claude Code 每次啟動時選擇執行時，並保持到您退出。在擷取功能旗標的 sessions 中，它在 Claude Code v2.1.232 或更新版本上使用 v2 執行時。

在不擷取功能旗標的 sessions 中，Claude Code 在 Claude Code v2.1.274 或更新版本上預設使用 v2 執行時：

  • Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的 Sessions，除非嵌入 Claude Code 的主機平台設定 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST
  • 透過 Claude apps gateway 登入的 Sessions
  • 您關閉遙測或功能旗標擷取的 Sessions，例如使用 DISABLE_TELEMETRY

在 v2 上，Claude Code 也：

  • 詢問 HTTP servers 是否支援較新的修訂版，並與支援的 servers 一起使用它。它也在擷取功能旗標的 sessions 中詢問 claude.ai 連接器 servers。若要讓它詢問 stdio servers 或每個 session 中的連接器 servers，請設定 MCP_PROTOCOL_NEGOTIATION 為 auto。它連接到每個其他 server，如 v1 所做的那樣。
  • 從較新修訂版上的 servers 接收 list_changed 通知，透過它保持開啟的流。
  • 不註冊在較新修訂版上連接的channel server，因為該修訂版無法攜帶 channel 訊息。
  • 失敗MCP OAuth 登入，其授權回應命名意外的簽發者。

Anthropic 可以使用 Claude Code 擷取的功能旗標將特定 server 保持在較早的協議上，或關閉該流。

若要自己選擇執行時，請設定 MCP_SDK_GENERATION 為 v1 或 v2。若要決定 Claude Code 是否詢問，請設定 MCP_PROTOCOL_NEGOTIATION 為 auto 或 legacy。

動態工具更新

Claude Code 支援 MCP list_changed 通知，允許 MCP servers 動態更新其可用工具、提示和資源，而無需您斷開連接並重新連接。當 MCP server 傳送 list_changed 通知時，Claude Code 會自動重新整理該 server 的可用功能。

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

v2 執行時上的通知流

在 v2 執行時上，Claude Code 從較新協議修訂版上的 server 接收 list_changed 通知，透過它保持開啟的流。當流關閉時，Claude Code 會重新開啟它，有兩個限制：

  • 流在 10 秒內再次關閉：Claude Code 最多重新開啟它三次，然後停止該連接。
  • 流保持開啟超過 10 秒，然後關閉，如流到無伺服器主機通常所做的那樣：在一小時內五次重新開啟後，Claude Code 在下一次之前等待約六小時。

直到流重新開啟，您保留 server 的最後擷取的工具、提示和資源。若要更快地選擇其變更，請從 /mcp 重新連接 server。

自動重新連接

Claude Code 重新連接在 session 中途斷開的遠端 server，並在暫時性錯誤後重試 HTTP 或 SSE server 的首次連接。Stdio servers 是本機程序，Claude Code 不會自動重新連接它們。

遠端 server 的中途斷開

Claude Code 使用指數退避重新連接已斷開的遠端 server：最多五次嘗試，從一秒延遲開始，每次加倍。您看到的內容取決於您如何執行 Claude Code：

  • 在互動式 session 中：/mcp 在 Claude Code 重新連接時將 server 顯示為待處理。五次失敗嘗試後，Claude Code 將 server 標記為失敗，或在 server 需要再次授權時標記為需要驗證。當它將 server 標記為失敗時，您會看到 MCP server "<name>" disconnected · open /mcp to reconnect 通知。您可以從 /mcp 手動重試。
  • 在 claude -p 執行和 Agent SDK sessions 中：Claude Code 按相同的時間表重新連接，沒有 /mcp 面板顯示嘗試。

失敗的首次連接

當 HTTP 或 SSE server 的首次連接因暫時性錯誤（例如 5xx 回應、連接被拒絕或逾時）失敗時，Claude Code 最多重試三次。如果連接仍然失敗，Claude Code 將 server 標記為失敗。Claude Code 在啟動時和 server 在 session 中途新增時以這種方式重試。這包括 Claude Code 從其配置新增到雲端 session 的 server 和您使用 Agent SDK 的 setMcpServers() 新增的 server。

Claude Code 在這些情況下不會重試：

  • WebSocket server 的首次連接
  • 驗證或找不到錯誤，因為它需要配置變更才能解決。當 headersHelper 是 server 的 Authorization 標頭的唯一來源時，Claude Code 無論如何都會重試驗證錯誤，因為它在每次嘗試時重新執行 helper 並可以選擇新的認證

失敗的發現請求

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

Claude 如何了解 server 失敗

Claude Code 是否告訴 Claude 配置的 server 無法連接取決於工具搜尋，預設為開啟：

  • 使用工具搜尋，Claude Code 告訴 Claude 哪個 server 失敗及其連接錯誤，因此 Claude 在其回應中報告連接失敗。Claude Code 在找不到匹配工具的 ToolSearch 結果中包含相同的資訊。
  • 在任何沒有工具搜尋的配置中，Claude Code 不會向 Claude 報告失敗的 server 連接。

使用 channels 推送訊息

MCP server 也可以直接將訊息推送到您的 session 中，以便 Claude 可以回應外部事件，例如 CI 結果、監控警報或聊天訊息。若要啟用此功能，您的 server 宣告 claude/channel 功能，並在啟動時使用 --channels 旗標選擇加入。請參閱 Channels 以使用官方支援的 channel，或 Channels reference 以建立您自己的。

在 v2 執行時上，如果您設定 MCP_PROTOCOL_NEGOTIATION 為 auto 且 channel server 協商 MCP 協議修訂版 2026-07-28，它無法傳遞 channel 訊息，因此 Claude Code 不會將其註冊為 channel。保留變數未設定，或將其設定為 legacy，將 stdio servers 保持在較早的握手上。

每個 server 的 timeout 是每個工具呼叫的硬牆鐘限制，來自 server 的進度通知不會延長它。低於 1000 的值會被忽略並落回到 MCP_TOOL_TIMEOUT，或在該變數未設定時落回到其預設值約 28 小時。對於 HTTP、SSE 或claude.ai 連接器 server，還有第二個每個請求的計時器，涵蓋每個請求直到 server 的第一個回應位元組。Claude Code 將該計時器設定為三個值中最大的：60 秒、適用於 server 的工具逾時和 MCP_TIMEOUT。未設定的 MCP_TOOL_TIMEOUT 的 28 小時預設值不會進入該比較，低於 60 秒的值不會縮短計時器。Stdio 和 WebSocket servers 沒有每個請求的計時器。

每個 server 至少 1000 的 timeout 也會作為下面所述的閒置逾時的下限：Claude Code 永遠不會因為閒置而在每個 server 的 timeout 之前中止該 server 的工具呼叫。需要 Claude Code v2.1.203 或更新版本。

對遠端 MCP server 的工具呼叫如果在閒置視窗內沒有傳送回應和進度通知，會以錯誤中止，而不是等待牆鐘限制。它適用於除 IDE servers 和 SDK 進程內 servers 之外的每種 server 類型。HTTP、SSE、WebSocket 和 claude.ai 連接器 servers 的閒置視窗預設為五分鐘，stdio servers 的預設為 30 分鐘。在 v2.1.203 之前，stdio servers 不受閒置逾時限制。

在毫秒中設定 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT 環境變數以變更閒置視窗，或將其設定為 0 以停用檢查。

這些逾時限制呼叫可以執行多長時間，不一定總是它阻止 session 多長時間：執行超過兩分鐘的主對話呼叫會先移至背景工作。請參閱長工具呼叫的自動背景化。

長工具呼叫的自動背景化

主對話中仍在執行兩分鐘後的 MCP 工具呼叫會移至背景工作，而不是阻止 session。Claude 立即接收工作 ID 並繼續工作，結果在呼叫解決時作為工作通知到達。自動背景化需要 Claude Code v2.1.212 或更新版本。

工作出現在 /tasks 中，您也可以在其中停止它，它不會在退出 session 時存活。每個呼叫限制仍然適用於呼叫在背景執行時：由每個 server timeout 或 MCP_TOOL_TIMEOUT 設定的牆鐘限制，以及由 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT 設定的閒置逾時。

設定 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 環境變數（以毫秒為單位）以變更閾值，或將其設定為 0 以關閉自動背景化。設定 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 為 1 也會關閉它，以及所有其他背景工作功能。

某些呼叫永遠不會移至背景：

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

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

Plugin 提供的 MCP servers

Plugins 可以捆綁 MCP servers，在啟用 plugin 時提供工具和整合。Plugin MCP servers 的工作方式與使用者配置的 servers 相同。

Plugin MCP servers 的工作方式：

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

Plugin MCP 配置範例：

在 plugin 根目錄的 .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"]
    }
  }
}

Plugin MCP 功能：

  • 自動生命週期：servers 在這些點連接和斷開：
    • 在 session 啟動時，Claude Code 自動連接已啟用 plugins 的 servers。在 /mcp 中，您之前使用過的遠端 (HTTP 或 SSE) plugin server 可以顯示cached 狀態而不是；Claude Code 在 Claude 首次呼叫其其中一個工具時連接它
    • 如果您在 session 期間啟用或停用 plugin，Claude Code 在變更套用時連接或斷開其 MCP servers。在不重新啟動的情況下套用 plugin 變更描述何時發生。在沒有互動式終端的 session 中，/reload-plugins 不會連接或斷開 plugin MCP servers；這些變更在您的下一個 session 中生效
    • 當您重新載入時，Claude Code 保留配置未變更的 plugin servers 的即時連接，並在您替換 session 的 MCP server 列表而不命名它們時執行相同操作
    • 當您在 v2.1.246 或更新版本上使用 /cd 移動 session 時，Claude Code 連接新目錄的設定啟用的 plugins 的 servers，並斷開不再啟用的 plugins 的 servers，因此您不需要在移動後執行 /reload-plugins
    • 在雲端 sessions 中，對尚未連接的 plugin server 的 MCP 呼叫（例如在閒置 session 喚醒後），按需啟動 server 並等待它連接
  • 路徑佔位符：${CLAUDE_PLUGIN_ROOT} 解析為 plugin 的安裝目錄，${CLAUDE_PLUGIN_DATA} 解析為其持久狀態目錄，${CLAUDE_PROJECT_DIR} 解析為穩定的專案根目錄。替換適用於：
    • stdio servers：command、args、env
    • http、sse 和 ws servers：url、headers 和 headersHelper。在 v2.1.195 之前，headersHelper 將佔位符作為字面字符串傳遞
  • 使用者環境存取：存取與手動配置的 servers 相同的環境變數
  • 多種傳輸類型：支援 stdio、SSE、HTTP 和 WebSocket 傳輸，傳輸支援可能因 server 而異

Plugin servers 在 /mcp 中出現，並有指示器顯示它們來自 plugins。

Plugin MCP 工具名稱：

來自 plugin 捆綁的 MCP server 的工具在其可呼叫名稱中包含 plugin 名稱和 server 金鑰。完整形式是 mcp__plugin_<plugin-name>_<server-name>__<tool-name>，其中 A-Z、a-z、0-9、_ 和 - 以外的任何字元都被替換為 _。對於在名為 my-plugin 的 plugin 中捆綁的 database-tools server，query 工具可呼叫為：

mcp__plugin_my-plugin_database-tools__query

在 permission rules、skill 的 allowed-tools 列表、subagent 的 tools 欄位 或 hook matcher 中參考工具時，請使用此完整名稱。針對裸 server 金鑰（例如 mcp__database-tools__.*）編寫的 hook matcher 永遠不會針對 plugin 捆綁的 server 觸發。

server 本身在範圍名稱 plugin:<plugin-name>:<server-name> 下註冊，例如 plugin:my-plugin:database-tools。在需要配置的 server 名稱的地方使用該名稱，例如 mcp_tool hook 的 server 欄位。

請參閱 plugin 元件參考，了解有關使用 plugins 捆綁 MCP servers 的詳細資訊。

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。

# 新增本機範圍的 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 項目來自該來源；欄位不會跨範圍合併。

  1. Local scope
  2. Project scope
  3. User scope
  4. Plugin-provided servers
  5. 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 命令會儲存設定而不驗證認證，因此此處接受預留位置值，但 server 稍後無法連接。若要驗證連接，請執行 /mcp 並檢查 server 是否顯示 connected。具有不良認證的 server 會顯示 failed，失敗詳細資訊包括 server 傳回的 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"

若要確認 server 啟動，請執行 /mcp 並檢查 db 是否顯示 connected。

然後自然地查詢您的資料庫：

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

顯示 orders 表的架構

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

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

許多雲端 MCP 伺服器需要身份驗證。Claude Code 支援 OAuth 2.0 以進行安全連線。

當伺服器回應 401 Unauthorized 或 403 Forbidden 時，Claude Code 會將遠端伺服器標記為需要身份驗證。Claude Code 顯示的內容取決於伺服器：

  • 對於您尚未登入的伺服器，任一狀態碼都會在 /mcp 中標記它，以便您完成 OAuth 流程。
  • 對於 claude.ai 連接器，由 claude.ai 拒絕您的工作階段令牌導致的 401 不會標記連接器，因為重新授權連接器無法修復您的登入。Claude Code 改為顯示 工作階段令牌被拒絕狀態。
  • 對於您在 headers 中或透過 headersHelper 設定 Authorization 標頭的伺服器，連線時的 401 或 403 不會標記伺服器，因為要修復的認證是您設定的認證。Claude Code 改為報告連線失敗。如果您從 ${VAR} 參考設定該標頭，請檢查該變數是否是 Claude Code 讀取為空 的變數之一。
  • 對於 傳遞到雲端工作階段的連接器，Claude Code 不會執行登入流程，因為工作階段的代理使用您在 claude.ai 中授予的授權向連接器進行身份驗證。當那裡的連接器需要再次授權時，請在 claude.ai/customize/connectors 重新連接它，而不是從工作階段進行。

當對您已登入的 OAuth 伺服器的請求返回 401 Unauthorized 時，Claude Code 會重新整理儲存的令牌、重新連接並重試請求一次。只有在該重試也失敗時，它才會在 /mcp 中標記伺服器。在 v2.1.206 之前，因暫時性原因（例如網路錯誤）失敗的令牌重新整理會將 OAuth 伺服器標記為在該工作階段的其餘時間需要身份驗證，即使其重新整理令牌仍然有效。

當伺服器拒絕儲存的重新整理令牌時，Claude Code 會立即顯示指向 /mcp 的通知。開啟 /mcp 並在伺服器上選擇 Re-authenticate 以在下一個工具呼叫失敗之前再次登入。

傳回指向其授權伺服器的 WWW-Authenticate 標頭的自訂伺服器會獲得與任何其他遠端伺服器相同的自動探索。

當一個或多個已設定的伺服器需要身份驗證時，Claude Code 也會顯示啟動通知，因此您不必開啟 /mcp 來探索哪些伺服器需要登入。該通知需要 Claude Code v2.1.193 或更新版本。它只計算您可以從 Claude Code 登入的伺服器。在 v2.1.218 之前，它也計算在 claude.ai 中未連接的 claude.ai 連接器，您只能從 claude.ai 設定進行連接。

該通知會宣佈每個伺服器一次，並在後續啟動時將其排除在計數之外，直到該伺服器已連接並再次需要登入。/mcp 仍會列出每個需要登入的伺服器。

在非互動模式下，沒有 /mcp 面板，因此 Claude Code 無法為您執行 OAuth 流程。從 v2.1.196 開始，當已設定的伺服器在啟用 工具搜尋（預設值）的 claude -p 或 Agent SDK 執行期間需要身份驗證時，Claude Code 會告訴 Claude 該伺服器的工具不可用，直到您授權它。Claude 可以命名需要登入的伺服器，而不是回應為好像伺服器未設定。從具有 /mcp 或 claude mcp login <name> 的互動工作階段完成登入。

如果您為伺服器設定了 headers.Authorization 且伺服器拒絕該標頭，Claude Code 會報告連線失敗，而不是回退到 OAuth。檢查令牌對 MCP 端點是否有效，或移除標頭以使用 OAuth 流程。

1

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

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

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

在 Claude Code 中使用 /mcp 命令

在 Claude Code 中，使用命令：

/mcp

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

從命令列進行身份驗證

claude mcp login <name> 命令直接從您的 shell 執行已設定伺服器的 OAuth 流程，因此您不需要在工作階段內開啟 /mcp 面板。

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 一起使用（使用預先設定的認證）。

# 使用動態用戶端註冊的固定回呼連接埠
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 應用程式，然後在新增伺服器時提供認證。

1

使用伺服器註冊 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。

2

使用您的認證新增伺服器

這些標籤涵蓋兩個命令：claude mcp add 將您的用戶端 ID 和回呼連接埠作為旗標，claude mcp add-json 在 oauth 物件中採用它們。如果您註冊了重新導向 URI，請將回呼連接埠設定為該 URI 中的連接埠。

使用 --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
3

在 Claude Code 中進行身份驗證

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

覆寫 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 伺服器決定要求的範圍集。

從 v2.1.196 開始，當未設定 oauth.scopes 時，Claude Code 會要求伺服器的 WWW-Authenticate 標頭或其受保護資源中繼資料提供的範圍，並在兩者都未提供時不傳送 scope 參數。它不再要求自動探索的授權伺服器中繼資料中的完整 scopes_supported 目錄。要求該目錄導致公告僅限管理員或範本範圍的身份提供者以 invalid_scope 錯誤拒絕授權請求。從已設定的 authServerMetadataUrl 擷取的中繼資料仍會將其 scopes_supported 作為要求的範圍提供。

如果授權伺服器在 scopes_supported 中公告 offline_access，Claude Code 會將其附加到固定範圍，以便可以在不進行新瀏覽器登入的情況下重新整理存取令牌。

如果伺服器稍後為工具呼叫傳回 403 insufficient_scope，該呼叫會失敗，並顯示 needs additional permissions 訊息，該訊息命名伺服器要求的範圍。伺服器在 /mcp 中顯示為需要身份驗證。

如果該範圍不在您的固定 oauth.scopes 中，請新增它，然後執行 /mcp 並再次驗證伺服器。Claude Code 要求固定範圍而不是伺服器命名的範圍，因此如果您在不新增它的情況下再次驗證，您獲得的令牌仍然缺少它。

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

如果您的 MCP 伺服器使用 OAuth 以外的身份驗證方案，例如 Kerberos、短期令牌或內部 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

Claude Code 在每次連線時執行新的 helper，在工作階段開始和重新連接時，一旦 專案和本機範圍伺服器的信任規則 允許它執行。它不會快取結果，因此您的指令碼負責任何令牌重用。

如果工具呼叫傳回 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 命令中相對路徑解析的目錄。

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

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

Helper 可以讀取哪些變數

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

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

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

從 JSON 配置新增 MCP servers

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

1

從 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
2

驗證 server 已新增

claude mcp get weather-api

從 Claude Desktop 匯入 MCP servers

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

1

從 Claude Desktop 匯入 servers

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

選擇要匯入的 servers

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

3

驗證 servers 已匯入

claude mcp list

透過 claude mcp 命令新增的伺服器名稱只能包含字母、數字、連字號和底線。Claude Desktop 不會套用該限制，因此名稱包含任何其他字元（例如空格）的 Claude Desktop 伺服器無法匯入。匯入會報告它拒絕的每個名稱，並仍會匯入您選擇的其他伺服器。在 v2.1.205 之前，第一個無效名稱會停止匯入，且不會新增任何選定的伺服器。

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

如果您已使用 claude.ai 帳戶登入 Claude Code，您在 claude.ai 中新增的 MCP 伺服器（稱為 connectors）會自動在 Claude Code 中可用：

1

在 claude.ai 中設定 MCP 伺服器

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

2

驗證 MCP 伺服器

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

3

在 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 為 connected · session token rejected，或其詳細檢視顯示 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 中新增的伺服器會 優先於 指向相同 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.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 伺服器，其他應用程式可以連接到它：

# 啟動 Claude 作為 stdio MCP 伺服器
claude mcp serve

該命令在啟動時不會列印任何內容。stdio MCP 伺服器透過 stdin 和 stdout 進行通訊，因此沉默、被阻止的終端表示伺服器正在執行並等待用戶端連接。

您可以透過將此設定新增到 claude_desktop_config.json 在 Claude Desktop 中使用它：

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

MCP 輸出限制和警告

當 MCP 工具產生大量輸出時，Claude Code 會幫助管理權杖使用量，以防止淹沒您的對話上下文：

  • 輸出警告閾值：當任何 MCP 工具輸出超過 10,000 個權杖時，Claude Code 會顯示警告
  • 可配置的限制：您可以使用 MAX_MCP_OUTPUT_TOKENS 環境變數調整允許的最大 MCP 輸出權杖數
  • 預設限制：預設最大值為 25,000 個權杖
  • 範圍：環境變數適用於未聲明自己限制的工具。設定 anthropic/maxResultSizeChars 的工具會針對文字內容使用該值，無論 MAX_MCP_OUTPUT_TOKENS 設定為何。傳回影像資料的工具仍受 MAX_MCP_OUTPUT_TOKENS 限制
  • 超過限制：當沒有影像內容的結果超過限制時，Claude Code 會將其儲存到檔案，並在對話中用命名檔案路徑的訊息取代它，以便 Claude 在需要內容時讀取該檔案。該檔案位於 ~/.claude/projects/ 下的工作階段 tool-results 目錄中。

若要增加產生大量輸出的工具的限制：

export MAX_MCP_OUTPUT_TOKENS=50000
claude

提高特定工具的限制

如果您正在建置 MCP 伺服器，可以透過在工具的 tools/list 回應項目中設定 _meta["anthropic/maxResultSizeChars"]，允許個別工具傳回超過預設持久化到磁碟閾值的結果。Claude Code 會將該工具的閾值提高到註解值，最高可達 500,000 個字元的硬性上限。

這對於傳回本質上很大但必要的輸出的工具很有用，例如資料庫結構描述或完整檔案樹。沒有註解的情況下，超過預設閾值的結果會被持久化到磁碟，並在對話中被檔案參考取代。

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

該註解對文字內容獨立於 MAX_MCP_OUTPUT_TOKENS 應用，因此使用者不需要為聲明它的工具提高環境變數。傳回影像資料的工具仍受權杖限制。

工具結果中的影像

當 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 接受的綱要，或在未收到啟用重寫的遠端設定的部署上時，它會跳過該工具，在伺服器的日誌中記錄原因，並讓伺服器的其他工具保持可用。早於 v2.1.195 的版本會跳過每個輸入綱要具有根層級 anyOf、oneOf 或 allOf 的工具。

具有無效輸入綱要的工具

Claude API 會檢查請求中每個工具的輸入綱要，當任何一個綱要失敗時，會拒絕整個請求並返回 400 錯誤。Claude Code 在載入伺服器的工具時會自行執行 API 的兩項檢查，並排除每個會失敗的工具，以便伺服器的其他工具繼續運作：

  • 頂層屬性名稱必須為 1 到 64 個字元長，且只能使用 ASCII 字母和數字、_、. 和 -
  • 綱要必須對 JSON Schema draft 2020-12 元綱要有效。Claude Code 會對未宣告 $schema 的綱要和宣告 draft 2020-12 的綱要套用此檢查。宣告任何其他方言的綱要會跳過此檢查，但上述屬性名稱檢查仍然適用

Claude Code 會在根層級組合子重寫之後執行檢查，對它實際會傳送的綱要進行檢查。

當 Claude Code 排除一個工具時，它會在伺服器的日誌中記錄原因，並告訴 Claude 它排除了哪些工具以及原因，以便您可以詢問 Claude 為什麼工具遺失。如果您修復伺服器上的綱要，下次 Claude Code 載入伺服器的工具時，該工具就會恢復。

Claude Code 透過從 Anthropic 取得的功能旗標來開啟排除功能。在停用旗標取得的部署上，或在旗標從未到達的機器上（例如隔離的機器），Claude Code 仍會執行檢查並在伺服器的日誌中記錄哪個工具會被拒絕，但仍會將工具的綱要傳送給 API。API 會拒絕包含該綱要的請求，並返回 400 錯誤，按位置命名工具。在 v2.1.216 之前，沒有部署執行這些檢查。

根層級組合子處理是獨立的，當旗標取得關閉或旗標從未到達時，會保持自己的行為。

要求特定工具的批准

如果您正在建立 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
  }
}

anthropic/requiresUserInteraction 註解需要 Claude Code v2.1.199 或更新版本。較早的版本會忽略它並套用標準權限流程。

某些介面，例如 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 資源

1

列出可用資源

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

2

參考特定資源

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

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

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

多個資源參考

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

Compare @postgres:schema://users with @docs:file://database/user-model

MCP Apps UI 資源是具有 ui:// URI 或 text/html;profile=mcp-app 媒體類型的項目：供主應用程式呈現的頁面，而不是供 Claude 讀取的內容。它們不會出現在 @ 建議或資源列表工具的結果中，而且只提供 UI 資源的伺服器會顯示空的資源列表。按其 URI 讀取 UI 資源仍然有效。

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

針對 MCP 伺服器作者

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

新增清晰、描述性的伺服器指令，說明：

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

Claude Code 預設將每個工具描述和每個伺服器的指令截斷為 2,048 個字元。保持簡潔，並將關鍵詳細資訊放在開頭。

若要變更工作階段中每個 MCP 伺服器的限制，請將 CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH 設定為字元數。此變數需要 Claude Code v2.1.280 或更新版本。

工具搜尋預設為啟用：MCP 工具被延遲並按需發現。當 ANTHROPIC_BASE_URL 指向非第一方主機時，Claude Code 會停用它，因為大多數代理不轉發 tool_reference 區塊。設定 ENABLE_TOOL_SEARCH 明確覆蓋該後備方案。

設定 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 保持工具搜尋關閉。您無法透過自己設定 ENABLE_TOOL_SEARCH 來覆蓋它。您的組織可以透過 managed settings 在 Claude Code v2.1.227 或更新版本上保持工具搜尋開啟。停用預發行功能 涵蓋覆蓋適用的位置以及變數移除的內容。

工具搜尋需要支援 tool_reference 區塊的模型：Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5 及更新版本的模型。請參閱 API 文件中的模型相容性以取得目前清單。

在 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 工具延遲並按需載入。在 Google Cloud 的 Agent Platform 模型早於 Claude 4.5 世代時、當 ANTHROPIC_BASE_URL 是非第一方主機時，或在部署於 Azure 的 Microsoft Foundry 部署上時，回退到預先載入
true 所有 MCP 工具延遲，除了在部署於 Azure 的 Microsoft Foundry 部署上，伺服器端拒絕仍強制預先載入，以及在 Google Cloud 的 Agent Platform 模型早於 Claude 4.5 世代上，Claude Code 保持預先載入工具。Claude Code 透過代理傳送測試版標頭，並在不支援 tool_reference 區塊的代理上要求失敗
auto 閾值模式：Claude Code 預先載入它會延遲的工具，同時它們的定義總計少於內容視窗的 10%，一旦定義達到 10% 就延遲所有工具
auto:N 具有自訂百分比的閾值模式，其中 N 是 0-100。例如，auto:5 表示 5%
false 所有 MCP 工具預先載入，無延遲 
# 使用自訂 5% 閾值
ENABLE_TOOL_SEARCH=auto:5 claude

# 完全停用工具搜尋
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 欄位在所有伺服器類型上都可用。MCP 伺服器也可以透過在工具的 _meta 物件中包含 "anthropic/alwaysLoad": true 來標記個別工具為始終載入，這對該工具只有相同的效果。

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

使用 MCP 提示作為命令

MCP 伺服器可以公開提示，這些提示在 Claude Code 中成為可用的命令。

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

執行 MCP 提示

1

探索可用的提示

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

2

執行沒有引數的提示

/mcp__github__list_prs
3

執行帶有引數的提示

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

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

Managed MCP 設定

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