协议版本: 2024-11-05
Model Context Protocol (MCP) 允许服务器暴露可供语言模型调用的工具。工具使模型能够与外部系统交互，例如查询数据库、调用API或执行计算。每个工具通过唯一的名称标识，并包含描述其模式的元数据。

​
用户交互模型

Tools in MCP are designed to be 模型控制的, meaning that the language model can discover and invoke tools automatically based on its contextual understanding and the user’s prompts. 然而，实现可以自由通过任何适合其需求的接口模式来暴露工具——协议本身并不强制任何特定的用户交互模式。
For trust & safety and security, there 应当 always be a human in the loop with the ability to deny tool invocations.Applications 应当:
  • 提供用户界面，清晰展示哪些工具正在暴露给AI模型
  • 调用工具时插入清晰的可视化指示器
  • 向用户展示操作确认提示，以确保人工参与其中

​
能力

Servers that support tools 必须 declare the tools capability: 
{
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  }
}
listChanged indicates whether the server will emit notifications when the list of available tools changes.

​
协议消息

​
列出工具

To discover available tools, clients send a tools/list request. This operation supports pagination. 请求： 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}
响应： 响应： 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather information for a location",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name or zip code"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

​
调用工具

To invoke a tool, clients send a tools/call request: 请求： 
{
  "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 能力的服务器应当发送通知： 
{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

​
消息流

​
数据类型

​
工具

工具定义包含：
  • name: 工具的独特标识
  • description: 功能的人类可读描述
  • inputSchema: JSON模式定义预期参数

​
工具结果

工具结果可包含多种不同类型的条目内容：

​
文本内容

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

​
图像内容

{
  "type": "image",
  "data": "base64-encoded-data",
  "mimeType": "image/png"
}

​
嵌入资源

Resources 可以 被嵌入，用于通过一个可供客户端稍后订阅或再次获取的URI来提供额外的上下文或数据： 
{
  "type": "resource",
  "resource": {
    "uri": "resource://example",
    "mimeType": "text/plain",
    "text": "Resource content"
  }
}

​
错误处理

工具使用两种错误报告机制：
  1. 协议错误: Standard JSON-RPC errors for issues like:
    • 未知工具
    • 无效参数
    • 服务器错误
  2. 工具执行错误: Reported in tool results with isError: true:
    • API失败
    • 无效输入数据
    • 业务逻辑错误
协议错误示例: 
{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Unknown tool: invalid_tool_name"
  }
}
示例工具执行错误： 
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Failed to fetch weather data: API rate limit exceeded"
      }
    ],
    "isError": true
  }
}

​
安全注意事项

  1. 服务器 必须:
    • 验证所有工具输入
    • 实施恰当的访问控制
    • 限制工具调用频率
    • 净化工具输出内容
  2. Clients 应当:
    • 在敏感操作上提示用户确认
    • 在调用服务器之前向用户显示工具输入，避免恶意或意外的数据泄露
    • 在传递给大语言模型LLM之前验证工具结果
    • 为工具调用实现超时机制
    • 记录工具使用情况以便审计