第十三节 外部工具服务接入
[!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」协议错误；现对未知工具做兜底处理并按需重连自愈，后端就绪后自动恢复，不再因此整体不可用。