服務與 MCP | Claude Code 初學者教學

90 秒總覽

服務層是 Claude Code 與外部世界之間的邊界。所有外部依賴（API 呼叫、MCP 伺服器、檔案系統服務等）都透過服務層封裝，上層流程不直接接觸外部實作。MCP（Model Context Protocol）整合後的能力不是單一清單，而是分開維護 tools / commands / resources，並受 server policy 與 tool deny rules 共同影響。

執行路徑（主骨架）

await getMcpToolsCommandsAndResources(config, context, onUpdate)

// onUpdate 逐台回報
setMcp({
  tools: mapAndFilterTools(...),
  commands: mapCommands(...),
  resources: mapResources(...),
})

const visibleTools = filterToolsByDenyRules(tools, permissionContext)

重點：此流程是「分組並發 + 逐台回報」，不是一次拿到完整聚合物件；另外 policy 與 deny rules 分屬不同層次。

1. 讀取 MCP 設定，取得已註冊的伺服器清單
2. 以 local/remote 分組並發連線
3. 每台連線完成後逐台回報 tools/commands/resources
4. 套用 server policy 與工具 deny 規則
5. 分別更新 mcp.tools / mcp.commands / mcp.resources，供回合引擎使用

flowchart LR
  A[設定載入] --> B[MCP 伺服器探索]
  B --> C[分組並發連線]
  C --> D[逐台拉取工具+資源+命令]
  D --> E[server policy + deny rules]
  E --> F[分別更新 tools/commands/resources]
  F --> G[提供給回合引擎]

路徑判讀重點

設定載入階段決定哪些 MCP 伺服器會被連線，未列入設定的伺服器不會被探索。
連線是分組並發，單一伺服器失敗不會阻斷其他伺服器整合。
MCP 資源工具（list/read resource）是條件式加入，不是永遠常駐。
tools、commands、resources 在狀態中分開維護；不是全部合成同一工具清單。

關鍵決策（為什麼這樣設計）

決策 1：外部依賴必須經過服務層

原因：所有外部呼叫（API、MCP 伺服器、檔案系統）統一經過服務層封裝，讓上層邏輯只依賴抽象介面。這使得核心流程可以獨立測試與維護，不受外部實作變動影響。

代價：新增外部依賴時必須先在服務層建立對應的封裝，無法直接從上層呼叫，初期開發速度略慢。

決策 2：MCP 採用標準協議而非自訂介面

原因：使用 Model Context Protocol 標準協議讓第三方伺服器能以統一方式提供工具、資源與命令，大幅降低整合成本。任何符合 MCP 規範的伺服器都能即插即用，無需為每個外部來源撰寫客製化適配器。

代價：標準協議的彈性受限於規範定義，遇到規範未涵蓋的需求時需等待上游演進或在服務層額外擴充。

決策 3：政策過濾在整合時執行而非使用時

原因：在 MCP 能力整合進主清單時就執行政策過濾，能及早排除不合規工具。這樣回合引擎拿到的永遠是已通過審查的清單，不需在每次工具呼叫時重複檢查，降低運行時開銷與遺漏風險。

代價：政策變更後需重新觸發整合流程才能生效，無法在執行中即時動態調整可用工具集。

替代方案與取捨

替代方案比較表
方案	優點	缺點	為何未採用/何時可採用
直接呼叫外部 API（不經服務層）	開發速度快，呼叫路徑短	上層流程與外部實作強耦合，難以測試與替換	極簡原型可行；正式系統規模下維護成本過高
自訂擴充協議（取代 MCP 標準協議）	可完全按需設計，彈性最大	每個外部來源需客製適配器，整合成本隨來源數量線性增長	特殊需求超出 MCP 規範時可作為補充；通用場景應優先使用標準協議
使用時過濾（每次工具呼叫時檢查政策）	政策變更可即時生效，無需重新整合	每次呼叫都有額外檢查開銷，且容易因遺漏檢查點而產生安全漏洞	需要即時動態調整工具集時可考慮；目前整合時過濾已足夠且更安全

失敗路徑與防護

Failure 1：MCP 伺服器連線失敗

症狀：目標 MCP 伺服器無法連線（網路不通、伺服器未啟動、認證失敗），導致該伺服器提供的工具與資源全部缺失。

防護：連線階段設定逾時機制與重試策略；單一伺服器失敗不阻斷整體流程，系統以降級模式繼續運作並記錄警告，讓使用者知道哪些能力暫時不可用。

Failure 2：遠端工具 schema 不合規

症狀：tools/list 回傳結構不符 schema，該 server 本次工具清單可能整包失敗（回傳空陣列）。

防護：把 schema 失敗視為 server 級事件寫入日誌，並在 UI 明確標示該 server 當前工具不可用，避免誤判為單一工具故障。

Failure 3：政策過濾誤擋合法工具

症狀：server policy 或 deny rules 設定過嚴，導致預期工具未進入最終可見集合。

防護：記錄每個被排除工具/伺服器的規則命中原因；避免在文件中假設一定有 dry-run 機制，改以可觀測日誌與比對清單為主。

實作驗證（你改完要怎麼確認）

確認 MCP 伺服器連線成功：啟動後日誌應顯示各伺服器的連線狀態，無非預期的連線錯誤。
確認工具清單正確合併：回合引擎拿到的工具清單應包含內建工具與所有已連線 MCP 伺服器提供的合規工具。
確認政策過濾正確執行：被政策排除的工具不應出現在最終清單中，且過濾日誌應記錄排除原因。
確認伺服器斷線時的降級行為：模擬某一 MCP 伺服器斷線，系統應繼續運作且正確回報哪些能力暫時不可用。

前兩項是最低可接受驗證集，後兩項針對過濾與容錯做回歸測試。