跳转至

MCP 运维

这页讲的是“怎么把 MCP 这条能力链维护在可连接、可治理、可审计的状态”，而不是只列几个接口。

标准操作顺序

  1. 注册 MCP server
  2. 绑定或轮换 credential
  3. 用 health check / test call 验证 tools/list 或 tools/call
  4. 挂载到 Agent，并设置 allowlist、timeout、budget、tool capability
  5. 预览 direct response 行为
  6. 在真实对话中验证常规工具链路或 passthrough 结果

关键入口

  • Studio 的 MCP server 页面
  • Studio 的 Agent Detail 页面
  • POST /mcp-servers/{mcp_server_id}/health-check
  • POST /mcp-servers/{mcp_server_id}/test-call
  • POST /agents/{agent_id}/mcp-response-preview

Runbook 1: 新增一个 MCP server

步骤

  1. 创建 MCP server registry 记录
  2. 选择 transport type：stdio 或 http_sse
  3. 填写 connection config
  4. 如果需要凭据，定义 credential schema 并绑定 credential
  5. 跑 health check
  6. 跑 test call

成功标志

  • server status 为 active
  • tools/list 能返回工具
  • 无需进入真实对话就能先跑通 test call

Runbook 2: 绑定或轮换 credential

关键点

  • credential 是单独对象，不直接和 server 配置混在一起
  • credential scope 影响复用边界
  • 轮换后需要重新验证 mount 是否仍可用

先看哪里

  • MCP credential 页面
  • mcp_credentials 相关记录
  • mcp_secret_manager.py

Runbook 3: 挂载到 Agent

当前一个 agent mount 至少决定这些运行参数：

  • allowed_tools
  • tool_capability
  • timeout_ms
  • max_calls_per_turn
  • priority

这意味着“挂载成功”不等于“行为正确”，因为策略层还没验证。

验证顺序

  1. mount 是否 active
  2. priority 是否符合预期
  3. allowlist 是否过严
  4. timeout 是否太短
  5. max_calls_per_turn 是否会在多工具场景触顶

Runbook 4: 验证 direct response / passthrough

当前 MCP 运维不能只验证工具能不能跑通，还要验证“工具结果如何回到用户”。

关键能力

  • quick match
  • intent gate
  • field catalog
  • direct response preview
  • passthrough render

推荐动作

  1. 先跑 response preview
  2. 再用真实对话做一轮端到端验证
  3. 最后查 audit 看 tool call 和最终用户响应是否一致

高频故障与分流

health check 失败

优先怀疑：

  • transport type 配错
  • connection config 不完整
  • 容器 / 网络视角下路径或 URL 不可达

test call 可以，真实对话不触发

优先怀疑：

  • mount 没绑定到当前 Agent
  • allowlist 拦掉了工具
  • 模型没有选中该工具
  • intent gate / direct response 配置影响了最终表现

工具触发了，但结果不对

优先怀疑：

  • tool arguments 生成错误
  • timeout 太短导致截断
  • 返回 payload 字段映射与预期不一致

审计里有调用，但前台看不到结果

优先怀疑：

  • passthrough / direct response 配置
  • 最终 generation 阶段覆盖了工具输出

排障建议

  • 先区分连接失败、策略阻断、参数生成错误还是结果注入错误
  • stdio 路径要按容器内路径判断，不按开发机路径判断
  • 先用 health check / test call 确认 transport 层，再看运行时策略层
  • 对多工具 Agent，要关注 max_calls_per_turn 与 mount priority

对应代码入口

路径 作用
ai_service/services/mcp_client.py transport 调用
ai_service/services/mcp_registry.py runtime mount 解析
ai_service/services/mcp_policy.py allowlist、budget、timeout 策略
ai_service/services/mcp_secret_manager.py credential 注入
ai_service/services/mcp_audit.py 调用审计
ai_service/orchestrator/mcp_response_config.py direct response 规则
ai_service/orchestrator/mcp_passthrough.py passthrough 渲染