Skip to main content

title: 工具

协议修订: 2025-06-18
模型上下文协议(MCP)允许服务器暴露可被语言模型调用的工具。工具使模型能够与外部系统交互,例如查询数据库、调用API或执行计算。每个工具由其名称唯一标识,并包含描述其模式的元数据。

用户交互模型

MCP中的工具设计为模型控制,这意味着语言模型可以基于其上下文理解及用户的提示自动发现并调用工具。 然而,实现可以自由地通过任何适合其需求的接口模式暴露工具——协议本身不强制任何特定的用户交互模型。
出于信任、安全和隐私的考虑,始终应有人类参与,其有权拒绝工具调用。应用程序
  • 提供UI,明确显示暴露给AI模型的工具
  • 在调用工具时插入清晰的视觉指示
  • 在执行操作时向用户呈现确认提示,以确保人类参与其中

功能

支持工具的服务器必须声明 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理解和正确处理结构化工具输出,方法包括:
  • 对响应进行严格的模式验证
  • 提供类型信息以便更好地与编程语言集成
  • 指导客户端和LLM正确解析和利用返回的数据
  • 支持更好的文档和开发体验

错误处理

工具使用两种错误报告机制:
  1. 协议错误:标准JSON-RPC错误,用于以下问题:
    • 未知工具
    • 无效参数
    • 服务器错误
  2. 工具执行错误:在工具结果中用 isError: true 报告:
    • API失败
    • 无效输入数据
    • 业务逻辑错误
示例协议错误:
示例工具执行错误:

安全考虑

  1. 服务器必须
    • 验证所有工具输入
    • 实现适当的访问控制
    • 限制工具调用频率
    • 清理工具输出
  2. 客户端
    • 在敏感操作时提示用户确认
    • 在调用服务器前向用户显示工具输入,以避免恶意或意外的数据泄露
    • 在传递给LLM前验证工具结果
    • 为工具调用实现超时机制
    • 记录工具使用情况以供审计