xinmi/docs/zh/mcp-approval.md

MCP 工具人工审核（危险调用）

对应需求：智能体调用 MCP 工具前可中断，待人工确认后再执行（GitHub #1173）。

行为说明

1. 在 设置 → MCP 中连接测试成功后，在工具列表上打开 「需人工审核」 开关，即可为该工具打标。
2. Agent 运行时若即将调用已打标的工具，会推送 tool_approval_required 事件，对话界面展示审批卡片（可编辑 JSON 参数）。
3. 用户 通过 或 拒绝 后，后端恢复执行；拒绝时工具返回错误信息给模型，不会调用远端 MCP。
4. 若超时未处理（默认 10 分钟，可通过配置 agent.tool_approval_timeout_seconds 调整），视为拒绝。

配置示例

任选一种：

1. config.yaml

agent:
  tool_approval_timeout_seconds: 600  # 可选，默认 600（秒）

2. 环境变量（优先级高于 yaml）

# 支持纯秒数或 Go duration（30s / 5m / 1h）
WEKNORA_AGENT_TOOL_APPROVAL_TIMEOUT=600

API

• GET /api/v1/mcp-services/:id/tool-approvals — 列出已保存的审核配置
• PUT /api/v1/mcp-services/:id/tool-approvals/:tool_name — 设置某工具是否需审核（{"require_approval": true}）
• POST /api/v1/agent/tool-approvals/:pending_id — 在审批卡片中提交结果
  • body: {"decision":"approve"|"reject","modified_args":{...}可选,"reason":"..."可选}

部署与限制

• 审批等待状态保存在进程内存 中：pending_id 仅对当前实例有效；进程重启后进行中的等待会失败（表现为拒绝/取消）。
• 多副本部署：当配置了 REDIS_ADDR 时，Resolve 会通过 Redis Pub/Sub（频道 weknora:mcp_approval:resolve）跨实例转发，因此 SSE 与提交审批的 HTTP 请求落到不同实例也能正确唤醒等待者；未配置 Redis 时退化为单机模式，需要使用会话粘滞（sticky session）。
• 审批等待不会被工具默认 60s 超时取消：审批阶段使用 round 级别的 ctx（不带 defaultToolExecTimeout），仅受 agent.tool_approval_timeout_seconds 与请求级取消控制。
• 安全边界：审核通过后的参数仍由当前登录空间提交；请仅在可信环境下授予「通过」权限。