MCP 服务
MCP(Model Context Protocol) 是让 AI 调用外部工具/数据源的通用协议。SparkX 通过 MCP 服务管理,让智能体和工作流能够自由调用任意外部能力,扩展性无上限。
1. 什么是 MCP
MCP(Model Context Protocol)是一套让大模型与外部工具通信的标准协议。你可以把它理解成"AI 世界的 USB 接口":
- 一个 MCP Server(MCP 服务端)对外暴露若干个工具(Tool)
- SparkX 作为 MCP Client(客户端)连接到 MCP Server,自动发现它有哪些工具
- 智能体/工作流在需要时,就能调用这些工具(查天气、查订单、发邮件、调内部 API……)
SparkX 智能体 ──调用工具──► MCP Server(外部)──执行──► 返回结果
(MCP 协议)
💡 有了 MCP,你不用改 SparkX 任何代码,只要部署/配置一个 MCP Server,智能体就自动多了一项能力。
2. MCP 服务能干什么
| 能力 | 说明 |
|---|---|
| 🔌 无限扩展 | 任何能写成 MCP Server 的能力都能接入(数据库、内部系统、第三方 API、本地脚本……) |
| 🔗 接入意图树 | MCP 工具可挂到智能体的意图树上,按意图路由调用 |
| 🧩 融入 RAG 管线 | 在 MIXED 场景下,模型可同时用检索结果 + MCP 工具 |
| 🔄 自动发现工具 | 连接 MCP Server 后,SparkX 自动拉取它的工具清单(工具数、参数定义) |
3. MCP 服务列表
进入「AI 配置 → MCP 服务」菜单,看到所有已配置的 MCP 服务卡片:
每个卡片展示:
| 信息 | 说明 |
|---|---|
| 传输类型 | SSE / HTTP Streamable(标签显示) |
| 启用状态 | 启用 / 禁用(可点开关切换) |
| 服务名称 | 自定义名称 |
| 地址 | MCP Server 的端点 URL |
| 认证 | 无认证 / API Key / Bearer Token(及是否已配置) |
| 工具 | 该服务自动发现的工具数量 |
卡片操作
每个卡片底部有 4 个操作:
| 操作 | 说明 |
|---|---|
| 编辑 | 修改服务配置 |
| 测试 | 测试连接,验证配置是否正确(会弹出测试结果) |
| 刷新工具 | 重新拉取 MCP Server 的工具清单(服务端工具变更后用) |
| 删除 | 删除该服务(关联的工具快照一并删除,意图树中引用该服务的节点将失效) |
⚠️ 删除 MCP 服务前,确认没有智能体/意图树正在引用它的工具,否则相关节点会失效。
4. 新增 / 编辑 MCP 服务
点击「新增服务」或在卡片点「编辑」,右侧弹出配置抽屉:
4.1 基本信息
| 字段 | 说明 |
|---|---|
| 服务名称(必填) | 自定义,如「天气查询服务」 |
| 描述 | 服务用途说明(可选) |
| 启用 | 是否启用该服务 |
4.2 连接配置
| 字段 | 说明 |
|---|---|
| 传输类型 | 当前支持 HTTP Streamable(MCP 标准传输) |
| 服务地址(必填) | MCP Server 的端点地址,如 http://localhost:3001/mcp |
💡 服务地址要填 MCP Server 的完整端点路径,不是只填到根域名。
4.3 认证配置
三种认证方式可选:
| 认证类型 | 说明 | 额外字段 |
|---|---|---|
| 无认证 | MCP Server 不需要鉴权 | 无 |
| API Key | 通过自定义请求头传 Key | 请求头名称(默认 X-API-Key)+ API Key |
| Bearer Token | 通过 Authorization 头传 Token | Bearer Token |
🔒 安全说明:
- API Key / Token 在编辑时不会回显(后端脱敏),留空表示保留原值,改动才需重新填写
- 卡片上的「(已配置)/(未配置)」标记帮你确认密钥状态
4.4 自定义请求头(可选)
如果 MCP Server 需要额外的自定义请求头(如 X-Tenant-Id),可在这里逐行添加:
- 每行一个 Header(键值对)
- 点
+ 添加请求头增加行,点✕删除
4.5 高级配置
| 字段 | 默认值 | 说明 |
|---|---|---|
| 超时(秒) | 30 | 调用工具的超时时间(1~300) |
| 重试次数 | 1 | 调用失败后的重试次数(0~10) |
| 备注 | — | 备注(可选) |
| 排序 | 100 | 列表排序,数值小者靠前 |
5. 测试与刷新
5.1 测试连接
配置完(或编辑时)点「测试连接」,会用当前表单参数真实连接一次 MCP Server:
- 连接成功 → 弹出测试结果,显示发现的工具清单
- 连接失败 → 提示具体错误(地址不通 / 认证失败 / 超时等),据此排查
💡 建议每次新增/修改服务都先测试,确认能连上再保存。
5.2 刷新工具
当 MCP Server 新增或改动了工具后,点「刷新工具」让 SparkX 重新拉取最新的工具清单。
- 刷新成功 → 工具数更新,可在意图树/智能体里选用新工具
- 刷新失败 → 提示错误原因
💡 测试连接和刷新工具都会更新工具快照,区别在于:测试偏重"验证能不能连",刷新偏重"同步最新工具列表"。
6. MCP 工具如何被使用
配置好 MCP 服务后,它的工具通过两条路径被智能体使用:
路径一:意图树路由(主路径)
在智能体的意图树配置里,把某个 MCP 工具挂到对应意图节点上。用户提问命中该意图时,智能体调用这个工具:
用户提问 → 意图分类 → 命中"查天气"意图 → 调用天气 MCP 工具 → 返回结果
路径二:工作流节点
在工作流编排里,通过 LLM 节点的提示词编排,让模型在 MIXED 场景下自主决定是否调用 MCP 工具(对应 PromptPlanner 的 MCP_ONLY / MIXED 场景路由)。
💡 这两条路径对应 README 里提到的
mcp/模块:McpToolRegistry(注册中心)+McpToolService(执行器)+McpClientManager(客户端管理)。
7. 配置速查表
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 服务名称 | — | 自定义(必填) |
| 传输类型 | HTTP Streamable | MCP 标准传输 |
| 服务地址 | — | MCP Server 端点(必填) |
| 认证类型 | 无认证 | 无 / API Key / Bearer Token |
| 超时(秒) | 30 | 1~300 |
| 重试次数 | 1 | 0~10 |
| 排序 | 100 | 小者靠前 |
8. 注意事项
- ⚠️ 服务地址要填完整端点路径(如
http://localhost:3001/mcp),不要只填域名 - ⚠️ API Key / Token 编辑时不回显,留空即保留原值;只有想更换时才重新填
- ⚠️ 删除 MCP 服务会让引用它的意图节点失效,删除前务必确认
- ⚠️ MCP Server 端工具变更后,记得点「刷新工具」同步,否则用的还是旧工具快照
- 💡 生产环境建议给 MCP Server 配上认证(API Key / Bearer Token),避免裸奔
- 💡 如果连接不稳定,适当调大「超时」和「重试次数」
