透過 MCP 將 Claude Code 連接到工具

使用 MCP 可以做什麼

• 從問題追蹤器實現功能：“新增 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

/plugin install mcp-server-dev@claude-plugins-official

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

安裝 MCP 伺服器

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

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

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

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

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

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Claude Code 如何停止 stdio 伺服器

• 在 macOS 和 Linux 上：Claude Code 會傳送 SIGINT，若程序在 100 毫秒後仍在執行則傳送 SIGTERM，再過 400 毫秒後傳送 SIGKILL。
• 在 Windows 上：Claude Code 會關閉伺服器的 stdin，若程序在 300 毫秒後仍在執行，則結束伺服器的程序樹。

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

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

依據為其他用戶端撰寫的設定說明新增伺服器

• URL，例如 https://mcp.example.com/mcp：伺服器為遠端伺服器。
• 啟動命令，例如 npx -y @example/mcp-server：伺服器在您的電腦上執行。
• mcpServers JSON 區塊：為其他用戶端設定檔撰寫的設定。

從 URL 新增伺服器

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

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

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

從 mcpServers 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"]}'

管理您的伺服器

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get notion

# Remove a server
claude mcp remove notion

# (within Claude Code) Check server status
/mcp

伺服器狀態

• ⏸ 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 面板重新開啟該伺服器。
• ✘ Blocked by enterprise managed policy：被您組織的某項政策拒絕的伺服器。Claude Code 會在 claude mcp list 和 claude mcp get <name> 中都顯示它。被受管 MCP 設定中的允許清單、拒絕清單或其他限制封鎖的伺服器，會在這兩個命令中都被隱藏，而不是以此狀態顯示。請詢問您的管理員是哪項政策封鎖了該伺服器。

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

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

伺服器狀態詳細資訊

連線失敗與未設定的伺服器

• 路徑與查詢字串絕不會出現在該訊息中。
• 對於本機、專案或使用者範圍中或受管 MCP 設定中的伺服器，來源會顯示該設定中所寫的主機，因此主機中的 ${VAR} 參照在訊息中不會被展開。
• 對於沒有狀態碼或錯誤碼的失敗，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 中，部分憑證變數則會讀取為空值，且不會發出警告。

工具可用性

雲端工作階段中的工具數量

• 您儲存庫的 .claude/settings.json 中有拒絕規則指向該工具或其整個伺服器：若您的工作階段會讀取該檔案，請移除該規則
• 工具的完整名稱超過 128 個字元：請依照名稱過長的處理步驟
• 伺服器將該工具列給自己的介面使用，而非給 Claude：若您維護該伺服器，請在工具的 _meta.ui.visibility 中加入 model，讓 Claude 可使用該工具。否則，無須修正任何東西。

來自仍在連線中之伺服器的工具

• 使用工具搜尋（預設）時：等待發生在 ToolSearch 呼叫內。
• 未使用工具搜尋時：Claude 改用 WaitForMcpServers 工具。未使用工具搜尋的設定包括 ENABLE_TOOL_SEARCH=false，以及在 Google Cloud 的 Agent Platform 上使用早於 Claude Opus 4.5、Claude Sonnet 4.5 和 Claude Haiku 4.5 的模型。對於 ANTHROPIC_BASE_URL 閘道，請參閱透過 LLM 閘道使用工具搜尋。
• 在 Microsoft Foundry 託管於 Azure 的部署上：Claude 會從工具搜尋路徑開始，而非使用 WaitForMcpServers，因為 Claude Code 只能從 API 得知該部署的伺服器端拒絕。在 Claude Code 將該部署切換為預先載入後，來自完成連線之伺服器的工具會在 Claude 的下一個請求中變為可用。

停用伺服器而不移除

• disabledMcpServers：選擇退出清單，適用於使用者設定的伺服器、外掛伺服器、您的組織透過受管設定提供的伺服器、Claude Code 自行擷取的 claude.ai 連接器，以及預設為開啟的內建伺服器。Claude Code 不會連線到您在此列出的伺服器。當您使用停用 claude.ai 連接器中所述的每專案 /mcp 切換停用 claude.ai 連接器時，Claude Code 會以其顯示名稱將其寫入此清單，例如 claude.ai Slack。
• enabledMcpServers：選擇加入清單，適用於預設為關閉的內建伺服器，例如 computer-use。Claude Code 只有在您於此列出預設關閉的伺服器時才會連線到它。

MCP 用戶端執行環境

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

• 詢問 HTTP、stdio 和 claude.ai 連接器伺服器是否支援較新的修訂版，並對支援者使用它。這包括雲端和 Remote Control 工作階段的連接器。Claude Code 與其他所有伺服器的連線方式與 v1 相同。
• 透過它保持開啟的串流，從使用較新修訂版的伺服器接收 list_changed 通知。
• 不會註冊以較新修訂版連線的頻道伺服器，因為該修訂版無法承載頻道訊息。
• 當授權回應指出非預期的簽發者時，讓 MCP OAuth 登入失敗。
• 只將 MCP OAuth 憑證傳送到透過 HTTPS 提供，或位於 localhost、127.0.0.1 或 ::1 的 token 端點。若伺服器的 token 端點在其他任何位置使用純 http://（例如您區域網路上的裝置），登入會失敗。請參閱 Refusing to send credentials to non-https token endpoint。

動態工具更新

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

v2 執行環境上的通知串流

• 串流在 10 秒內再次關閉：Claude Code 最多重新開啟三次，之後就對該連線停止。
• 串流保持開啟超過 10 秒後才關閉（連到無伺服器主機的串流常見此情形）：在一小時內重新開啟五次後，Claude Code 會等待約六小時才進行下一次。

自動重新連線

遠端伺服器在工作階段中途中斷

• 在互動式工作階段中：Claude Code 重新連線期間，/mcp 會將該伺服器顯示為待處理。五次嘗試失敗後，Claude Code 會將該伺服器標記為失敗，或在伺服器需要重新授權時標記為需要身分驗證。當它將伺服器標記為失敗時，您會看到 MCP server "<name>" disconnected · open /mcp to reconnect 通知。您可以從 /mcp 手動重試。
• 在 claude -p 執行和 Agent SDK 工作階段中：Claude Code 會進行相同的五次嘗試，但沒有 /mcp 面板可顯示。若五次皆失敗，執行會在沒有該伺服器工具的情況下繼續：
  • 在暫時性錯誤之後，例如 5xx 回應或逾時：Claude Code 會在背景持續重試 HTTP 或 SSE 伺服器。重試最多持續約半小時，當某次連線成功時，該伺服器的工具會再次可用。在此之前，Agent SDK 工作階段會回報狀態 failed，而您的程式碼可以重新連線該伺服器。若要在 claude -p 中重新連線，請重新開始執行。
  • 當伺服器需要您重新登入時：Claude Code 會停止重試，且 Agent SDK 工作階段會將該伺服器的狀態回報為 needs-auth。請在您的 shell 中使用 claude mcp login <name> 登入。然後重新開始執行，或在 Agent SDK 工作階段中改為重新連線該伺服器。

首次連線失敗

• stdio 伺服器的首次連線。若要再次嘗試，請參閱結束或無法啟動的 stdio 伺服器
• WebSocket 伺服器的首次連線。若要在互動式終端機工作階段中再次嘗試，請從 /mcp 中該伺服器的選單選取 Reconnect
• 身分驗證錯誤或找不到錯誤，因為這需要變更設定才能解決。當 headersHelper 是伺服器 Authorization 標頭的唯一來源時，Claude Code 仍會重試身分驗證錯誤，因為它會在每次嘗試時重新執行該輔助程式，並可取得新的憑證

結束或無法啟動的 stdio 伺服器

探索請求失敗

自行重試失敗的伺服器

Claude 如何得知伺服器失敗

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

透過頻道推送訊息

MCP 工具呼叫的時間限制

• 依伺服器：在該伺服器的設定項目中加入以毫秒為單位的 timeout 欄位
• 跨所有伺服器：設定 MCP_TOOL_TIMEOUT

長時間工具呼叫的自動背景化

• 以毫秒為單位設定 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 環境變數以變更門檻，或將其設為 0 以關閉自動背景化。設為 0 時，Claude 在互動式工作階段中也會等待 MCP 任務
• 將 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 設為 1，以關閉自動背景化和背景命令

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

在伺服器上執行的 MCP 任務

停止 MCP 任務或取得其結果

MCP task <server task id> (<server>/<tool>) completed.

回答來自 MCP 任務的問題

在 MCP 任務執行期間結束、清除或恢復

呼叫成為 MCP 任務所需的條件

• 伺服器支援任務
• 伺服器是以協定修訂版 2026-07-28 連線的 HTTP、stdio 或 claude.ai 連接器伺服器。設定 MCP_SDK_GENERATION=v1 或 MCP_PROTOCOL_NEGOTIATION=legacy 會排除此條件
• 工作階段會擷取功能旗標，因此不是在 Amazon Bedrock 之類的第三方供應商上，也未關閉遙測或旗標擷取
• Anthropic 已為您這類工作階段開啟 MCP 任務。在 v2.1.304 或更新版本上，這涵蓋終端機 CLI 工作階段、Agent SDK 工作階段和 GitHub Actions 執行。其他使用介面，例如 VS Code 擴充功能和桌面應用程式，沒有 MCP 任務
• 呼叫來自主對話，而非來自 subagent
• 工作階段為互動式，或是讀取 --input-format stream-json 的 Agent SDK 工作階段或 claude -p 執行具備：
  • CLAUDE_AUTO_BACKGROUND_TASKS 為 1
  • CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND 不為 1
  • CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 不為 0

MCP 任務的狀態訊息

MCP 任務的時間限制

讓 Claude 等待 MCP 任務的結果

• CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 設為 0：Claude 會等待每個 MCP 工具呼叫直到呼叫結束
• CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND 設為 1：Claude 會等待任務的結果。在自動背景化開啟期間，它預設會在兩分鐘後移動該呼叫，因此短任務會就地完成，而長任務不會阻擋您。被移動的呼叫是一般背景呼叫，而非 MCP 任務。它不會在結束工作階段後保留

{
  "env": {
    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "0"
  }
}

給伺服器作者的 MCP 任務說明

以任務回應呼叫

{
  "resultType": "task",
  "taskId": "build-7f3a9c2e",
  "status": "working",
  "statusMessage": "Compiling, 40 of 212 files done",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:03:07Z",
  "ttlMs": null,
  "pollIntervalMs": 5000
}

回報狀態、結果和問題

{
  "resultType": "complete",
  "taskId": "build-7f3a9c2e",
  "status": "completed",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:09:41Z",
  "ttlMs": null,
  "result": {
    "content": [{ "type": "text", "text": "Build succeeded: 212 files, 0 warnings" }]
  }
}

外掛提供的 MCP 伺服器

• 外掛在外掛根目錄的 .mcp.json 中定義 MCP 伺服器，或直接內嵌於 plugin.json 中
• 當您啟用外掛時，Claude Code 會自動啟動其 MCP 伺服器
• Claude Code 會將外掛 MCP 工具與手動設定的 MCP 工具一併提供
• 外掛伺服器是透過安裝或解除安裝外掛來新增與移除，而非使用 /mcp 命令。您仍可在 /mcp 中將已安裝的外掛伺服器切換為關閉，這會讓 Claude Code 停止連線至該伺服器，而不會移除外掛

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

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

• 自動生命週期：伺服器會在以下時機連線與中斷連線：
  • 在工作階段啟動時，Claude Code 會自動連線已啟用外掛的伺服器。在 /mcp 中，您先前使用過的遠端（HTTP 或 SSE）外掛伺服器可能會改為顯示 cached 狀態；Claude Code 會在 Claude 首次呼叫其某個工具時連線該伺服器。當 stdio 外掛伺服器的連線在不到 15 分鐘前失敗時，Claude Code 會略過該連線
  • 如果您在工作階段期間啟用或停用外掛，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 傳輸，但傳輸支援可能因伺服器而異

• stdio 伺服器：會印出 Command: stdio、一行空的 Args:，並將每個環境變數顯示為 NAME=[REDACTED]
• WebSocket 伺服器：會印出 URL: ws，並將每個標頭顯示為 <name>: [REDACTED]，而 claude mcp list 會以 ws 取代 URL 顯示

mcp__plugin_my-plugin_database-tools__query

MCP 安裝範圍

Local 範圍

# Add a local-scoped server (default)
claude mcp add --transport http stripe https://mcp.stripe.com

# Explicitly specify local scope
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Project 範圍

# Add a project-scoped server
claude mcp add --transport http shared-server --scope project https://example.com/mcp

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

• 將其加入 disabledMcpjsonServers，這會在每種權限模式中封鎖它。
• 使用 --setting-sources 或 SDK 的 settingSources 選項完全排除專案設定。
• 使用 --strict-mcp-config 啟動工作階段。Claude Code 隨後只會使用您透過 --mcp-config 傳入的 MCP 伺服器。對於 Claude Code 未載入的 project 範圍伺服器略過核准提示，需要 Claude Code v2.1.246 或更新版本；在 v2.1.246 之前，strict 工作階段仍會等待這些伺服器的核准，導致背景工作階段在啟動時停滯等待。如需此旗標在受管 MCP 檔案下的作用，請參閱使用 managed-mcp.json 進行獨佔控制。

User 範圍

# Add a user server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

範圍階層與優先順序

1. Local 範圍
2. Project 範圍
3. User 範圍
4. 外掛提供的伺服器
5. claude.ai 連接器

.mcp.json 中的環境變數展開

• ${VAR}：展開為環境變數 VAR 的值
• ${VAR:-default}：若已設定 VAR，則展開為 VAR 的值；若未設定，則展開為 default

變數展開範例

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

未設定且沒有預設值的變數

設定為空字串的變數

讀取為空值的憑證變數

• Claude Code 本身的憑證，例如 ANTHROPIC_API_KEY 與 ANTHROPIC_AUTH_TOKEN
• 您雲端供應商的憑證，例如 AWS_BEARER_TOKEN_BEDROCK
• 您環境中攜帶的其他憑證，例如 HTTPS_PROXY 與 NPM_TOKEN

參照在 /mcp 與 CLI 輸出中的顯示方式

• 伺服器 /mcp 詳細資訊檢視中的 URL 或命令列
• claude mcp list 與 claude mcp get 輸出

實用範例

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

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

審查 PR #456 並建議改進

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

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

範例：查詢您的 PostgreSQL 資料庫

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

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

顯示 orders 表的 schema

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

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

• 對於您尚未登入的伺服器，任一狀態碼都會在 /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 重新連接它，而不是從工作階段進行。

• 您儲存的登入資訊有重新整理 token：它會重新整理該 token、重新連接並重試請求一次。只有在該重試也失敗時，伺服器才會在 /mcp 中被標記。
• 您儲存的登入資訊沒有重新整理 token：它會在不使用該 token 的情況下連接一次。如果伺服器有回應，其工具會在您登出狀態下運作，且被拒絕的 token 會被刪除。如果伺服器也拒絕該連線，/mcp 會顯示該伺服器需要身分驗證。

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

/mcp

從命令列進行身分驗證

claude mcp login sentry

claude mcp login sentry --no-browser

使用固定的 OAuth 回呼連接埠

# Fixed callback port with dynamic client registration
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

使用預先設定的 OAuth 憑證

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

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

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

覆寫 OAuth 中繼資料探索

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

限制 OAuth 範圍

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

對位於需驗證之代理伺服器後方的伺服器使用 OAuth

• 代理伺服器的標頭：使用 --header、headers 欄位或 headersHelper 傳遞，並使用代理伺服器讀取的名稱
• OAuth 登入：不要將 Authorization 放入已設定的標頭中，然後在您的 shell 中使用 claude mcp login <name> 登入。如果您設定了 Authorization 標頭，Claude Code 會將其作為伺服器的憑證，不會為該伺服器回退到 OAuth。

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

{
  "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 執行的位置

Helper 可以讀取哪些變數

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

在 headersHelper 執行之前信任資料夾

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

登入位於需要標頭之閘道後方的 MCP 伺服器

• 您可以編輯其設定的伺服器：在 headers 中設定它，或從 headersHelper 傳回它
• 由受管 MCP 或外掛提供的伺服器：請您的管理員或外掛作者將該標頭新增到伺服器的項目中

• 授權頁面：您在瀏覽器中於此頁面登入，而瀏覽器不會傳送已設定的標頭。如果您的瀏覽器收到的是閘道的錯誤而非該頁面，請要求閘道的管理者讓該頁面在沒有標頭的情況下通過。
• 位於其他來源的授權伺服器：如果該伺服器前方的閘道也需要該標頭，登入會在那裡失敗。請要求該閘道的管理者讓 OAuth 請求在沒有標頭的情況下通過。

從 JSON 配置新增 MCP servers

# 基本語法
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

claude mcp get weather-api

從 Claude Desktop 匯入 MCP servers

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

claude mcp list 

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

/mcp

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

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

Connectors 如何到達 Claude Code

• 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 工具的控制

• 工具設定為 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 connectors

{
  "disableClaudeAiConnectors": true
}

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

將 Claude Code 用作 MCP 伺服器

# Start Claude as a stdio MCP server
claude mcp serve

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

which claude

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

以 MCP 用戶端身分讀取背景命令的輸出

• 若要讀取目前為止的輸出：從您的用戶端開啟該路徑的檔案，或將該路徑作為 file_path 傳遞給伺服器的 Read 工具
• 若要得知命令何時完成：在 command 值後附加一個輸出固定字串的 echo，例如 npm test; echo DONE。當該字串出現在檔案中時，命令即已完成。若沒有該字串，就沒有任何標記表示結束，因為 Claude Code 不會在檔案中加入結尾行，也不會通知您的用戶端。
• 若要讀取長輸出的結尾：僅使用 file_path 呼叫 Read 會傳回第一頁，或在檔案超過大小限制時失敗。請同時傳遞 offset 和 limit，這在任何檔案大小下皆可運作：
  1. 呼叫 Read，並將 offset 和 limit 皆設為 1，然後從結果中取得 totalLines
  2. 再次呼叫 Read，將 offset 設為 totalLines 減九，並將 limit 設為 10
  3. 在第二次呼叫傳回的最後十行中尋找您的 echo 字串

MCP 輸出限制和警告

• 輸出警告閾值：當任何 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 會關閉連線，且該伺服器上進行中的呼叫會失敗。如果您負責維護該伺服器，請減少每則訊息傳回的資料量以維持在限制之內

• 文字結果的字元限制：對於未聲明 anthropic/maxResultSizeChars 的工具，沒有影像內容的成功結果一旦超過 50,000 個字元，無論其 token 數為何，Claude Code 都會將其儲存到檔案。設定 MAX_MCP_OUTPUT_TOKENS 不會改變此閾值
• 錯誤結果：當工具傳回標記為 isError: true 的結果時，Claude 會將該結果的文字作為工具的錯誤訊息接收。超過約 11,000 個字元的錯誤文字只會保留其前 5,000 個和後 5,000 個字元，中間會有一個標記說明移除了多少字元

export MAX_MCP_OUTPUT_TOKENS=50000
claude

提高特定工具的限制

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

工具結果中的影像

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

• allOf：來自每個分支的屬性會被合併，每個分支的 required 清單仍然適用
• anyOf 和 oneOf：來自每個分支的屬性會被合併，每個分支的 required 清單會在工具描述中說明，而不是由綱要強制執行

具有無效輸入綱要的工具

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

• Claude 會取得未經變更的工具，而伺服器的日誌會針對該工具記錄 input schema would be rejected by the Anthropic API
• 如果 API 隨後拒絕該 schema，請參閱 API 拒絕其輸入 schema 的工具

API 拒絕其輸入 schema 的工具

• 如果您的工作階段因按位置指名工具的 400 錯誤而失敗：請依照工具輸入 schema 無效中的步驟操作
• 如果您使用該伺服器：您不需要執行任何操作。Claude 仍然可以呼叫該工具，但看不到其參數
• 如果您維護該伺服器：請在伺服器上修復該工具的輸入 schema。日誌行以 The API said: 及 API 拒絕該 schema 的原因結尾。請驗證伺服器收到的引數，因為 Claude 是在看不到其參數的情況下呼叫該工具

名稱超過 128 個字元的工具

要求特定工具的核准

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

標記可安全呼叫兩次的工具

• idempotentHint：該工具可能會變更某些內容，且使用相同引數再次呼叫它是安全的
• readOnlyHint：該工具不會變更任何內容。Claude Code 也會將該工具的呼叫與其他唯讀呼叫平行執行。

{
  "name": "set_issue_status",
  "annotations": {
    "idempotentHint": true
  }
}

回應 MCP 徵詢請求

• 表單模式：Claude Code 顯示一個對話框，其中包含伺服器定義的表單欄位（例如，使用者名稱和密碼提示）。填入欄位並提交。
• URL 模式：Claude Code 詢問是否在您的瀏覽器中開啟連結。伺服器使用此模式進行在終端機外完成的流程，例如登入。

在雲端工作階段中回應徵詢請求

• 表單模式：填入欄位，然後按一下 Submit
• URL 模式：按一下 Open link，完成其開啟的流程，然後在卡片上按一下 I’m done, continue

Claude Code 宣告的徵詢模式

• 使用 protocol revision 2026-07-28 的連線
• 在較早協定修訂版本（2025-11-25 及更舊版本）上，連線至使用者 Claude Code MCP 設定中的 stdio、sse、http 和 ws 伺服器的連線。需要 Claude Code v2.1.287 或更新版本

使用 MCP 資源

參考 MCP 資源

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

使用 MCP 工具搜尋進行擴展

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

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

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

變更描述長度限制

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

{
  "name": "search_tickets",
  "description": "Searches the ticket tracker by keyword",
  "_meta": {
    "anthropic/alwaysLoad": true
  }
}

設定工具搜尋

• Claude Opus 4.5、Sonnet 4.5、Haiku 4.5 及更新版本：工具搜尋預設為開啟，與 Anthropic API 上相同。
• 較早的 Agent Platform 模型：Claude Code 預先載入所有 MCP 工具，因為它們的服務堆疊拒絕所需的測試版標頭。ENABLE_TOOL_SEARCH=true 不會覆寫此設定。

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

# Disable tool search entirely
ENABLE_TOOL_SEARCH=false claude

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

透過 LLM 閘道使用工具搜尋

低於 ENABLE_TOOL_SEARCH=auto 閾值時仍保持延遲的工具

豁免伺服器不延遲

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

延遲伺服器的工具

使用 MCP 提示作為命令

執行 MCP 提示

/mcp__github__list_prs

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

Managed MCP 設定