MCP 外部工具管理

MCP（Model Context Protocol）是给大模型挂外部工具的标准协议。配好一台 MCP 服务器，小匠就能调它暴露的工具（查表、写脚本、跑分析），所有业务侧能力都从这里接进来。

4.1 MCP 是什么

MCP 是 Anthropic 开源的一套外部工具接入协议，把"模型 ↔ 工具"之间的发现、调用、错误返回统一成一套接口。小匠在每条对话里能调"数据分析""平台配置""菜单查询"等业务能力，背后都是连到一台或多台 MCP 服务器上完成的。

对管理员的视角而言，MCP 服务器 = 一组可调用工具的容器：

• 一台 MCP 服务器对外暴露 N 个工具（tool），每个工具有自己的名称、参数定义、用途说明
• 小匠在跑对话时，由 AI 决定调哪个工具、传什么参数；管理员只负责保证服务器在线、工具能正常返回
• 新增 / 退役一组业务能力，对应的操作就是加一台 MCP 服务器或停掉一台 MCP 服务器，不用改小匠代码

提示： 和 Skill 的区别：Skill 是"对 AI 的提示词 + 一组操作步骤"（教 AI 怎么做），是文档级资产；MCP 是"AI 能调用的工具端口"，是运行时服务。一个 Skill 往往会调用 MCP 暴露出来的若干工具来完成任务。

4.2 进入 MCP 管理

1. 用 admin 或 super_admin 账号登录小匠 admin 后台
2. 左侧导航 → 能力配置 → MCP 管理，地址 /admin/mcp
3. 进入后能看到 MCP 服务卡片网格，顶部有两个 Tab：服务 N（卡片视图）和 工具 N（按来源 MCP / Skill / 系统工具分组的扁平表）
4. 右上角有 连通性自检（批量探活所有服务）和 添加 MCP 服务 两个按钮

小贴士： 第一次启动已经配过一台：第一次跑 setup 向导（见首次启动：setup 向导）时，第 3 步已经默认接入了 http://localhost:7000/mcp，本章后续讲怎么管理它、再加更多。

4.3 MCP 服务器卡片

每张卡片就是一台 MCP 服务器，结构含义如下：

4.4 添加 MCP 服务

典型场景：业务侧新部署了一组 docker 容器（比如新一套数据中台的 MCP 接口）、要把它接进来给小匠用。

1. 右上角 添加 MCP 服务 按钮，打开「添加 MCP 服务」弹窗
2. 弹窗里依次填（带 * 为必填）：服务名 （小写字母 / 数字 / 连字符，3-41 位，命名约定 jecloud-<area>-mcp，编辑模式只读）；中文显示名（业务用户和管理员可见的展示名，可选）；类型 （stdio 本地子进程 / HTTP（streamable_http） 默认 / SSE 三选一）；URL / 启动命令 *（HTTP/SSE 填完整 URL 如 http://localhost:7000/mcp，stdio 填本地子进程启动命令含参）；超时（秒）（单次工具调用超时，默认 30，范围 1-300）；备注（干啥用 / 谁维护 / 注意事项，可选）；启用（默认勾上即可）
3. 底部按钮：测试连接（仅编辑模式可用，新建时禁用）/ 取消 / 创建
4. 点 创建 保存后，列表多出一张卡片；可再点 连通性自检 或卡片底部测试按钮探活
5. 保存失败 → 弹窗保留所填、显示错误信息（连不通 / 协议错 / 名字冲突），改完再试

注意： HTTP 模式优先：除非你明确知道要跑本地 stdio 进程，一律用 HTTP（streamable_http）模式。stdio 走的是本地子进程 stdin/stdout，不适合 docker 化部署，调试也麻烦；SSE 是旧协议，仅在对接老服务时使用。

4.5 测试连接 + 查看工具

卡片底部测试连接图标按钮负责探活：发一次握手包确认 MCP 进程在监听，结果以 toast 弹窗反馈「测试通过」或「测试失败 + 错误信息」，同时刷新卡片状态徽标（运行中 / 离线）。右上角的连通性自检是批量版，依次对所有服务跑一遍。

查看工具有两个入口：

• 卡片 meta 行的 工具 N 数字（蓝色可点）→ 弹「查看工具 · <name>」对话框，列出该 MCP 的工具表（# / 工具名 / 说明）
• 顶部切到 工具 Tab → 看全站所有工具的扁平表，按来源（MCP / Skill / 系统工具）分组，可折叠 / 搜索工具名 + 说明

每条工具显示两列：

• 工具名（如 tbl_create / da_query / menu_get_top）
• 说明（来自 MCP 自己的 description）

小贴士： 工具数突然变了？同一台 MCP 服务器，业务侧升级镜像后工具数往往会变。每次 MCP 端有更新，建议手动跑一次测试连接并切到「工具」Tab 点刷新——AI 那边下次对话才会感知到新增工具。

4.6 工具调用（运行时怎么工作）

管理员一般不需要手工"调用"某个 MCP 工具——工具是给 AI 用的。但理解一下流程，对排查故障有帮助。

一次对话里，AI 决定调一个 MCP 工具的链路是：

用户消息 → 小匠 agent → LLM 看到所有启用的 MCP 工具清单
       → LLM 选定要调的工具 + 拼参数
       → 小匠 agent 转发给对应的 MCP 服务器
       → MCP 跑业务逻辑（查库 / 调平台 API / 算 hash …）
       → 返回结果给 LLM 作为下一轮上下文
       → LLM 生成最终回答

要确认某条对话调了哪些工具，去 监控 → 调用日志（/admin/traces，见监控章节）查这条会话的 trace，能看到工具名、入参、出参、耗时和错误。

提示： 停用 = 对 AI 隐身：列表里把一台 MCP 的「启用」关掉，并不会停掉 MCP 进程本身，只是不再把它的工具广播给 LLM——AI 下次对话就看不到这些工具，自然不会调。临时下线一台疑似有问题的 MCP，比删除安全。

4.7 故障排查

MCP 出问题时，AI 给的回答会很奇怪（"我无法访问该数据""未找到工具"），先按下面这套顺序查。

状态显示「离线」

1. 卡片底部点测试连接图标 → 看 toast 里的错误提示
2. 常见原因：URL 写错（多/少了 /mcp、端口错、协议错）；MCP 进程没起（docker 容器挂了 / 端口冲突）；网络不通（小匠 agent 所在机器到 MCP 那台机器有防火墙）
3. 在 MCP 服务器所在机器上直接 curl http://host:port/mcp 确认服务是否在监听

状态在线，但工具调用总报错

1. 去 调用日志（/admin/traces）找最近这条出错的 trace
2. 看工具的真实入参 / 错误返回——一般是 MCP 端业务层报错（比如登录态过期、参数 schema 对不上）
3. 必要时去 MCP 服务器的容器里看进程日志（小匠侧能拿到的就是 MCP 返回的那段 message）

工具列表里少了一个想要的工具

1. 切到顶部 工具 Tab，右上角点刷新（旋转箭头）按钮重新拉全表
2. 仍没有 → 说明 MCP 端没暴露这个工具，去 MCP 端确认是否在 tools/ 目录里注册了
3. 暴露了但小匠端拉不到 → 看 MCP 端日志、确认 tools/list 接口的返回是否包含它

AI 看似调对了工具，但回答总是错

1. 多半是提示词 / 工具 description 不够清晰，导致 AI 误用
2. 看提示词管理，确认 system 提示词里对这类工具的指引是否准确
3. 必要时让 MCP 开发改 tools/<name>.py 里的 description，把"什么时候调""参数怎么填"写得更具体

注意： 不要直接删 MCP 服务器去"刷新"：删除是不可逆操作（运行中的 chat 流不受影响，但下次 chat 重建 agent 时不再含此 MCP）。临时排查请用停用开关，确认彻底退役再删。

小贴士： 排查口诀：不通查 URL & 端口 → 通了查 trace → trace 有错查 MCP 端日志 → 一切正常但 AI 错查提示词。

提示： 下一步：改了 MCP 服务器配置后 → 点该 MCP 行的「测试连接」按钮，看是否拉到新工具列表 → 去 chat 实测一条会用到该工具的对话，再去调用日志看记录。

相关

• Skill 技能包管理
• 模型管理
• 提示词管理
• 监控：调用 · 审计 · 系统日志