接入 MCP 服务器

把外部 MCP 工具服务器接入灵渠——三类连接方式、连接配置字段、工具准入范围、连接状态机与健康探测，以及连通性韧性与重试策略

灵渠作为 MCP 客户端，可接入任意符合 MCP 协议的外部工具服务器。每一个接入的工具服务器，在平台内称为一个 MCP 连接。本页讲清：连接方式有哪几类、连接配置写什么、如何约束工具准入范围、连接处于哪些状态、平台如何探测健康并在故障时自愈。

接入与管理 MCP 连接的接口集中在控制平面 /api/v1/mcp/*，仅运营控制台可见。下文示例中的 https://<平台入口地址> 请替换为你的平台实例统一入口地址。

1. 三类连接方式

不同的工具服务器以不同方式暴露其能力。灵渠按工具服务器的部署形态，提供三类连接方式：

连接方式	适用场景	说明
本地进程	本机工具、命令行工具、脚本	平台拉起一个本地子进程，经标准输入 / 输出与之通信
HTTP	远程服务、微服务、托管工具	平台向工具服务器的 HTTP 端点发起请求
持久流	实时数据、推送式工具	平台与工具服务器建立持久连接，工具服务器可主动推送事件

连接方式与认证方式相互独立：本地进程从父进程继承运行环境、无逐次调用认证；HTTP 与持久流连接可叠加请求头凭据等认证形态。同一个工具服务器，连接方式与认证方式分别配置、互不绑定。

2. 连接配置

接入一个工具服务器，提交其连接配置。下面以 HTTP 连接为例：

curl https://<平台入口地址>/api/v1/mcp/clients \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "name": "business_search",
    "connection_type": "http",
    "endpoint": "https://<工具服务器入口>/mcp",
    "auth_type": "none",
    "tools_to_execute": ["*"],
    "ping_available": true
  }'

各字段含义：

字段	含义
`name`	连接唯一标识；仅限 ASCII，不含空格与连字符，不以数字开头，全局唯一
`connection_type`	连接方式：`local`（本地进程）/ `http` / `stream`（持久流）
`endpoint`	工具服务器入口地址（HTTP / 持久流连接）；本地进程连接改以启动参数声明
`auth_type`	认证方式：`none` / `headers`（请求头凭据）/ 按需扩展的其他形态
`tools_to_execute`	该连接对外开放的工具准入范围（见 §3）
`ping_available`	工具服务器是否支持轻量探活，影响健康探测方式（见 §5）

敏感配置值（如带凭据的入口地址）以环境变量占位引用，平台在连接时解析；接口返回与控制台展示中一律脱敏，不回显明文。配置中引用的环境变量在启动时校验齐备。

接入后做一次工具发现，确认连接已建立、工具清单已拉取：

curl https://<平台入口地址>/api/v1/mcp/clients/<连接标识>/tools \
  -H "Cookie: <控制台会话凭证>"

响应给出该连接发现到的工具清单及其描述与参数结构：

{
  "client": "business_search",
  "state": "connected",
  "tools": [
    { "name": "search", "description": "<工具用途描述>" },
    { "name": "fetch_record", "description": "<工具用途描述>" }
  ]
}

3. 工具准入范围

tools_to_execute 是每个连接的工具准入基线，决定该连接的哪些工具可被平台代理调用。采用"默认拒绝"语义：

取值	行为
`["*"]`	该连接的全部工具均可用
`[]` 或省略	不开放任何工具（默认拒绝）
`["tool_a", "tool_b"]`	仅开放指定工具

工具准入范围是工具过滤的第一级（连接级）。在此基线之上，还有请求级与密钥级两级过滤逐层收窄，详见工具执行与治理 · 工具过滤。

工具对外一律以"连接名 + 工具名"的前缀形式标识（如 business_search-search），确保多个连接的同名工具不冲突。前缀命名是跨连接工具唯一性的基础。

4. 连接状态机

每个 MCP 连接在生命周期中处于以下状态之一：

状态	含义
`connecting`	正在建立连接
`connected`	已连接，工具可用
`disconnected`	连接中断，但可重连恢复
`error`	配置或连接失败，需修正后重试

运行期可对连接做以下管理操作：

# 手动重连一个已中断的连接
curl https://<平台入口地址>/api/v1/mcp/clients/<连接标识>/reconnect \
  -X POST \
  -H "Cookie: <控制台会话凭证>"

# 调整连接配置（如收窄工具准入范围）
curl https://<平台入口地址>/api/v1/mcp/clients/<连接标识> \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{ "tools_to_execute": ["search"] }'

# 临时停用一个连接（保留配置，工具对调用方不可见）
curl https://<平台入口地址>/api/v1/mcp/clients/<连接标识> \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{ "disabled": true }'

停用与启用是编排面操作：停用后平台关闭该连接、停止健康探测，连接记录保留、工具对调用方不可见，便于灰度与回退而无需删除。停用状态跨重启保留——重启后连接载入内存但不建立，直到显式启用。

5. 健康探测

平台周期性探测每个已连接工具服务器的健康状态，及时发现中断并自愈。探测方式有两种：

探测方式	适用情形	开销
轻量探活（默认）	工具服务器支持探活协议	最小
工具列表探测	工具服务器不支持探活，或需更重的检查	较高

探测方式由连接的 ping_available 字段决定，可在「MCP 网关」页随时切换，切换即时生效、无需重连。健康探测的关键参数（探测周期、单次超时、连续失败阈值）按平台默认设定，达到连续失败阈值后连接转入 disconnected，该连接的工具随即对调用方不可用。

6. 连通性韧性与重试

为吸收瞬时网络抖动与短时不可用，平台对关键操作采用指数退避重试——首次失败后按递增等待时间重试，等待上限封顶，避免对工具服务器持续冲击。

平台对以下操作施加重试：建立初始连接、启动传输、初始化协议、工具发现、健康探测失败后的自动重连。

平台区分两类错误，决定是否重试：

错误类别	处置
瞬时错误	连接超时 / 被拒、网络不可达、域名解析失败、`5xx`、`429`、I/O 中断等——重试
永久错误	认证失败（`401`/`403`）、授权被拒、配置无效、命令 / 入口不存在、`400`/`405`/`422` 等——立即失败、不重试

当连接连续探活失败超过阈值时，平台在后台自动发起重连，重连同样走指数退避；重连成功后健康探测恢复、工具自动复用，无需人工介入。手动重连可随时触发，作为后台自愈之外的兜底手段。

7. 命名约定

连接名有以下约束（违反者在创建时被拒绝）：

仅含 ASCII 字符
不含连字符（-）或空格
不以数字开头
全局唯一

合法示例：filesystem、business_search、knowledgeBase、tool123。非法示例：my-tools、web search、123tools。