引导

协议版本: 2025-11-25

模型上下文协议（MCP）为服务器提供了一种标准化方式，用于在交互过程中通过客户端向用户请求额外信息。此流程允许客户端保持对用户交互和数据共享的控制，同时使服务器能够动态收集必要的信息。

引导支持两种模式：

表单模式：服务器可以从用户请求结构化数据，带有可选的 JSON 模式来验证响应
URL 模式：服务器可以将用户引导到外部 URL，用于不应该通过 MCP 客户端传递的敏感交互

1 用户交互模型

MCP 中的引导允许服务器通过启用用户输入请求嵌套在其他 MCP 服务器功能中来实现交互式工作流程。

实现可以通过任何适合其需求的界面模式公开引导——协议本身不强制要求任何特定的用户交互模型。

为了信任与安全以及安全性：

服务器禁止使用表单模式引导来请求敏感信息
服务器必须对涉及敏感信息（如凭据）的交互使用 URL 模式

MCP 客户端必须：

提供清楚显示哪个服务器正在请求信息的 UI
尊重用户隐私并提供清晰的拒绝和取消选项
对于表单模式，允许用户在发送之前查看和修改其响应
对于 URL 模式，在导航到目标 URL 之前清楚显示目标域/主机并获取用户同意

2 能力

支持引导的客户端必须在初始化期间声明 elicitation 能力：

json

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

为了向后兼容，空的能力对象等同于仅声明对 form 模式的支持：

json

{
  "capabilities": {
    "elicitation": {}  // 等同于 { "form": {} }
  }
}

声明 elicitation 能力的客户端必须至少支持一种模式（form 或 url）。

服务器禁止发送客户端不支持的模式的引导请求。

3 协议消息

3.1 引导请求

要从用户请求信息，服务器发送 elicitation/create 请求。

所有引导请求必须包含以下参数：

名称	类型	选项	描述
`mode`	string	`form`、`url`	引导的模式。对于表单模式是可选的（如果省略则默认为 `"form"`）。
`message`	string		解释为什么需要交互的人类可读消息。

mode 参数指定引导的类型：

"form"：带有可选模式验证的带内结构化数据收集。数据暴露给客户端。
"url"：通过 URL 导航的带外交互。数据（除了 URL 本身）不暴露给客户端。

为了向后兼容，服务器可以省略表单模式引导请求的 mode 字段。客户端必须将没有 mode 字段的请求视为表单模式。

3.2 表单模式引导请求

表单模式引导允许服务器直接通过 MCP 客户端收集结构化数据。

表单模式引导请求必须指定 mode: "form" 或省略 mode 字段，并包含以下额外参数：

名称	类型	描述
`requestedSchema`	object	定义预期响应结构的 JSON Schema。

3.2.1 请求的模式

requestedSchema 参数允许服务器使用 JSON Schema 的受限子集来定义预期响应的结构。

为简化客户端用户体验，表单模式引导模式仅限于具有原始属性的扁平对象。

模式限于以下原始类型：

字符串模式

json

{
  "type": "string",
  "title": "Display Name",
  "description": "Description text",
  "minLength": 3,
  "maxLength": 50,
  "pattern": "^[A-Za-z]+$",
  "format": "email",
  "default": "user@example.com"
}

支持的格式：email、uri、date、date-time

数字模式

json

{
  "type": "number",
  "title": "Display Name",
  "description": "Description text",
  "minimum": 0,
  "maximum": 100,
  "default": 50
}

布尔模式

json

{
  "type": "boolean",
  "title": "Display Name",
  "description": "Description text",
  "default": false
}

枚举模式

单选枚举（无标题）：

json

{
  "type": "string",
  "title": "Color Selection",
  "description": "Choose your favorite color",
  "enum": ["Red", "Green", "Blue"],
  "default": "Red"
}

单选枚举（带标题）：

json

{
  "type": "string",
  "title": "Color Selection",
  "description": "Choose your favorite color",
  "oneOf": [
    { "const": "#FF0000", "title": "Red" },
    { "const": "#00FF00", "title": "Green" },
    { "const": "#0000FF", "title": "Blue" }
  ],
  "default": "#FF0000"
}

多选枚举（无标题）：

json

{
  "type": "array",
  "title": "Color Selection",
  "description": "Choose your favorite colors",
  "minItems": 1,
  "maxItems": 2,
  "items": {
    "type": "string",
    "enum": ["Red", "Green", "Blue"]
  },
  "default": ["Red", "Green"]
}

多选枚举（带标题）：

json

{
  "type": "array",
  "title": "Color Selection",
  "description": "Choose your favorite colors",
  "minItems": 1,
  "maxItems": 2,
  "items": {
    "anyOf": [
      { "const": "#FF0000", "title": "Red" },
      { "const": "#00FF00", "title": "Green" },
      { "const": "#0000FF", "title": "Blue" }
    ]
  },
  "default": ["#FF0000", "#00FF00"]
}

客户端可以使用此模式来：

生成适当的输入表单
在发送之前验证用户输入
为用户提供更好的指导

所有原始类型都支持可选的默认值以提供合理的起点。支持默认值的客户端应该使用这些值预填表单字段。

请注意，复杂的嵌套结构、对象数组（除枚举外）和其他高级 JSON Schema 功能故意不被支持，以简化客户端用户体验。

3.2.2 示例：简单文本请求

请求：

json

{
  "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"]
    }
  }
}

响应：

json

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

3.2.3 示例：结构化数据请求

请求：

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "elicitation/create",
  "params": {
    "mode": "form",
    "message": "Please provide your contact information",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Your full name"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Your email address"
        },
        "age": {
          "type": "number",
          "minimum": 18,
          "description": "Your age"
        }
      },
      "required": ["name", "email"]
    }
  }
}

响应：

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "action": "accept",
    "content": {
      "name": "Monalisa Octocat",
      "email": "octocat@github.com",
      "age": 30
    }
  }
}

3.3 URL 模式引导请求

新功能：URL 模式引导在 MCP 规范的 2025-11-25 版本中引入。其设计和实现可能在未来的协议修订版中发生变化。

URL 模式引导使服务器能够将用户引导到外部 URL，用于不应通过 MCP 客户端传递的带外交互。这对于身份验证流程、支付处理和其他敏感或安全操作至关重要。

URL 模式引导请求必须指定 mode: "url"、一个 message，并包含以下额外参数：

名称	类型	描述
`url`	string	用户应导航到的 URL。
`elicitationId`	string	引导的唯一标识符。

url 参数必须包含有效的 URL。

重要：URL 模式引导不是用于授权 MCP 客户端访问 MCP 服务器（这由 MCP 授权处理）。相反，它用于 MCP 服务器需要代表用户获取敏感信息或第三方授权时。MCP 客户端的 bearer 令牌保持不变。客户端的唯一责任是向用户提供关于服务器希望他们打开的引导 URL 的上下文。

3.3.1 示例：请求敏感数据

请求：

json

{
  "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."
  }
}

响应：

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "action": "accept"
  }
}

3.4 URL 模式引导的完成通知

当 URL 模式引导启动的带外交互完成时，服务器可以发送 notifications/elicitation/complete 通知。

3.5 需要 URL 引导的错误

当请求在引导完成之前无法处理时，服务器可以返回 URLElicitationRequiredError（代码 -32042）以向客户端指示需要 URL 模式引导。

4 消息流程

4.1 表单模式流程

4.2 URL 模式流程

4.3 带引导需求错误的 URL 模式流程

5 响应操作

三种响应操作是：

接受（action: "accept"）：用户明确批准并提交了数据
拒绝（action: "decline"）：用户明确拒绝了请求
取消（action: "cancel"）：用户关闭而未做出明确选择

6 实现注意事项

6.1 状态性

实现引导的服务器必须安全地将此状态与个人用户关联。

6.2 用于敏感数据的 URL 模式引导

对于与需要敏感信息的外部 API 交互的服务器。

6.3 用于 OAuth 流程的 URL 模式引导

URL 模式引导支持一种模式，其中 MCP 服务器充当第三方资源服务器的 OAuth 客户端。

7 错误处理

当请求在引导完成之前无法处理时：-32042（URLElicitationRequiredError）
服务器发送客户端能力中未声明的模式的 elicitation/create 请求：-32602（无效参数）

8 安全注意事项

服务器必须将引导请求绑定到客户端和用户身份
客户端必须提供清晰的指示，说明哪个服务器正在请求信息
客户端应该实施用户批准控制
客户端应该允许用户随时拒绝引导请求
客户端应该实施速率限制
客户端应该以清楚说明正在请求什么信息以及为什么请求的方式呈现引导请求

8.1 安全 URL 处理

请求引导的 MCP 服务器：

禁止在 URL 中包含关于最终用户的敏感信息
禁止提供预先认证的 URL
不应该在表单模式引导请求的任何字段中包含可点击的 URL
应该为非开发环境使用 HTTPS URL

实现 URL 模式引导的客户端：

禁止自动预获取 URL
禁止在没有用户明确同意的情况下打开 URL
必须在同意之前向用户显示完整的 URL 以供检查
必须以安全的方式打开 URL

8.2 表单模式安全

服务器禁止通过表单模式请求敏感信息
客户端应该根据提供的模式验证所有响应
服务器应该验证接收的数据是否与请求的模式匹配

MCP 规范

规范说明：2025-06-18

MCP 客户端功能概述

MCP 服务器功能概述

工具

规范说明：2025-11-25

概述

客户端功能概述

服务器功能概述

ComfyUI 教程

引导 ​

1 用户交互模型 ​

2 能力 ​

3 协议消息 ​

3.1 引导请求 ​

3.2 表单模式引导请求 ​

3.2.1 请求的模式 ​

3.2.2 示例：简单文本请求 ​

3.2.3 示例：结构化数据请求 ​

3.3 URL 模式引导请求 ​

3.3.1 示例：请求敏感数据 ​

3.4 URL 模式引导的完成通知 ​

3.5 需要 URL 引导的错误 ​

4 消息流程 ​

4.1 表单模式流程 ​

4.2 URL 模式流程 ​

4.3 带引导需求错误的 URL 模式流程 ​

5 响应操作 ​

6 实现注意事项 ​

6.1 状态性 ​

6.2 用于敏感数据的 URL 模式引导 ​

6.3 用于 OAuth 流程的 URL 模式引导 ​

7 错误处理 ​

8 安全注意事项 ​

8.1 安全 URL 处理 ​

8.2 表单模式安全 ​

引导

1 用户交互模型

2 能力

3 协议消息

3.1 引导请求

3.2 表单模式引导请求

3.2.1 请求的模式

3.2.2 示例：简单文本请求

3.2.3 示例：结构化数据请求

3.3 URL 模式引导请求

3.3.1 示例：请求敏感数据

3.4 URL 模式引导的完成通知

3.5 需要 URL 引导的错误

4 消息流程

4.1 表单模式流程

4.2 URL 模式流程

4.3 带引导需求错误的 URL 模式流程

5 响应操作

6 实现注意事项

6.1 状态性

6.2 用于敏感数据的 URL 模式引导

6.3 用于 OAuth 流程的 URL 模式引导

7 错误处理

8 安全注意事项

8.1 安全 URL 处理

8.2 表单模式安全