1. 什么是引导？ #

引导（Elicitation）是 MCP 服务器通过客户端向用户请求额外信息的标准化方式。服务器在执行工具或完成任务时，可能需要用户提供配置、选择或敏感凭据，引导即用于此。

协议版本：2025-11-25

2. 本章你将学到 #

• 表单模式与 URL 模式的区别
• 能力声明与协议消息
• 表单模式下的 JSON Schema（字符串、数字、枚举等）
• 响应动作、错误处理与安全要点

3. 模式对比 #

安全：敏感信息必须用 URL 模式；表单模式不得请求密码、API 密钥等。

4. 能力 #

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

{
  "capabilities": {
    "elicitation": {
      "form": {},
      "url": {}
    }
  }
}

空对象 elicitation: {} 等价于仅支持 form。客户端必须至少支持一种模式。

5. 协议消息 #

5.1 引导请求（elicitation/create） #

5.2 表单模式示例 #

请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "elicitation/create",
  "params": {
    "mode": "form",
    "message": "Please provide your GitHub username",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" }
      },
      "required": ["name"]
    }
  }
}

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "action": "accept",
    "content": { "name": "octocat" }
  }
}

5.3 表单模式 Schema 类型 #

支持扁平对象的原始类型：

5.4 URL 模式示例 #

请求：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "elicitation/create",
  "params": {
    "mode": "url",
    "elicitationId": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://mcp.example.com/ui/set_api_key",
    "message": "Please provide your API key to continue."
  }
}

响应： action: "accept" 表示用户同意打开 URL；实际交互在外部完成，客户端不获知结果。

5.5 完成通知（URL 模式） #

当外部交互完成时，服务器可以发送：

{
  "jsonrpc": "2.0",
  "method": "notifications/elicitation/complete",
  "params": {
    "elicitationId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

客户端可据此重试先前失败的请求。

6. 响应动作 #

7. 流程示意 #

表单模式：

URL 模式：

8. 错误处理 #

9. 安全要点 #

10. 延伸阅读 #