MCP工具调用系统
GeniSpace 智能体支持强大的MCP（Model Context Protocol）工具调用系统，能够通过内置工具和外部MCP服务器扩展智能体的能力边界。本指南详细介绍MCP工具的配置、使用和管理方法。
MCP工具概述
什么是MCP工具
MCP（Model Context Protocol）工具是一种标准化的接口协议，允许智能体调用功能和服务。GeniSpace实现了完整的MCP工具生态系统，包括：
- 内置工具：随智能体提供的渲染与实用工具
- 平台工具：平台提供的算子、任务和数据源
- 外部工具：通过MCP服务器提供的第三方工具
备注
只有在为智能体启用思维链时，工具才会执行。
工具分类
内置工具
- 来源：随智能体提供的渲染与实用工具
- 类型：
html_render、chart_render、table_render、iframe_embed、url_redirect、editable_document、web_browser和memory_tools - 用途：渲染丰富输出（HTML、图表、表格、嵌入框架、可编辑文档），并提供浏览、记忆存储等实用辅助
- 权限控制：通过内置工具开关启用或禁用
备注
内置工具仅为渲染/实用工具。数据库查询、邮件发送、文件处理等能力由平台算子（见下文）提供，而非内置工具。
平台算子工具
- 来源：平台算子系统和用户自定义算子
- 示例：以算子形式提供的数据库查询、邮件发送、文件处理等集成
- 命名规范：
operator_identifier_method_identifier - 权限控制：支持全部算子或指定算子选择
- 特点：
- 显示算子详细信息（名称、标识符、描述）
- 展示算子支持的方法列表
- 区分自定义算子和系统算子
平台任务工具
- 来源：平台任务系统
- 调用方式：智能体可以创建和执行任务
- 任务类型：SCHEDULED（定时任务）、EVENT（事件任务）、MANUAL（手动任务）
- 权限控制：支持全部任务或指定任务选择
- 特点：
- 显示任务名称、类型、描述
- 智能体可以将任务作为工具调用
- 支持任务编排和执行
平台数据源工具
- 来源：平台数据源系统
- 调用方式：智能体可以直接查询和操作数据源
- 操作类型：READ（读取）、CREATE（创建）、UPDATE（更新）、DELETE（删除）
- 权限控制：支持全部数据源或指定数据源选择
- 特点：
- 显示数据源名称、操作类型、描述
- 显示关联的数据库信息
- 智能体可以执行SQL查询和数据操作
外部工具（MCP服务器工具）
- 来源：外部MCP服务器
- 调用方式：直接调用外部MCP服务
- 命名规范：由服务器定义
- 扩展性：支持任意数量的外部服务器
MCP工具配置
基础配置
在智能体配置页面的工具（MCP）标签页进行配置。该标签页仅在启用思维链时可见。
这里有两个相互独立的开关——不存在单一的总开关：
1. 内置工具
☑️ 启用内置工具
- 控制随智能体提供的渲染与实用工具（
html_render、chart_render、table_render、iframe_embed、url_redirect、editable_document、web_browser、memory_tools） - 默认启用
2. 平台工具
☑️ 启用平台工具
- 控制对平台算子、任务和数据源的访问（包括用户自定义算子和系统算子）
- 启用后，请配置下方的选择策略
3. 算子选择策略
○ 不使用工具 - 禁用所有算子访问
○ 全部算子 - 使用用户有权限的所有算子
○ 指定算子 - 仅使用选中的特定算子
指定算子选择：
- 可以精确控制智能体可以使用的算子
- 支持多选，适用于专业化场景
- 显示算子名称、标识符、描述和方法列表
- 区分自定义算子和系统算子
- 有助于提高安全性和专业性
4. 任务选择策略
○ 不使用任务 - 禁用所有任务访问
○ 全部任务 - 智能体可以创建和执行任何任务
○ 指定任务 - 仅限使用选中的任务
指定任务选择：
- 控制智能体可以创建和执行的任务
- 显示任务名称、类型（SCHEDULED/EVENT/MANUAL）、描述
- 适用于有特定业务流程的场景
- 防止智能体执行不相关的任务
5. 数据源选择策略
○ 不使用数据源 - 禁用所有数据源访问
○ 全部数据源 - 智能体可以访问所有数据源
○ 指定数据源 - 仅限使用选中的数据源
指定数据源选择：
- 控制智能体可以访问的数据源
- 显示数据源名称、操作类型（READ/CREATE/UPDATE/DELETE）、描述
- 显示关联的数据库信息
- 适用于需要限制数据访问范围的场景
- 提高数据安全性
外部MCP服务器配置
添加外部服务器
{
"name": "自定义工具服务器",
"endpoint": "https://your-mcp-server.com",
"apiKey": "your-api-key",
"description": "提供特定领域的专业工具",
"tools": ["tool1", "tool2", "tool3"]
}
配置参数说明：
- name：服务器显示名称
- endpoint：MCP服务器API端点
- apiKey：访问密钥（可选）
- description：服务器功能描述
- tools：可用工具列表
工具分析与执行
智能工具分析
系统使用大语言模型分析用户输入，决定是否需要使用工具：
分析因素
- 用户意图：分析用户的真实需求
- 可用工具：检查当前可用的工具列表
- 上下文信息：利用知识库和搜索结果
- 执行历史：避免重复执行相同工具
- 角色定义：基于智能体的专业角色
分析流程
用户输入 → 意图识别 → 工具匹配 → 参数生成 → 执行决策
工具执行过程
1. 参数验证
- 检查必需参数是否完整
- 验证参数类型和格式
- 应用默认值和约束条件
2. 权限检查
- 验证用户对工具的访问权限
- 检查空间级别的工具配置
- 确保符合安全策略
3. 工具调用
- 根据工具类型选择调用方式
- 传递完整的上下文信息
- 记录执行过程和结果
4. 结果处理
- 解析工具返回的结果
- 生成执行摘要
- 更新工具执行历史
错误恢复机制
当工具执行失败时，系统提供智能错误恢复：
错误分析
- 解析错误类型和原因
- 分析原始参数的问题
- 提供参数修正建议
自动重试
- 基于错误信息重新生成参数
- 智能调整工具调用策略
- 提供详细的重试原因
错误类型处理
- 参数错误：重新分析和生成参数
- 权限错误：检查访问配置
- 网络错误：尝试重新连接
- 业务错误：根据错误信息调整策略
工具开发与集成
外部MCP服务器开发
标准MCP协议
- 实现标准的MCP接口规范
- 支持工具列表查询
- 提供工具执行接口
- 返回标准化结果格式
服务器示例
// 工具列表接口
GET /tools
{
"tools": [
{
"name": "weather_query",
"description": "查询天气信息",
"parameters": {...}
}
]
}
// 工具执行接口
POST /execute
{
"tool": "weather_query",
"parameters": {"city": "北京"}
}
API接口
列出可用工具
获取为某个智能体解析出的工具（内置工具，以及其配置允许的算子、任务、数据源和外部工具）。空间和用户由您的身份认证推导得出——无需 X-Space-ID、X-User-ID 或 X-Agent-ID 等请求头。
const res = await fetch(`/api/agents/${agentId}/mcp/tools`, {
method: 'GET',
headers: {
Authorization: 'Bearer YOUR_API_KEY'
}
});
const { data } = await res.json();
// data：{ tools, operatorTools, taskTools, externalTools }
智能体会在聊天或任务运行期间自行执行这些工具（需启用思维链）；没有可直接调用的单独"执行工具"接口。
最佳实践
工具选择策略
专业化智能体
- 算子选择：使用"指定算子"策略，只选择相关领域的算子
- 任务选择：使用"指定任务"策略，限制可执行的任务类型
- 数据源选择：使用"指定数据源"策略，限制可访问的数据源
- 优势：提高响应准确性和专业性，增强安全性
通用智能体
- 算子选择：使用"全部算子"策略，提供广泛的功能覆盖
- 任务选择：使用"全部任务"策略，允许执行任何任务
- 数据源选择：使用"全部数据源"策略，允许访问所有数据源
- 优势：适合多样化的任务需求，提供最大的灵活性
数据密集型智能体
- 算子选择：选择数据处理相关的算子
- 数据源选择：使用"指定数据源"策略，选择需要的数据源
- 任务选择：可选择数据同步、数据转换等任务
- 优势：专注于数据处理和分析任务
任务编排智能体
- 任务选择：使用"指定任务"策略，选择需要编排的任务
- 算子选择：选择任务执行所需的算子
- 数据源选择：根据任务需求选择数据源
- 优势：专注于任务编排和流程自动化
性能优化建议
提高工具执行成功率
- 保持选择聚焦：只授予智能体真正需要的算子、任务和数据源
- 优化错误处理：提供清晰的错误信息和恢复建议
- 监控工具状态：定期检查外部服务器的可用性
安全考虑
权限控制
- 严格限制工具访问权限
- 定期审查工具使用情况
- 实施最小权限原则
数据保护
- 避免在工具参数中传递敏感信息
- 使用加密传输保护API通信
- 记录和审计工具调用日志
故障排除
常见问题
工具列表为空
原因：
- 未为该智能体启用思维链
- 内置工具和平台工具两个开关都处于关闭状态
- 权限配置错误
解决方案：
- 启用思维链，然后打开"工具（MCP）"标签页
- 按需启用内置工具和/或平台工具
- 验证用户权限设置
工具执行失败
原因：
- 参数格式错误
- 权限不足
- 外部服务不可用
解决方案：
- 检查参数是否符合工具要求
- 验证工具访问权限
- 测试外部服务器连接
下一步
探索更多相关功能：
相关指南：