連線 MCP

MCP 的價值不是“把所有工具都接進 Claude”，而是把你反覆複製貼上的外部上下文，變成可治理、可認證、可撤銷、可限權的工具連線。——翔宇

1. MCP 解決的是“上下文搬運”問題

不用 MCP 時，你通常這樣工作：

1. 開啟 Jira / Linear / GitHub issue。
2. 複製需求。
3. 開啟 Sentry / 日誌 / 資料庫。
4. 複製報錯、schema、查詢結果。
5. 粘給 Claude。
6. Claude 根據這段靜態資訊做事。

MCP 讓 Claude Code 直接連線這些系統。官方例子包括：

• 從 issue tracker 讀取需求並實現功能。
• 查 Sentry / Statsig 分析線上錯誤和使用資料。
• 查詢 PostgreSQL 資料庫。
• 根據 Figma / Slack 裡的設計更新模板。
• 建立 Gmail 草稿或自動化業務流程。
• 透過 channel 接收外部事件，讓 Claude 對 CI、監控或聊天訊息做反應。

2. 什麼時候不該接 MCP

這些場景不要急著接：

• 只是偶爾查一次資料。
• 複製一小段上下文就能完成。
• MCP server 來源不可信。
• server 會讀取不可信網頁、issue 評論、使用者輸入，但沒有 prompt injection 防護。
• server 能訪問生產資料，卻沒有隻讀賬號或最小許可權。
• server 有寫操作，但沒有審批、許可權和回復。
• 工具一次返回海量日誌、schema 或搜尋結果。
• 你還沒配置好 Claude Code permissions。

官方提醒很明確：第三方 MCP server 未必經過 Anthropic 驗證，尤其是能抓取不可信內容的 server，會帶來 prompt injection 風險。

3. MCP 三種 transport 怎麼選

Claude Code 支援三類連線方式。

• HTTP：遠端 MCP server 的推薦方式，適合雲服務和 SaaS。
• SSE：相容舊服務。官方當前說明 SSE transport 已廢棄，能用 HTTP 就不要新接 SSE。
• stdio：本機程序。適合內部指令碼、本地資料庫、本機檔案系統、需要直接跑命令的 server。

典型安裝命令：

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

claude mcp add --transport sse asana https://mcp.asana.com/sse

claude mcp add --transport stdio airtable -- npx -y airtable-mcp-server

stdio 命令裡有一個容易踩的點：Claude Code 自己的引數必須放在 server name 前面，-- 後面的內容才是傳給 MCP server 的命令和引數。

claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080

4. Windows 上 stdio 要特別處理

官方特別提醒：native Windows 裡，如果 local MCP server 用 npx，通常要加 cmd /c 包一層。

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

否則可能遇到 Connection closed，因為 Windows 不能像 Unix shell 那樣直接執行 npx。

WSL 場景按 Linux 習慣處理，不等同於 native Windows。

5. 安裝後怎麼管理

常用命令只有幾個：

claude mcp list

claude mcp get github

claude mcp remove github

會話內檢視連線、認證和來源：

/mcp

遠端 HTTP / SSE server 斷線時，Claude Code 會自動重連並使用指數退避。stdio server 是本機程序，不會自動按遠端連線邏輯重連。

6. 三種作用域：local、project、user

MCP server 有三種安裝作用域。

• local：預設。只在當前專案載入，配置儲存在 ~/.claude.json 的當前專案條目裡，不提交。適合個人試驗、本機開發 server、帶個人憑據的連線。
• project：寫入專案根目錄 .mcp.json，設計上可以提交到 git。適合團隊都需要、結構可共享、憑據不進儲存庫的 server。
• user：寫入 ~/.claude.json，跨所有專案生效。適合個人長期使用的通用工具。

安裝示例：

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

claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

7. 作用域優先順序：同名只連線一次

當同一個 server 名字在多個地方出現時，Claude Code 只連線一次，並按官方優先順序選擇定義：

1. Local scope（本地作用域）
2. Project scope（專案作用域）
3. User scope（使用者作用域）
4. Plugin-provided servers
5. Claude.ai connectors

前三層按 server name 去重。外掛和 Claude.ai connectors 按 endpoint 去重。

這意味著：你在 local scope（本地作用域）臨時加了一個同名 github，它會壓過專案 .mcp.json 裡的 github。如果排障時你發現團隊配置沒生效，先查本機 ~/.claude.json 裡是否有同名 server。

8. .mcp.json 可以提交什麼

專案級 MCP 配置會寫到：

.mcp.json

一個基本結構：

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

可以提交：

• server 名稱。
• transport 型別。
• 公開 URL。
• 本機命令結構。
• 環境變數名稱。
• 不含金鑰的預設引數。

不該提交：

• API key。
• OAuth client secret。
• 個人 token。
• 生產資料庫明文 DSN。
• 個人機器絕對路徑，除非用環境變數或預設值兜底。

9. .mcp.json 支援環境變數展開

官方支援兩種語法：

• ${VAR}：讀取環境變數。
• ${VAR:-default}：有環境變數就用，沒有就用預設值。

可展開的位置包括：

• command
• args
• env
• url
• headers

示例：

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

如果必需環境變數沒有設定、也沒有預設值，Claude Code 會解析配置失敗。

10. 專案級 server 首次使用會要求信任

Project scope 的 .mcp.json 是可以提交的，這也意味著你 clone 一個儲存庫時，儲存庫可能帶著 MCP server 配置。

官方設計了安全提示：Claude Code 使用 project-scoped server 前會要求你批准。如果要重置選擇，可以執行：

claude mcp reset-project-choices

這和 headersHelper 一起看尤其重要。headersHelper 可以執行 shell 命令動態生成 header；如果定義在 project 或 local scope，只有你接受 workspace trust 後才會執行。

11. OAuth：遠端 MCP 的推薦認證方式

很多遠端 MCP server 需要認證。Claude Code 支援 OAuth 2.0，通常流程是：

1. 新增 HTTP MCP server。
2. 在 Claude Code 裡執行 /mcp。
3. 跟隨瀏覽器登入。
4. 回到 Claude Code 檢視認證狀態。

示例：

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

/mcp

官方說明認證 token 會被安全儲存並自動重新整理。你可以在 /mcp 選單裡清除認證，必要時重新授權。

12. 固定 callback port 和預配置 OAuth 憑據

某些 MCP server 要求預先註冊 redirect URI。預設情況下，Claude Code 會隨機選擇本地可用埠作為 OAuth callback port。你可以固定埠：

claude mcp add --transport http --callback-port 8080 my-server https://mcp.example.com/mcp

如果 server 不支援 Dynamic Client Registration，可能需要預配置 client ID / secret：

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

也可以透過環境變數提供 secret：

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

官方說明 client secret 會存到系統 keychain 或 credentials file，而不是寫進配置檔案。

13. OAuth metadata 和 scope 限制

企業或內部 OAuth server 可能不能走預設 discovery。Claude Code 支援在 MCP 配置裡指定 authServerMetadataUrl：

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

這個 URL 必須是 https://。

如果要限制 OAuth 請求的 scope，可以在 oauth.scopes 裡固定範圍。官方說明 oauth.scopes 會優先於 metadata 和 server 自動發現的 scopes。不要把 scope 配到“能用就全給”，而是按最小許可權給。

14. 動態 header：headersHelper

有些內部系統 token 很短，或需要每次連線動態簽名。Claude Code 支援 headersHelper：

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

helper 要求：

• stdout 輸出 JSON object。
• key 和 value 都是字串。
• 執行超時是 10 秒。
• 動態 header 會覆蓋同名靜態 headers。
• 每次連線或重連都會重新執行，不快取。

Claude Code 執行 helper 時會提供：

• CLAUDE_CODE_MCP_SERVER_NAME
• CLAUDE_CODE_MCP_SERVER_URL

15. MCP 許可權規則怎麼寫

MCP server 接入後，不等於所有工具都應該自動放行。

Claude Code permissions 支援 MCP 工具規則：

• mcp__puppeteer：匹配 puppeteer server 提供的任意工具。
• mcp__puppeteer__*：也匹配該 server 的全部工具。
• mcp__puppeteer__puppeteer_navigate：只匹配具體工具。

更穩的做法是隻允許明確工具：

{
  "permissions": {
    "allow": [
      "mcp__sentry__get_issue",
      "mcp__github__list_pull_requests"
    ],
    "ask": [
      "mcp__github__create_issue"
    ],
    "deny": [
      "mcp__postgres__execute_write"
    ]
  }
}

16. MCP 與 sandbox 的關係

上一章講過：permissions 適用於 Bash、Read、Edit、WebFetch、MCP 等工具。sandbox 主要限制 Bash 及其子程序。

這意味著：

• MCP 工具呼叫靠 permissions 控制。
• MCP server 自己連外部 API，通常不受 Bash sandbox 直接約束。
• stdio MCP server 是本機程序，啟動命令本身要當作本機程式審查。
• 遠端 MCP server 的外部訪問邊界，主要由 server 自身許可權、OAuth scope、token、網路策略和 managed policy 控制。

17. 輸出大小也是安全和質量問題

MCP 工具輸出太大，會帶來三個問題：

• 佔滿上下文。
• 把無關資訊帶進判斷。
• 讓 prompt injection 內容更容易混入任務。

官方機制：

• 單個 MCP 工具輸出超過 10,000 tokens 會顯示警告。
• 預設最大輸出限制是 25,000 tokens。
• 可以用 MAX_MCP_OUTPUT_TOKENS 調整。

export MAX_MCP_OUTPUT_TOKENS=50000
claude

如果你是 MCP server 作者，可以為特定工具宣告 _meta["anthropic/maxResultSizeChars"]，最高到 500,000 characters。否則超出預設閾值的結果會落盤，並在會話裡替換成檔案引用。

18. Tool Search：多 MCP 不一定撐爆上下文

官方現在預設啟用 MCP Tool Search。

它的作用是：啟動時不把所有 MCP tool schema 全塞進上下文，而是先載入 tool names。Claude 需要時再搜尋相關工具，只有真正使用的工具進入上下文。

這降低了“接幾個 MCP 就佔滿上下文”的風險，但不代表可以無節制安裝。

MCP server 作者要注意：server instructions 和 tool descriptions 會影響 Claude 何時搜尋這些工具。官方說明 tool description 和 server instructions 會被截斷到 2KB 左右，所以關鍵說明要放前面。

如果某些核心工具必須始終載入，可以設定 alwaysLoad：

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

19. MCP resources：用 @ 引用外部資源

MCP server 可以暴露 resources。Claude Code 支援在 prompt 裡用 @ 引用它們。

示例：

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

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

這些資源會被自動獲取並作為附件加入上下文。路徑可以在 @ 自動補全裡模糊搜尋。

20. MCP prompts 可以變成命令

MCP server 可以暴露 prompts。Claude Code 會把它們顯示成 slash command，格式通常是：

/mcp__servername__promptname

例如：

/mcp__github__list_prs

/mcp__github__pr_review 456

prompt 結果會直接注入當前對話。server name 和 prompt name 會被規範化，空格通常變成下劃線。

21. Plugin 和 Claude.ai connectors 也會帶 MCP

MCP 不只來自你手動 claude mcp add。

外掛可以打包 MCP server：

• 外掛啟用時，server 自動連線。
• 外掛停用或啟用後，可能需要 /reload-plugins。
• plugin MCP server 會出現在 /mcp 裡，並標明來源。

Claude.ai connectors 也可能出現在 Claude Code：

• 你用 Claude.ai 賬號登入時，Claude.ai 中配置的 MCP server 會自動可用。
• Team / Enterprise 裡通常由管理員新增 connector。
• 如果 Claude Code 本地配置了相同 endpoint，優先使用本地配置，Claude.ai connector 會被隱藏。

可以關閉 Claude.ai MCP server：

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

22. Claude Code 也可以作為 MCP server

官方支援讓 Claude Code 自己作為 stdio MCP server：

claude mcp serve

這可以被 Claude Desktop 等 MCP client 呼叫。配置時 command 必須能找到 Claude Code 執行檔；如果 PATH 裡沒有 claude，要寫完整路徑。

which claude

23. 組織級 MCP 管理

企業有兩種集中管理方式。

第一種是 managed-mcp.json：管理員部署固定 MCP server 列表，使用者不能新增、修改或使用其他 MCP server。系統路徑包括：

• macOS：/Library/Application Support/ClaudeCode/managed-mcp.json
• Linux / WSL：/etc/claude-code/managed-mcp.json
• Windows：C:\Program Files\ClaudeCode\managed-mcp.json

第二種是 managed settings 裡的 allowlist / denylist：

• allowedMcpServers
• deniedMcpServers

限制維度有三種：

• serverName：按 server 名稱。
• serverCommand：按 stdio server 的啟動命令和引數。
• serverUrl：按遠端 server URL，可用 wildcard。

如果組織只允許 managed MCP，可以用 managed-only 設定 allowManagedMcpServersOnly。

24. 一個安全的接入順序

新 MCP 不要一上來 project scope + allow all。按這個順序：

25. 常見故障排查

連線失敗：

• 執行 claude mcp get <name> 看配置。
• 會話內執行 /mcp 看連線狀態。
• HTTP / SSE 檢查 URL、認證、網路、OAuth。
• stdio 檢查 command、args、PATH、環境變數。
• Windows + npx 檢查是否需要 cmd /c。
• 增加 MCP_TIMEOUT 處理啟動慢的 server。

認證失敗：

• 在 /mcp 重新認證。
• 清除舊認證後重新登入。
• 檢查 OAuth callback port。
• 檢查 client ID / secret。
• 檢查 scope 是否被限制過小。
• 檢查 headersHelper 是否輸出合法 JSON。

工具不出現：

• 檢查 server 是否 connected。
• 檢查是否被同名 local scope 覆蓋。
• 檢查 plugin / connector 是否被隱藏。
• 檢查 managed allowlist / denylist。
• 檢查 Tool Search 下工具是否需要被搜尋觸發。

輸出太大：

• 優先讓 server 分頁和摘要。
• 對具體工具增加 server 側 result size annotation。
• 必要時調整 MAX_MCP_OUTPUT_TOKENS。

26. 自檢清單

學完這一章，你應該能完成這些判斷：

• 我能解釋 MCP 解決的是上下文搬運，不是越多工具越好。
• 我知道遠端優先 HTTP，SSE 是相容路徑，stdio 是本機程序。
• 我能判斷 MCP 應該放 local、project 還是 user scope。
• 我知道 local scope 會壓過同名 project scope。
• 我知道 .mcp.json 可以提交結構，但不能提交金鑰。
• 我知道 OAuth token、client secret、headersHelper 的安全邊界。
• 我知道如何用 permissions 精確限制 MCP 工具。
• 我知道 MCP 輸出過大會汙染上下文。
• 我知道 Tool Search 預設降低工具 schema 的上下文佔用。
• 我知道 plugin、Claude.ai connectors、managed MCP 都可能讓 MCP 出現在 /mcp 裡。

27. 術語速查

• MCP：Model Context Protocol，用來把外部工具、資料來源和 API 接入 Claude Code。
• MCP server：提供 tools、resources、prompts 或 channels 的外部服務。
• transport：Claude Code 連線 MCP server 的方式，包括 HTTP、SSE、stdio。
• local scope：只在當前專案載入，配置儲存在 ~/.claude.json。
• project scope：寫入專案根目錄 .mcp.json，可提交給團隊。
• user scope：跨專案可用，配置儲存在 ~/.claude.json。
• .mcp.json：專案級 MCP 配置檔案。
• /mcp：Claude Code 會話內檢視和認證 MCP server 的命令。
• headersHelper：動態生成 HTTP headers 的命令。
• MAX_MCP_OUTPUT_TOKENS：控制 MCP 工具輸出 token 上限的環境變數。
• Tool Search：延遲載入 MCP tool schema 的機制。
• managed-mcp.json：組織集中下發的 MCP server 配置檔案。
• allowedMcpServers：managed settings 中允許 MCP server 的策略欄位。
• deniedMcpServers：managed settings 中禁止 MCP server 的策略欄位。

官方來源

• Connect Claude Code to tools via MCP
• Configure permissions
• Claude Code settings
• Model Context Protocol