title: 工具
协议修订: 2025-06-18
用户交互模型
MCP中的工具设计为模型控制,这意味着语言模型可以基于其上下文理解及用户的提示自动发现并调用工具。 然而,实现可以自由地通过任何适合其需求的接口模式暴露工具——协议本身不强制任何特定的用户交互模型。功能
支持工具的服务器必须声明tools 功能:
listChanged 表示当可用工具列表变化时,服务器是否会发送通知。
协议消息
列出工具
为了发现可用工具,客户端发送tools/list 请求。此操作支持分页。
请求:
调用工具
为了调用工具,客户端发送tools/call 请求:
请求:
列表变化通知
当可用工具列表发生变化时,声明了listChanged 功能的服务器应发送通知:
消息流程
数据类型
工具
一个工具定义包括:name: 工具的唯一标识符title: 可选的人类可读工具名称,用于显示。description: 功能的人类可读描述inputSchema: JSON Schema,定义预期参数outputSchema: 可选的JSON Schema,定义预期输出结构annotations: 可选属性,描述工具行为
工具结果
工具结果可以包含 结构化 或 非结构化 内容。 非结构化 内容返回在结果的content 字段中,可以包含多种类型的内容项:
所有内容类型(文本、图像、音频、资源链接和嵌入资源)
支持可选的
注解,
该注解提供了关于受众、优先级和修改时间的元数据。这与资源和提示使用的注解格式相同。
文本内容
图像内容
音频内容
资源链接
工具可以返回 资源 的链接,以提供额外的上下文或数据。在这种情况下,工具将返回一个客户端可以订阅或获取的URI:工具返回的资源链接不保证出现在
resources/list 请求的结果中。嵌入式资源
资源 可以 使用合适的 URI方案 嵌入以提供额外的上下文或数据。使用嵌入式资源的服务器应实现resources 功能:
结构化内容
结构化 内容作为JSON对象返回在结果的structuredContent 字段中。
为了向后兼容,返回结构化内容的工具应同时在 TextContent 块中返回序列化的JSON。
输出模式
工具还可以提供输出模式,以验证结构化结果。 如果提供了输出模式:- 服务器必须提供符合此模式的结构化结果。
- 客户端应针对此模式验证结构化结果。
- 对响应进行严格的模式验证
- 提供类型信息以便更好地与编程语言集成
- 指导客户端和LLM正确解析和利用返回的数据
- 支持更好的文档和开发体验
错误处理
工具使用两种错误报告机制:-
协议错误:标准JSON-RPC错误,用于以下问题:
- 未知工具
- 无效参数
- 服务器错误
-
工具执行错误:在工具结果中用
isError: true报告:- API失败
- 无效输入数据
- 业务逻辑错误
安全考虑
-
服务器必须:
- 验证所有工具输入
- 实现适当的访问控制
- 限制工具调用频率
- 清理工具输出
-
客户端应:
- 在敏感操作时提示用户确认
- 在调用服务器前向用户显示工具输入,以避免恶意或意外的数据泄露
- 在传递给LLM前验证工具结果
- 为工具调用实现超时机制
- 记录工具使用情况以供审计