1. 什么是采样？ #

采样（Sampling）是 MCP 服务器通过客户端向语言模型发起「生成/补全」请求的标准化方式。服务器无需自己的 API 密钥，由客户端控制模型访问和权限。

协议版本：2025-11-25

2. 本章你将学到 #

• 采样的能力声明与协议消息
• 基本采样与带工具的采样
• 多轮工具循环与消息约束
• 模型偏好、错误处理与安全要点

3. 典型流程 #

信任与安全：应有用户参与，具备拒绝能力；应用应提供审核 UI，允许查看/编辑提示和响应。

4. 能力 #

客户端必须在初始化时声明 sampling 能力：

5. 协议消息 #

5.1 基本采样（sampling/createMessage） #

请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": { "type": "text", "text": "What is the capital of France?" }
      }
    ],
    "modelPreferences": {
      "hints": [{ "name": "claude-3-sonnet" }],
      "intelligencePriority": 0.8,
      "speedPriority": 0.5
    },
    "systemPrompt": "You are a helpful assistant.",
    "maxTokens": 100
  }
}

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "role": "assistant",
    "content": { "type": "text", "text": "The capital of France is Paris." },
    "model": "claude-3-sonnet-20240307",
    "stopReason": "endTurn"
  }
}

5.2 带工具的采样 #

服务器在请求中加入 tools 和可选的 toolChoice：LLM 可请求调用工具，服务器执行后把结果作为 tool_result 发回，继续下一轮采样。

5.3 工具选择模式（toolChoice） #

6. 多轮工具循环 #

1. 服务器发送带 tools 的采样请求
2. LLM 返回 stopReason: "toolUse"，内容含 tool_use 块
3. 服务器执行工具，将结果作为 tool_result 加入消息
4. 服务器发送带工具结果的新采样请求
5. 重复 2–4 直至 LLM 返回 stopReason: "endTurn"

7. 消息内容约束 #

7.1 工具结果消息 #

包含工具结果（type: "tool_result"）的用户消息必须仅含工具结果，不能与文本、图像等混合。

7.2 工具使用与结果平衡 #

每个 tool_use 块必须有对应的 tool_result 匹配（toolUseId 与 id 一致），且位于下一轮助手消息之前。所有工具使用都解析后，对话才能继续。

8. 流程示意 #

9. 模型偏好 #

9.1 能力优先级（0–1） #

9.2 模型提示（hints） #

服务端可建议模型名称或系列：

{
  "hints": [
    { "name": "claude-3-sonnet" },
    { "name": "claude" }
  ],
  "costPriority": 0.3,
  "speedPriority": 0.8,
  "intelligencePriority": 0.5
}

客户端做最终选择，可将提示映射到不同提供商的等效模型。

10. 消息内容类型 #

11. 错误处理 #

示例： 用户拒绝

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -1,
    "message": "User rejected sampling request"
  }
}

12. 安全要点 #