工具 - Model Context Protocol 中文文档

Model Context Protocol (MCP) 允许服务器公开可由语言模型调用的工具。工具使模型能够与外部系统交互，例如查询数据库、调用 API 或执行计算。每个工具都由名称唯一标识，并包含描述其 schema 的元数据。

用户交互模型

MCP 中的工具被设计为模型控制，这意味着语言模型可以基于其对上下文和用户提示的理解，自动发现并调用工具。不过，实现可以自由地通过任何适合自身需求的界面模式公开工具；协议本身并不强制规定任何特定的用户交互模型。

出于信任与安全及安全性考虑，SHOULD 始终让人类参与流程，并能够拒绝工具调用。应用 SHOULD:

提供清楚说明哪些工具会暴露给 AI 模型的 UI
在工具被调用时插入清晰的视觉指示
对操作向用户展示确认提示，确保人类参与流程

能力

支持工具的服务器 MUST 声明 tools 能力：

{
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  }
}

listChanged 表示服务器是否会在可用工具列表变化时发出通知。

协议消息

列出工具

为了发现可用工具，客户端会发送 tools/list 请求。此操作支持分页。 请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "title": "Weather Information Provider",
        "description": "Get current weather information for a location",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name or zip code"
            }
          },
          "required": ["location"]
        },
        "icons": [
          {
            "src": "https://example.com/weather-icon.png",
            "mimeType": "image/png",
            "sizes": ["48x48"]
          }
        ],
        "execution": {
          "taskSupport": "optional"
        }
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

调用工具

为了调用工具，客户端会发送 tools/call 请求： 请求：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "New York"
    }
  }
}

响应：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
      }
    ],
    "isError": false
  }
}

列表变化通知

当可用工具列表变化时，已声明 listChanged 能力的服务器 SHOULD 发送通知：

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

消息流

数据类型

Tool

工具定义包括：

name：工具的唯一标识符
title：用于显示的可选人类可读工具名称。
description：对功能的人类可读描述
icons：用于在用户界面中显示的可选图标数组
inputSchema：定义预期参数的 JSON Schema
- 遵循 JSON Schema 使用指南
- 如果不存在 $schema 字段，则默认为 2020-12
- MUST 是有效的 JSON Schema 对象（不是 null）
- 对于没有参数的工具，请使用以下有效方式之一：
  - { "type": "object", "additionalProperties": false } - 推荐：明确只接受空对象
  - { "type": "object" } - 接受任何对象（包括带有属性的对象）
outputSchema：定义预期输出结构的可选 JSON Schema
- 遵循 JSON Schema 使用指南
- 如果不存在 $schema 字段，则默认为 2020-12
annotations：描述工具行为的可选属性
execution：描述执行相关属性的可选对象
- taskSupport：表示此工具是否支持任务增强执行。取值为 "forbidden"（默认）、"optional" 或 "required"

出于信任与安全及安全性考虑，除非工具 annotations 来自受信任服务器，否则客户端 MUST 将其视为不可信。

工具名称

工具名称长度 SHOULD 在 1 到 128 个字符之间（含边界）。
工具名称 SHOULD 被视为区分大小写。
SHOULD 仅允许以下字符：ASCII 大写和小写字母（A-Z、a-z）、数字（0-9）、下划线（_）、连字符（-）和点（.）
工具名称 SHOULD NOT 包含空格、逗号或其他特殊字符。
工具名称 SHOULD 在服务器内唯一。
有效工具名称示例：
- getUser
- DATA_EXPORT_v2
- admin.tools.list

Tool Result

工具结果可以包含结构化内容或非结构化内容。 非结构化内容会在结果的 content 字段中返回，并且可以包含多个不同类型的内容项：

所有内容类型（文本、图像、音频、资源链接和嵌入式资源）都支持可选的 annotations，用于提供受众、优先级和修改时间等元数据。这与资源和提示使用的 annotation 格式相同。

文本内容

{
  "type": "text",
  "text": "Tool result text"
}

图像内容

{
  "type": "image",
  "data": "base64-encoded-data",
  "mimeType": "image/png",
  "annotations": {
    "audience": ["user"],
    "priority": 0.9
  }
}

音频内容

{
  "type": "audio",
  "data": "base64-encoded-audio-data",
  "mimeType": "audio/wav"
}

资源链接

工具 MAY 返回指向资源的链接，以提供额外上下文或数据。在这种情况下，工具会返回一个可由客户端订阅或获取的 URI：

{
  "type": "resource_link",
  "uri": "file:///project/src/main.rs",
  "name": "main.rs",
  "description": "Primary application entry point",
  "mimeType": "text/x-rust"
}

资源链接支持与常规资源相同的资源 annotations，以帮助客户端理解如何使用它们。

工具返回的资源链接不保证会出现在 resources/list 请求的结果中。

嵌入式资源

资源 MAY 使用合适的 URI 方案以内嵌方式提供额外上下文或数据。使用嵌入式资源的服务器 SHOULD 实现 resources 能力：

{
  "type": "resource",
  "resource": {
    "uri": "file:///project/src/main.rs",
    "mimeType": "text/x-rust",
    "text": "fn main() {\n    println!(\"Hello world!\");\n}",
    "annotations": {
      "audience": ["user", "assistant"],
      "priority": 0.7,
      "lastModified": "2025-05-03T14:30:00Z"
    }
  }
}

嵌入式资源支持与常规资源相同的资源 annotations，以帮助客户端理解如何使用它们。

Structured Content

结构化内容会作为 JSON 对象在结果的 structuredContent 字段中返回。为了向后兼容，返回结构化内容的工具 SHOULD 同时在 TextContent 块中返回序列化后的 JSON。

输出 Schema

工具也可以提供输出 schema，用于验证结构化结果。如果提供了输出 schema：

服务器 MUST 提供符合此 schema 的结构化结果。
客户端 SHOULD 根据此 schema 验证结构化结果。

带输出 schema 的工具示例：

{
  "name": "get_weather_data",
  "title": "Weather Data Retriever",
  "description": "Get current weather data for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or zip code"
      }
    },
    "required": ["location"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "temperature": {
        "type": "number",
        "description": "Temperature in celsius"
      },
      "conditions": {
        "type": "string",
        "description": "Weather conditions description"
      },
      "humidity": {
        "type": "number",
        "description": "Humidity percentage"
      }
    },
    "required": ["temperature", "conditions", "humidity"]
  }
}

此工具的有效响应示例：

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"temperature\": 22.5, \"conditions\": \"Partly cloudy\", \"humidity\": 65}"
      }
    ],
    "structuredContent": {
      "temperature": 22.5,
      "conditions": "Partly cloudy",
      "humidity": 65
    }
  }
}

提供输出 schema 有助于客户端和 LLM 通过以下方式理解并正确处理结构化工具输出：

启用对响应的严格 schema 验证
提供类型信息，以便更好地与编程语言集成
指导客户端和 LLM 正确解析和使用返回的数据
支持更好的文档和开发者体验

Schema 示例

使用默认 2020-12 schema 的工具：

{
  "name": "calculate_sum",
  "description": "Add two numbers",
  "inputSchema": {
    "type": "object",
    "properties": {
      "a": { "type": "number" },
      "b": { "type": "number" }
    },
    "required": ["a", "b"]
  }
}

使用显式 draft-07 schema 的工具：

{
  "name": "calculate_sum",
  "description": "Add two numbers",
  "inputSchema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "a": { "type": "number" },
      "b": { "type": "number" }
    },
    "required": ["a", "b"]
  }
}

无参数工具：

{
  "name": "get_current_time",
  "description": "Returns the current server time",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

错误处理

工具使用两种错误报告机制：

协议错误：用于以下问题的标准 JSON-RPC 错误：
- 未知工具
- 格式错误的请求（不满足 CallToolRequest schema 的请求）
- 服务器错误
工具执行错误：在工具结果中以 isError: true 报告：
- API 失败
- 输入验证错误（例如日期格式错误、值超出范围）
- 业务逻辑错误

工具执行错误包含可操作反馈，语言模型可用其自我修正并使用调整后的参数重试。 协议错误表示请求结构本身存在问题，模型通常不太可能修复。客户端 SHOULD 将工具执行错误提供给语言模型，以支持自我修正。客户端 MAY 将协议错误提供给语言模型，但这类错误不太可能成功恢复。协议错误示例：

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Unknown tool: invalid_tool_name"
  }
}

工具执行错误示例（输入验证）：

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Invalid departure date: must be in the future. Current date is 08/08/2025."
      }
    ],
    "isError": true
  }
}

安全注意事项

服务器 MUST:
- 验证所有工具输入
- 实现适当的访问控制
- 对工具调用进行速率限制
- 清理工具输出
客户端 SHOULD:
- 对敏感操作提示用户确认
- 在调用服务器前向用户显示工具输入，以避免恶意或意外的数据外泄
- 在传递给 LLM 前验证工具结果
- 为工具调用实现超时
- 出于审计目的记录工具使用情况

基础协议

客户端能力

服务器能力

工具

用户交互模型

能力

协议消息

列出工具

调用工具

列表变化通知

消息流

数据类型

Tool

工具名称

Tool Result

文本内容

图像内容

音频内容

资源链接

嵌入式资源

Structured Content

输出 Schema

Schema 示例

使用默认 2020-12 schema 的工具：

使用显式 draft-07 schema 的工具：

无参数工具：

错误处理

安全注意事项

​用户交互模型

​能力

​协议消息

​列出工具

​调用工具

​列表变化通知

​消息流

​数据类型

​Tool

​工具名称

​Tool Result

​文本内容

​图像内容

​音频内容

​资源链接

​嵌入式资源

​Structured Content

​输出 Schema

​Schema 示例

​使用默认 2020-12 schema 的工具：

​使用显式 draft-07 schema 的工具：

​无参数工具：

​错误处理

​安全注意事项

用户交互模型

能力

协议消息

列出工具

调用工具

列表变化通知

消息流

数据类型

Tool

工具名称

Tool Result

文本内容

图像内容

音频内容

资源链接

嵌入式资源

Structured Content

输出 Schema

Schema 示例

使用默认 2020-12 schema 的工具：

使用显式 draft-07 schema 的工具：

无参数工具：

错误处理

安全注意事项