工具执行与治理

MCP 工具调用的执行流程（建议与执行分离）、三级工具过滤规则，以及按密钥的工具会话与凭据生命周期管理

本页把 MCP 工具调用的"执行—过滤—会话"三件事合在一处：模型建议调用工具后如何受控执行、如何按三级规则约束哪些工具可用、以及按密钥的工具会话凭据如何随访问关系自动收敛。三者共同构成灵渠对工具调用的统一治理，与普通查询请求复用同一套额度、安全与计量口径。

工具执行经数据平面 /v1/*，工具会话管理经控制平面 /api/v1/mcp/*。下文示例中的 https://<平台入口地址> 请替换为你的平台实例统一入口地址。

1. 执行流程：建议与执行分离

当上游模型在响应中返回工具调用时，灵渠默认不自动执行它，而是把工具调用建议原样回给应用，由应用显式发起执行。这条"建议与执行分离"的设计，给应用留出了校验参数、按权限把关、必要时请用户确认的空间。

一次完整的工具调用按四步推进：

1.1 第一步：发起查询请求

应用以普通查询的形态发起请求，请求中可附带可用工具清单。模型若判断需要调用工具，会在响应中给出工具调用建议，而非自然语言答复：

{
  "id": "<响应标识>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "<工具调用标识>",
            "type": "function",
            "function": {
              "name": "business_search-fetch_record",
              "arguments": "{\"id\": \"<记录标识>\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

工具名采用"连接名 + 工具名"前缀（如 business_search-fetch_record），确保多个连接间工具唯一可辨。finish_reason 为 tool_calls 即表示这是一次工具调用建议，尚未执行。

1.2 第二步：应用研判

应用拿到建议后，按自身策略决定是否执行：校验参数是否合法、调用方是否有权限、敏感操作是否需用户确认。这一步完全由应用掌控，平台不越俎代庖。

1.3 第三步：显式发起执行

确认放行后，应用把工具调用对象原样提交给工具执行入口。平台在此环节让工具调用流经中间件管道——安全护栏先校验参数与权限，路由中间件把调用代理至对应工具服务器：

curl https://<平台入口地址>/v1/mcp/tool/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tsxt-************************" \
  -d '{
    "id": "<工具调用标识>",
    "type": "function",
    "function": {
      "name": "business_search-fetch_record",
      "arguments": "{\"id\": \"<记录标识>\"}"
    }
  }'

工具执行结果以可直接拼接进对话历史的形态返回：

{
  "role": "tool",
  "content": "<工具返回的结构化结果>",
  "tool_call_id": "<工具调用标识>"
}

工具执行入口的鉴权与数据平面查询入口一致（Authorization: Bearer <API 密钥>），逐次鉴权并归属到对应子账户。返回结构带有正确的 role（tool）与对应的 tool_call_id，可直接追加到对话历史，无需二次加工。

1.4 第四步：续接对话

应用把"原始问题 + 模型的工具调用建议 + 工具执行结果"组装为完整对话历史，再发起一次查询，模型据此生成最终答复。一次请求中模型可能建议多个工具调用，应用可按需串行或并行执行，结果各自拼回历史。

1.5 执行失败处置

工具执行可能因多种原因失败，平台以结构化错误返回，便于应用本地化处理：

情形	错误语义
工具执行超时	超出工具调用超时上限
工具不存在	工具名拼写错误，或所属连接已中断
工具被过滤	该工具不在当前请求的可用范围内（见 §2）

{
  "error": {
    "code": "tool_not_allowed",
    "message": "工具 business_search-delete_record 不在本次请求的可用范围内",
    "request_id": "<请求追踪标识>"
  }
}

2. 三级工具过滤

灵渠以三级过滤约束"哪些工具可用"，三级逐层收窄，一个工具须通过全部适用层级方可对模型可见、可执行：

级别	过滤面	说明
第一级 · 连接级	`tools_to_execute`	每个 MCP 连接的工具准入基线（默认拒绝），见接入 MCP 服务器 §3
第二级 · 请求级	请求头声明	单次请求临时收窄到指定连接 / 指定工具
第三级 · 密钥级	子账户配置	按 API 密钥（子账户）配置可访问工具，优先级最高

三级过滤以交集叠加：连接级是基线，请求级在其上进一步收窄，密钥级在配置存在时覆盖请求级声明。

2.1 请求级过滤

在单次请求头中临时收窄可用工具，不改动连接配置：

# 仅包含指定连接的工具
curl https://<平台入口地址>/v1/chat/completions \
  -H "Authorization: Bearer tsxt-************************" \
  -H "x-mcp-include-clients: business_search,knowledge_base" \
  -d '{ "model": "<模型中性名>", "messages": [ ... ] }'

# 仅包含指定工具（连接名-工具名；支持 连接名-* 通配该连接全部工具）
curl https://<平台入口地址>/v1/chat/completions \
  -H "Authorization: Bearer tsxt-************************" \
  -H "x-mcp-include-tools: business_search-search,knowledge_base-*" \
  -d '{ "model": "<模型中性名>", "messages": [ ... ] }'

请求级过滤头取空值即屏蔽全部工具（默认拒绝），可用于显式关闭某次请求的工具能力。通配符仅支持 连接名-*（该连接全部工具）与独立的 *（全部连接），不支持 连接名-前缀* 之类的局部前缀匹配。

2.2 密钥级过滤

为某个 API 密钥（子账户）配置可访问的工具集，按业务线 / 角色实施最小权限：

curl https://<平台入口地址>/api/v1/mcp/keys/<子账户标识>/tools \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "mcp_configs": [
      { "client": "knowledge_base", "tools_to_execute": ["search", "get_article"] },
      { "client": "ticketing", "tools_to_execute": ["*"] }
    ]
  }'

密钥级过滤的取值语义与连接级一致（["*"] 全部 / [] 无 / 指定列表）；未在密钥配置中列出的连接，其工具一律被屏蔽（默认拒绝）。当密钥配有 MCP 工具配置时，它覆盖请求级过滤头——即便请求头声明了某工具，只要密钥未授予，仍不可用。

2.3 过滤组合示例

配置	结果
连接级允许 `read`/`write`/`delete`；密钥级限定 `read`；请求头声明 `write`	仅 `read` 可用（密钥级覆盖请求级）
连接级允许 `read`/`write`；无密钥级配置；请求头声明 `write`	仅 `write` 可用（请求级生效）
连接级允许 `read`/`write`；密钥级与请求级均未声明	取连接级基线 `read`/`write`

常见用法：只读访问（仅开放 search/view/get_* 一类工具）、按环境隔离（开发密钥放开、生产密钥收窄）、按角色分级（查看 / 编辑 / 管理三档密钥配不同工具集）。

3. 按密钥的工具会话与凭据生命周期

当某些工具服务器要求逐调用方独立凭据（如按使用者各自授权才能访问的业务系统）时，灵渠为每个调用方身份维护一份独立的工具会话凭据。「MCP 会话」页按密钥（子账户）粒度集中管理这些凭据。

3.1 会话凭据的状态

每条会话凭据处于以下状态之一：

状态	含义	如何恢复
`active`	凭据有效，平台在每次调用时自动附带	—
`needs_reauth`	上游凭据已失效（刷新失败或被使用者在源端撤销）	重新授权并完成上游流程
`needs_update`	管理员调整了该工具服务器要求的凭据字段，现有凭据缺少新增字段	重新提交凭据值
`orphaned`	该身份已失去对此工具服务器的访问权（密钥被移出允许清单等），凭据本身仍有效	由管理员侧恢复访问权，下次对账自动转回 `active`
`pending`	授权 / 提交链接已下发，使用者尚未完成	完成链接指向的授权或提交

needs_reauth/needs_update 与 orphaned 的本质区别。 前两者是调用方侧问题——补一份新凭据即可修复（重新授权或重新提交）。orphaned 是访问控制问题——凭据本身没坏，缺的是"该身份经灵渠使用此工具服务器的权利"；重新授权只会产生重复凭据或在下次对账时再次回到孤立态，真正的修复在管理员侧（把密钥重新加回允许清单等）。因此孤立态凭据的「重新授权」操作在界面上隐藏，避免无效动作。

3.2 凭据随访问关系自动收敛

平台让会话凭据与"密钥 ↔ 工具服务器"的允许关系保持自动同步：当某身份的有效允许范围变化时，受影响的凭据自动改写状态，无需人工逐条处理。

管理动作	对现有凭据的影响
把某工具服务器从某密钥的允许清单移除	该「密钥 × 工具服务器」凭据转为 `orphaned`
把某工具服务器重新加回密钥允许清单	对应孤立凭据转回 `active`
删除某密钥	该密钥下全部凭据被清除
删除某工具服务器连接	该连接下全部身份的凭据与待完成流程一并清除

"有效允许范围"取"逐密钥显式配置 ∪ 全局放开的工具服务器"——与运行期工具可用性判定同一套谓词。凭据状态的收敛与工具过滤的判定口径一致，二者始终对得上。

3.3 凭据管理操作

「MCP 会话」页按凭据当前状态提供对应操作，不展示无效动作：

操作	适用状态	效果
重新授权	`needs_reauth`	对同一工具服务器与身份发起新授权流程，完成后原位替换失效凭据，状态转 `active`，身份不变
编辑凭据值	`active` / `needs_update`	发起新的凭据提交流程（表单预填已存字段名，不回显值），提交后原位替换
完成授权	`pending`	把使用者送回授权链接，完成未竟流程
撤销	凭据行与陈旧待完成流程	删除该凭据行；对待完成授权流程，先移除流程行以规避回调竞态

待完成流程行有短时有效期（约 15 分钟），逾期由平台清理，不残留为失败行。会话凭据的状态机与界面动作随状态自适应——孤立态与待重新授权态互斥于"无济于事的动作"，平台不暴露无操作意义的选项。