MCP 安全与审批

MCP 是平台最接近外部系统副作用的一层，因此安全与审批规则必须明确。

安全重点

凭据必须通过平台受控存储，而不是散落在提示词或前端配置中
工具能力要按 Agent 挂载与 allowlist 收敛
direct response 与 URL import 模式要显式评估返回面暴露范围
审计日志必须能按 session、Agent 和 server 回放

当前安全边界

凭据边界

MCP credential 不是普通配置项，而是独立持久化对象。正确路径是：

控制面写入 credential record
mcp_secret_manager 负责加载和注入 secret payload
运行时只消费解析后的 secret，不把密钥散落到 Agent prompt

这意味着 secret 轮换要走 credential 体系，不要改 prompt 或 definition。

挂载边界

一个 MCP server 是否能被某个 Agent 用，不取决于“系统里有没有这个 server”，而取决于：

Agent 是否挂载了该 server
挂载是否启用
mount allowlist 是否允许当前 tool
mount capability gate 是否放行

所以“注册了 server 但线上 Agent 调不到”通常是挂载或 gate 问题，不是 transport 问题。

响应边界

MCP 调用结果不一定都会回到模型总结链路。

当前系统已经支持：

quick match
intent gate
direct response
passthrough

这几层都可能改变用户最终看到的返回面，因此安全审查不能只盯 tool arguments，还要盯响应渲染规则。

Approval 现在是怎么工作的

1. 识别需要审批的工具

orchestrator 在 MCP stage 内会通过 runtime checkpoint service 判断某个 tool 是否要求人工审批。

2. 生成 awaiting checkpoint

如果需要审批，会创建：

MCPApprovalCheckpointState
RuntimeApprovalRequest
status 为 awaiting_approval 的 checkpoint record

同时把“等待审批”写入当前 turn 的 context，而不是静默失败。

3. 人工 release 后恢复执行

当 operator release 对应会话后，运行时会通过 _resume_pending_mcp_approval_checkpoint() 恢复原调用，并把 checkpoint 更新为：

completed
或 failed

也就是说，approval 不是“另起一条人工流程”，而是对原 MCP 调用的受控暂停与恢复。

典型风险点

direct response 过宽

如果 direct response 规则把过多字段直接暴露给最终用户，风险比“模型总结后再输出”更高。

需要重点检查：

selected fields
output mode
fallback to raw JSON 的可能性

capability 别名和 allowlist 不一致

系统支持 capability 级匹配，不只是字面 tool name 匹配。

所以审查 allowlist 时，不能只看一个具体工具名，还要看 capability alias 是否也被放开。

URL import mode 误把外部 HTTP 能力当普通只读查询

http_sse 和 URL import 可以很方便，但也最容易把外部副作用接口包装成“看起来像查询”的工具。

安全评估时必须单独确认：

endpoint 是否只读
response 是否包含敏感字段
timeout / retry 是否足够收敛

排查顺序

工具为什么被阻断

先看：

mount allowlist
capability gate
intent gate
approval-required 规则

调用执行了，但用户侧结果不对

先看：

direct response / passthrough 是否接管了输出
preview 渲染是否已经 fallback 到 raw JSON
审计里的 request / response payload 是否符合预期

为什么会话一直停在等待状态

先看：

是否存在 awaiting_approval checkpoint
operator 是否真的 release 了对应 session
checkpoint 恢复后是否在调用阶段失败

关键代码入口

路径	作用
`ai_service/services/mcp_secret_manager.py`	secret 加载与注入
`ai_service/services/mcp_policy.py`	allowlist、调用预算、timeout
`ai_service/orchestrator/checkpoint_state.py`	MCP 审批 checkpoint 状态
`ai_service/orchestrator/graph.py`	审批拦截、checkpoint 创建与恢复
`ai_service/api/routers/mcp.py`	credential、mount、preview、health check 控制面入口
`ai_service/api/routers/core.py`, `ai_service/conversations/interfaces/http/router.py`	runtime checkpoint 触发面与会话 release API 面

适合放在哪

调用策略与审批语义属于系统文档
具体配置字段和接口参数属于参考