模型上下文协议 (MCP) 允许服务器公开可由语言模型调用的工具。工具使模型能够与外部系统交互，例如查询数据库、调用 API 或执行计算。每个工具都由唯一的名称标识，并包含描述其 schema 的元数据。
用户交互模型
MCP 中的工具设计为受模型控制，这意味着语言模型可以根据其上下文理解和用户的提示词自动发现并调用工具。 然而，实现方式可以自由地通过任何符合其需求的界面模式公开工具——协议本身并不强制要求任何特定的用户交互模型。出于信任、安全和保障的考虑，应当 (SHOULD) 始终保持“人工在环”(human in the loop)，即拥有拒绝工具调用的能力。应用程序应当 (SHOULD)：
- 提供明确显示哪些工具正向 AI 模型公开的 UI
- 在调用工具时插入清晰的视觉指示器
- 在操作前向用户呈现确认提示，以确保人工干预
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"]
}
]
}
],
"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"
}
消息流
数据类型
工具定义包括
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
annotations：描述工具行为的可选属性
出于信任、安全和保障的考虑，客户端必须 (MUST) 将工具注释视为不可信，除非它们来自受信任的服务器。
- 工具名称的长度应当 (SHOULD) 在 1 到 128 个字符之间（含）。
- 工具名称应当 (SHOULD) 被视为区分大小写。
- 以下应当 (SHOULD) 是唯一允许的字符：大写和小写 ASCII 字母 (A-Z, a-z)、数字 (0-9)、下划线 (_)、连字符 (-) 和点 (.)
- 工具名称不应 (SHOULD NOT) 包含空格、逗号或其他特殊字符。
- 工具名称在一个服务器内应当 (SHOULD) 是唯一的。
- 有效工具名称示例
- getUser
- DATA_EXPORT_v2
- admin.tools.list
工具结果可能包含结构化或非结构化内容。 非结构化内容在结果的 content 字段中返回，可以包含多个不同类型的内容项：所有内容类型（文本、图像、音频、资源链接和内嵌资源）都支持可选的 annotations（注释），用于提供有关受众、优先级和修改时间的元数据。这与资源和提示词使用的注释格式相同。 文本内容
{
"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"
}
工具返回的资源链接不保证会出现在 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"
}
}
}
结构化内容
结构化内容在结果的 structuredContent 字段中作为 JSON 对象返回。 为了向后兼容，返回结构化内容的工具应当 (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 示例
{
"name": "calculate_sum",
"description": "Add two numbers",
"inputSchema": {
"type": "object",
"properties": {
"a": { "type": "number" },
"b": { "type": "number" }
},
"required": ["a", "b"]
}
}
{
"name": "calculate_sum",
"description": "Add two numbers",
"inputSchema": {
"$schema": "https://schema.json.js.cn/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 错误：
-
工具执行错误：在工具结果中通过
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)：
- 验证所有工具输入
- 实施适当的访问控制
- 对工具调用进行速率限制
- 清理工具输出
-
客户端**应该**
- 在敏感操作上提示用户确认
- 在调用服务器之前向用户显示工具输入，以避免恶意或意外的数据泄露
- 在传递给 LLM 之前验证工具结果
- 为工具调用实施超时机制
- 记录工具使用情况以便审计
