第十二節 外部工具服務接入

智慧體管理器 →「配置工具」面板支持連線任意標準協議的工具服務（例如 Notion、內部 API、私有知識庫）。

注意與 設置 → 提供商 區分：後者配置的是大模型供應商，與這裡的外部工具服務是兩回事。

12.1 新增一個外部服務

1. 輸入區模式滑塊旁的齒輪（智慧體管理器）→「配置工具」→ 新增服務。
2. 選擇通道：
   • Streamable HTTP（預設）/ SSE：填寫接入地址（URL）+ 憑證 — 適合雲端服務。現代 MCP 服務多用前者；兩者填錯時連線會自動協商回退，不必糾結選哪個。
   • stdio（本機程序）：填寫要啟動的命令列（如 npx -y @some/mcp-server） + 環境變數 — 直接在本機起一個子程序作為 MCP server，不必再要求對方提供 HTTP 地址，方便接 npm / pip 上現成的 MCP 實現。
3. 填寫：
   • 名稱：例如 notion。
   • 憑證：從對方平台獲取的存取令牌（HTTP / SSE 通道）；或子程序要的環境變數（stdio 通道）。
4. 啟用。

介面已重做：新增表單、後端詳情、健康看板、安裝確認彈窗整體改為更克制的資料表質感 — 技術訊息用等寬字型披露、發絲級邊框、狀態圓點，整體更清爽專業。

12.1.1 遠端 MCP 的 OAuth 登入

對於需要登入的遠端 MCP 服務，新增流程內嵌OAuth 2.1 + PKCE 授權：

• 建的時候就能登入：授權入口放在「新增 MCP」流程裡（不再藏在建好之後的詳情），點「OAuth 授權」會跳瀏覽器走標準授權碼 + PKCE 流程，本機回環回呼收到 token 後自動落地。
• 自動續期：access token 在到期前用 refresh_token 在啟動時 / 後台自動換新，授權成功後介面即時反饋並重新整理狀態，不必反復手動重新連線。
• public client（無 client_secret）和帶 client_secret 的 confidential client 都支持；endpoint 可通過 .well-known 自動發現，也可手填。

12.1.2 安裝確認彈窗：權限與相依一目了然

裝一個 MCP 後端 / 外掛前，安裝確認彈窗會把以下內容披露給你：

• 要披露的工具權限：會啟用哪些工具、各自的允許 / 詢問 / 停用預設值。
• 聲明的工作模式：permissionMode / allowed-tools 等限制（來自外掛 manifest）。
• 對本機的相依：如需要 node / python / git 等本機命令、操作系統、平台架構限制。
• 遠端工作區下額外給出輕量提示，避免裝上對方機器沒有的相依。

12.2 工具命名空間

外部服務暴露的工具會被自動加上前綴（例如 notion.search、notion.create_page），在工具列表裡獨立成組，互不衝突。

12.3 實時生效

新連上的外部服務下個回合即對助手可見，不必重開對話。這一特性讓你可以在對話過程中隨時增配服務。

開啟工具分類延遲載入（預設開啟，見 §9.2.1）時：工作階段進行中新連上的服務會直接可用，不用等助手主動載入；新開工作階段後才回到"用到時才載入"。

12.3.1 單獨設置某個服務是否延遲載入

在智慧體管理器 →「配置工具」Tab 裡，每個外部工具服務都有一個「延遲載入該服務的工具」開關：

• 開啟（預設）：該服務的工具不常駐，助手用到時才載入。
• 關閉：該服務的工具始終可用 —— 適合你高頻使用的服務。

若全域的「工具分類延遲載入」已關閉，所有工具本就常駐，此開關暫不起作用，介面會直接說明。

助手在系統提示詞裡會被告知你接入了哪些外部服務，並附上每個服務的工具數量與幾個示例工具名，因此即使工具暫未載入，它也知道該找誰。

12.4 例外處理

• 斷連重試：後端斷開會自動指數退避重試。
• 錯誤抽屜：錯誤訊息會拼接伺服器端原始傳回，便於定位是憑證過期、網路不通還是伺服器端故障。
• 就緒探測：連線建立後 AVL Code 會先做一次 ping，確保對端真正可服務再登記到工具列表。
• 後端一時缺席不再整體失效：某個後端暫時缺席 / 未就緒時，工具呼叫過去會傳回「unknown tool」協議錯誤把工具整體拖垮；現在對未知工具做兜底處理，並在需要時按需重新連線、自愈，等後端就緒後自動復原可用。

12.4.1 MCP 健康看板

MCP 配置 → 健康看板 按後端展示每個 MCP 的呼叫次數 / 失敗率 / 回應耗時（P50 / P95），一眼看出哪個服務慢、哪個在報錯；某後端最近一次失敗的錯誤訊息也會在該行展開，便於定位。

資料來自 MCP 閘道的環形緩衝統計（最近一段時間視窗），實時重新整理。

12.5 安全 — 憑證國密加密存儲（VAULT）

• MCP 後端的驗證令牌（HTTP Bearer AuthToken）和 stdio 子程序的環境變數整張 map 不再明文落盤，統一存進國密加密的憑證函式庫（SM4-GCM + HKDF-SM3、與本機 machineID 綁定，跨機即失效）。
• OAuth refresh_token + 續期元資料同樣進 VAULT，絕不入 zmcp.yaml 主配置、絕不入記錄檔。
• 現有配置自動遷移：舊的明文憑證下次使用時被動遷移到 VAULT 加密存儲，無需手工乾預；machineID 不可達 / 變化時優雅降級（復原提示重輸），不會神秘失敗。
• 冷啟動 401 修正：之前帶驗證的 HTTP MCP 服務在電腦 / 應用冷啟動後第一次呼叫會報 401——根因是 zMCP 閘道子程序的歸檔 key 錯誤使用了每次啟動都變的臨時 127.0.0.1:<連接埠> URL，而 App 父程序是按穩定的 workspaceID 落函式庫，導致 Load 恆 miss、復原到「現有被動遷移已清空」的明文（即空字串），最終發了個空 Bearer 頭被後端拒絕。本版改為讀寫兩端都用穩定的 workspaceID 當 key，冷啟動後正常帶憑證連上、無需手動重配。
• 憑證以加密形式存儲在本機，不會隨同對話內容上傳到模型。
• 第三方 stdio 服務拿不到閘道管理金鑰：以標準輸入輸出方式啟動的第三方 MCP 服務不再繼承工具閘道的管理金鑰，第三方程序不會持有本不該擁有的閘道管理權限。
• 可在智慧體管理器 →「配置工具」中針對每個外部服務獨立設置工具權限政策。