第十三節 外部工具服務接入
[!ref] 詳解見使用者手冊「外部工具服務接入」節。
13.1 服務條目欄位
每個外部服務條目包含：
| 欄位 | 類型 | 說明 |
|---|---|---|
name |
string | 名字（也作為工具前綴，例如 notion.*） |
protocol |
enum | http（Streamable HTTP，手動新增時的預設）/ sse（舊式）/ stdio。填錯時連線會自動協商回退：若伺服器端可達但握手被拒（如 405 / Bad Request），自動改試另一種 HTTP 傳輸並把實際生效的方式寫回配置；連不上（拒絕 / 超時 / EOF）則不回退 |
lazy_load |
bool | 是否延遲載入該服務的工具。缺省跟隨全域「工具分類延遲載入」；顯式關閉則該服務工具常駐。落盤 mcp_lazy_load（按後端名） |
endpoint |
string | HTTP / SSE 通道的 URL；stdio 通道不用 |
command |
string | stdio 通道要啟動的命令列（如 npx -y @some/mcp-server） |
args |
array | stdio 通道的命令列參數 |
env |
map | stdio 子程序的環境變數（憑證、token 等） |
credential |
string | HTTP / SSE 的 Bearer Token 或 API Key |
oauth |
object | OAuth 2.1 + PKCE 配置（authorizationEndpoint / tokenEndpoint / clientId / scope / clientSecret?）；endpoint 可通過 .well-known 自動發現 |
enabled |
bool | 是否啟用 |
timeout_ms |
int | 請求超時 |
retry |
object | max=3, base=500ms, jitter=0.3 |
憑證存儲（VAULT）：
credential/env/oauth.refresh_token與續期元資料不入主配置文件、不入記錄檔，統一進國密加密的憑證函式庫（SM4-GCM + HKDF-SM3，machineID 綁定）；現有明文憑證下次使用時被動遷移。
13.1.1 OAuth 流程欄位
| 欄位 | 說明 |
|---|---|
authorizationEndpoint |
OAuth 授權端點 |
tokenEndpoint |
OAuth token 端點 |
clientId |
用戶端 ID |
clientSecret |
可選；缺省即 public client（僅相依 PKCE） |
scope |
申請的權限範圍 |
redirectUri |
本機回環：http://127.0.0.1:<port>/cb |
pkce.codeVerifier / pkce.codeChallenge |
S256 |
accessTokenExpiresAt |
啟動 / 後台到期前用 refresh_token 自動換新 |
13.1.2 健康看板欄位
MCP 配置 → 健康看板 來源是 zMCP gateway 的 /admin/metrics 環形緩衝：
| 欄位 | 說明 |
|---|---|
backend |
MCP 後端名 |
calls |
呼叫次數（視窗內） |
failRate |
失敗率 |
p50Ms / p95Ms |
回應耗時分位（毫秒） |
lastError / lastErrorAt |
最近一次失敗錯誤訊息 + 時間 |
13.2 工具命名規則
| 來源 | 命名 |
|---|---|
| 內置工具 | 不加前綴（例如 read, git.status） |
| 安全分析 | sec.* 前綴 |
| 外部服務 | <服務 name>.* 前綴（例如 notion.search） |
| 通訊出站 | channels.* 前綴 |
| 技能呼叫 | skill.invoke |
13.3 錯誤抽屜條目
| 欄位 | 說明 |
|---|---|
| 時間 | 觸發時間 |
| 工具 | 工具名 |
| 狀態碼 / 錯誤類 | HTTP 狀態 / 例外類 |
| 摘要 | 單行簡述 |
| 詳情 | 伺服器端原始傳回（最多 4 KB） |
| 重試次數 | 自動重試已嘗試次數 |
後端缺席兜底：某後端一時缺席 / 未就緒時，
tools/call過去會傳回「unknown tool」協議錯誤；現對未知工具做兜底處理並按需重新連線自愈，後端就緒後自動復原，不再因此整體不可用。