引出 - Model Context Protocol 中文文档

Model Context Protocol (MCP) 为服务器在交互期间通过客户端向用户请求额外信息提供了标准化方式。该流程允许客户端保持对用户交互和数据共享的控制，同时让服务器能够动态收集必要信息。引出支持两种模式：

表单模式：服务器可以向用户请求结构化数据，并可选择使用 JSON schema 验证响应
URL 模式：服务器可以将用户引导至外部 URL，用于处理不得通过 MCP 客户端传递的敏感交互

用户交互模型

MCP 中的引出允许服务器实现交互式工作流，因为它支持在其他 MCP 服务器功能内部_嵌套_发生用户输入请求。实现可以自由地通过任何适合自身需求的界面模式公开引出；协议本身并不强制规定任何特定的用户交互模型。

出于信任与安全及安全性考虑：

服务器 MUST NOT 使用表单模式引出请求敏感信息，例如密码、API key、访问令牌或支付凭据
对于涉及此类敏感信息的交互，服务器 MUST 使用 URL 模式

此上下文中的“敏感信息”是指授予访问权限或授权交易的密钥和凭据。一般联系信息或个人资料信息（例如姓名、电子邮件地址或用户名）并非一概禁止；是否通过表单模式请求此类数据由服务器自行决定，并且应受用户可审查和拒绝的能力约束。MCP 客户端 MUST:

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

能力

支持引出的客户端在初始化期间 MUST 声明 elicitation 能力：

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

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

{
  "capabilities": {
    "elicitation": {}, // Equivalent to { "form": {} }
  },
}

声明 elicitation 能力的客户端 MUST 至少支持一种模式（form 或 url）。服务器 MUST NOT 发送客户端不支持的模式的引出请求。

协议消息

引出请求

为了向用户请求信息，服务器会发送 elicitation/create 请求。所有引出请求 MUST 包含以下参数：

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

mode 参数指定引出类型：

"form"：带内结构化数据收集，可选 schema 验证。数据会暴露给客户端。
"url"：通过 URL 导航进行带外交互。除 URL 本身之外，数据不会暴露给客户端。

为了向后兼容，服务器 MAY 在表单模式引出请求中省略 mode 字段。客户端 MUST 将没有 mode 字段的请求视为表单模式。

表单模式引出请求

表单模式引出允许服务器直接通过 MCP 客户端收集结构化数据。表单模式引出请求 MUST 指定 mode: "form" 或省略 mode 字段，并包含以下额外参数：

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

请求的 Schema

requestedSchema 参数允许服务器使用 JSON Schema 的受限子集定义预期响应的结构。为简化客户端用户体验，表单模式引出 schema 仅限于具有原始属性的扁平对象。 schema 限制为以下原始类型：

字符串 Schema

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

数字 Schema

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

布尔 Schema

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

Enum Schema 单选 enum（不带标题）：

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

单选 enum（带标题）：

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

多选 enum（不带标题）：

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

多选 enum（带标题）：

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

客户端可以使用此 schema 来：

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

所有原始类型都支持可选默认值，以提供合理的起点。支持默认值的客户端 SHOULD 使用这些值预填充表单字段。请注意，为简化客户端用户体验，复杂嵌套结构、对象数组（enum 之外）以及其他高级 JSON Schema 特性被有意不支持。

示例：简单文本请求

请求：

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

示例：结构化数据请求

请求：

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

响应：

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

URL Mode Elicitation Requests

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

URL 模式引出使服务器能够将用户引导至外部 URL，以处理不得通过 MCP 客户端传递的带外交互。这对于认证流程、支付处理以及其他敏感或安全操作至关重要。 URL 模式引出请求 MUST 指定 mode: "url" 和 message，并包含以下额外参数：

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

url 参数 MUST 包含有效 URL。

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

示例：请求敏感数据

此示例展示了 URL 模式引出请求如何将用户引导至安全 URL，让用户在那里提供敏感信息（例如 API key）。同一个请求也可以将用户引导至 OAuth 授权流程或支付流程；唯一差别是 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."
  }
}

响应：

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

带有 action: "accept" 的响应表示用户已同意该交互。它并不表示交互已经完成。该交互发生在带外；除非服务器发送表示完成的通知，否则客户端并不知道结果。

URL 模式引出的完成通知

当由 URL 模式引出启动的带外交互完成时，服务器 MAY 发送 notifications/elicitation/complete 通知。这允许客户端在适当情况下以编程方式作出反应。发送通知的服务器：

MUST 仅向发起引出请求的客户端发送通知。
MUST 包含原始 elicitation/create 请求中建立的 elicitationId。

客户端：

MUST 忽略引用未知 ID 或已完成 ID 的通知。
MAY 等待此通知，以自动重试收到 URLElicitationRequiredError 的请求、更新用户界面，或以其他方式继续交互。
如果通知始终未到达，SHOULD 仍提供手动控件，让用户重试或取消原始请求（或以其他方式恢复与客户端交互）。

示例

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

URL 引出必需错误

当某个请求必须等到引出完成后才能处理时，服务器 MAY 返回 URLElicitationRequiredError（代码 -32042），向客户端指示需要 URL 模式引出。除非需要 URL 模式引出，否则服务器 MUST NOT 返回此错误。该错误 MUST 包含一个引出列表，这些引出需要完成后才能重试原始请求。错误中返回的任何引出 MUST 都是 URL 模式引出，并且具有 elicitationId 属性。 错误响应：

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32042, // URL_ELICITATION_REQUIRED
    "message": "This request requires more information.",
    "data": {
      "elicitations": [
        {
          "mode": "url",
          "elicitationId": "550e8400-e29b-41d4-a716-446655440000",
          "url": "https://mcp.example.com/connect?elicitationId=550e8400-e29b-41d4-a716-446655440000",
          "message": "Authorization is required to access your Example Co files."
        }
      ]
    }
  }
}

消息流

表单模式流程

URL 模式流程

带引出必需错误的 URL 模式流程

响应动作

引出响应使用三动作模型，以清晰区分不同的用户动作。这些动作同时适用于表单和 URL 引出模式。

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "action": "accept", // or "decline" or "cancel"
    "content": {
      "propertyName": "value",
      "anotherProperty": 42
    }
  }
}

三个响应动作如下：

Accept（action: "accept"）：用户明确批准并随数据一起提交
- 对于表单模式：content 字段包含与请求 schema 匹配的已提交数据
- 对于 URL 模式：省略 content 字段
- 示例：用户点击 “Submit”、“OK”、“Confirm” 等
Decline（action: "decline"）：用户明确拒绝请求
- 通常省略 content 字段
- 示例：用户点击 “Reject”、“Decline”、“No” 等
Cancel（action: "cancel"）：用户关闭了界面，但没有明确选择
- 通常省略 content 字段
- 示例：用户关闭对话框、点击外部、按下 Escape、浏览器加载失败等

服务器应适当地处理每种状态：

Accept：处理已提交数据
Decline：处理明确拒绝（例如提供替代方案）
Cancel：处理关闭/取消（例如稍后再次提示）

实现注意事项

状态性

引出的大多数实际用途都要求服务器维护关于用户的状态：

是否已收集必需信息（例如通过表单模式引出收集用户显示名称）
资源访问状态（例如通过 URL 模式引出处理 API key 或支付流程）

实现引出的服务器 MUST 遵循安全最佳实践文档中的指南，将此状态与各个用户安全关联。具体而言：

状态 MUST NOT 仅与会话 ID 关联
状态存储 MUST 防止未经授权的访问
对于远程 MCP 服务器，用户标识在可能时 MUST 派生自通过 MCP 授权获取的凭据（例如 sub claim）

本节示例是非规范性的，用于说明引出的潜在用途。实现者应在保持安全最佳实践的同时，根据其具体需求调整这些模式。

用于敏感数据的 URL 模式引出

对于与需要敏感信息（例如凭据、支付信息）的外部 API 交互的服务器， URL 模式引出提供了一种安全机制，使用户能够提供此信息而不将其暴露给 MCP 客户端。在此模式中：

服务器将用户引导至安全网页（通过 HTTPS 提供）
该页面在用户信任的域名上展示品牌化表单 UI
用户直接在安全表单中输入敏感凭据
服务器安全存储凭据，并将其绑定到用户身份
后续 MCP 请求使用这些已存储凭据访问 API

这种方式确保敏感凭据永远不会经过 LLM 上下文、MCP 客户端或任何中间 MCP 服务器，从而降低通过客户端日志记录或其他攻击向量暴露的风险。

用于 OAuth 流程的 URL 模式引出

URL 模式引出支持一种模式：MCP 服务器作为第三方资源服务器的 OAuth 客户端。由 URL 模式引出启用的外部 API 授权独立于 MCP 授权。 MCP 服务器 MUST NOT 依赖 URL 模式引出来为自身授权用户。

理解区别

MCP 授权：MCP 客户端与 MCP 服务器之间必需的 OAuth 流程（见授权规范）
外部（第三方）授权：MCP 服务器与第三方资源服务器之间的可选授权，通过 URL 模式引出启动

在外部授权中，服务器同时充当：

OAuth 资源服务器（面向 MCP 客户端）
OAuth 客户端（面向第三方资源服务器）

示例场景：

MCP 客户端连接到 MCP 服务器
MCP 服务器集成了多个不同的第三方服务
当 MCP 客户端调用需要访问第三方服务的工具时，MCP 服务器需要该服务的凭据

关键安全要求如下：

第三方凭据 MUST NOT 经由 MCP 客户端传输：客户端绝不能看到第三方凭据，以保护安全边界
MCP 服务器 MUST NOT 将客户端凭据用于第三方服务：这会构成 token passthrough，而这是被禁止的
用户 MUST 直接授权 MCP 服务器：交互发生在 MCP 协议之外，不涉及 MCP 客户端
MCP 服务器负责 token：MCP 服务器负责存储和管理通过 URL 模式引出获得的第三方 token（换言之，MCP 服务器必须是有状态的）。

通过 URL 模式引出获得的凭据不同于 MCP 客户端使用的 MCP 服务器凭据。 MCP 服务器 MUST NOT 将通过 URL 模式引出获得的凭据传输给 MCP 客户端。

如需更多背景，请参阅安全最佳实践文档中的 token passthrough 章节，了解为什么 MCP 服务器不能充当透传代理。

实现模式

通过 URL 模式引出实现外部授权时：

MCP 服务器作为第三方服务的 OAuth 客户端生成授权 URL
MCP 服务器存储内部状态，将引出请求与用户身份关联（绑定）。
MCP 服务器向客户端发送 URL 模式引出请求，其中包含可启动授权流程的 URL。
用户直接与第三方授权服务器完成 OAuth 流程
第三方授权服务器重定向回 MCP 服务器
MCP 服务器安全存储第三方 token，并绑定到用户身份
未来的 MCP 请求可以利用这些已存储 token 访问第三方资源服务器的 API

以下是此模式可能如何实现的非规范性示例：此模式在支持与需要用户授权的第三方服务进行丰富集成的同时，保持了清晰的安全边界。

Error Handling

服务器 MUST 针对常见失败情况返回标准 JSON-RPC 错误：

当某个请求必须等到引出完成后才能处理时：-32042（URLElicitationRequiredError）

客户端 MUST 针对常见失败情况返回标准 JSON-RPC 错误：

服务器发送的 elicitation/create 请求使用了客户端能力中未声明的模式：-32602（Invalid params）

安全注意事项

服务器 MUST 将引出请求绑定到客户端和用户身份
客户端 MUST 清楚指示哪个服务器正在请求信息
客户端 SHOULD 实现用户批准控制
客户端 SHOULD 允许用户随时拒绝引出请求
客户端 SHOULD 实现速率限制
客户端 SHOULD 以清楚说明请求了哪些信息以及为什么请求的方式展示引出请求

安全 URL 处理

请求引出的 MCP 服务器：

MUST NOT 在 URL 引出请求发送给客户端的 URL 中包含有关最终用户的敏感信息，包括凭据、个人身份识别信息等。
MUST NOT 提供可预认证访问受保护资源的 URL，因为恶意客户端可能使用该 URL 冒充用户。
SHOULD NOT 在表单模式引出请求的任何字段中包含意图可点击的 URL。
SHOULD 在非开发环境中使用 HTTPS URL。

这些服务器要求确保客户端实现对于何时向用户展示 URL 有明确规则，从而可以一致地应用下面的客户端规则。实现 URL 模式引出的客户端 MUST 谨慎处理 URL，防止用户在不知情的情况下点击恶意链接。处理 URL 模式引出请求时，MCP 客户端：

MUST NOT 自动预取 URL 或其任何元数据。
MUST NOT 在未获得用户明确同意的情况下打开 URL。
MUST 在获得同意前向用户显示完整 URL 以供检查。
MUST 以安全方式打开服务器提供的 URL，且该方式不能让客户端或 LLM 检查内容或用户输入。例如，在 iOS 上，SFSafariViewController 是合适的，而 WkWebView 不合适。
SHOULD 高亮 URL 的域名，以缓解子域名欺骗。
SHOULD 对含糊/可疑 URI（即包含 Punycode 的 URI）发出警告。
SHOULD NOT 将引出请求任何字段中的 URL 渲染为可点击，URL 引出请求中的 url 字段除外（并需遵守上文详述的限制）。

识别用户

服务器 MUST NOT 在未经服务器验证的情况下依赖客户端提供的用户标识，因为这可能被伪造。相反，服务器 SHOULD 遵循安全最佳实践。非规范性示例：

错误：将“我是 joe@example.com”这样的用户输入视为权威信息
正确：依赖授权来识别用户

表单模式安全

服务器 MUST NOT 通过表单模式请求敏感信息（密码、API key 等）
客户端 SHOULD 根据提供的 schema 验证所有响应
服务器 SHOULD 验证收到的数据是否与请求的 schema 匹配

钓鱼攻击

URL 模式引出会返回一个 URL，攻击者可以将其发送给受害者。 MCP 服务器在接受信息前 MUST 验证打开该 URL 的用户身份。通常，身份验证通过利用 MCP 授权服务器来识别用户完成，例如通过浏览器中的会话 cookie 或等效机制。例如，URL 模式引出可用于执行 OAuth 流程，其中服务器充当另一个资源服务器的 OAuth 客户端。如果没有适当缓解措施，可能发生以下钓鱼攻击：

连接到良性服务器的恶意用户（Alice）触发引出请求
良性服务器作为第三方授权服务器的 OAuth 客户端生成授权 URL
Alice 的客户端显示该 URL 并请求同意
Alice 没有点击链接，而是诱骗同一良性服务器的受害用户（Bob）点击该链接
Bob 打开链接并完成授权，以为自己正在授权自己与良性服务器的连接
良性服务器收到第三方授权服务器的回调/重定向，并假定这是 Alice 的请求
第三方服务器的 token 被绑定到 Alice 的会话和身份，而不是 Bob 的会话和身份，导致账号接管

为防止此攻击，服务器 MUST 确保启动引出请求的用户（通过 MCP 客户端访问服务器的最终用户）与完成授权流程的用户是同一用户。实现这一点的方法有很多，最佳方式取决于具体实现。作为一个常见的非规范性示例，考虑 MCP 服务器可通过 Web 访问，并希望执行第三方授权码流程的情况。为防止钓鱼攻击，服务器会创建指向 https://mcp.example.com/connect?elicitationId=... 的 URL 模式引出，而不是直接指向第三方授权端点。这个“connect URL”必须确保打开页面的用户与生成引出的目标用户是同一用户。例如，它会检查用户是否拥有有效的会话 cookie，并且该会话 cookie 对应的用户正是使用 MCP 客户端生成 URL 模式引出的用户。这可以通过比较来自 MCP 服务器授权服务器的权威主体（sub claim）与会话 cookie 中的主体来完成。一旦该页面确认是同一用户，就可以将用户发送到第三方授权服务器 https://example.com/authorize?...，在那里完成正常 OAuth 流程。在其他情况下，服务器可能无法通过 Web 访问，也可能无法使用会话 cookie 来识别用户。在这种情况下，服务器必须使用不同机制来确认打开引出 URL 的用户与生成引出的目标用户是同一用户。在所有实现中，服务器 MUST 确保用于确定用户身份的机制能够抵御攻击者修改引出 URL 的攻击。

基础协议

客户端能力

服务器能力

引出

用户交互模型

能力

协议消息

引出请求

表单模式引出请求

请求的 Schema

示例：简单文本请求

示例：结构化数据请求

URL Mode Elicitation Requests

示例：请求敏感数据

URL 模式引出的完成通知

示例

URL 引出必需错误

消息流

表单模式流程

URL 模式流程

带引出必需错误的 URL 模式流程

响应动作

实现注意事项

状态性

用于敏感数据的 URL 模式引出

用于 OAuth 流程的 URL 模式引出

理解区别

实现模式

Error Handling

安全注意事项

安全 URL 处理

识别用户

表单模式安全

钓鱼攻击

​用户交互模型

​能力

​协议消息

​引出请求

​表单模式引出请求

​请求的 Schema

​示例：简单文本请求

​示例：结构化数据请求

​URL Mode Elicitation Requests

​示例：请求敏感数据

​URL 模式引出的完成通知

​示例

​URL 引出必需错误

​消息流

​表单模式流程

​URL 模式流程

​带引出必需错误的 URL 模式流程

​响应动作

​实现注意事项

​状态性

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

​用于 OAuth 流程的 URL 模式引出

​理解区别

​实现模式

​Error Handling

​安全注意事项

​安全 URL 处理

​识别用户

​表单模式安全

​钓鱼攻击

用户交互模型

能力

协议消息

引出请求

表单模式引出请求

请求的 Schema

示例：简单文本请求

示例：结构化数据请求

URL Mode Elicitation Requests

示例：请求敏感数据

URL 模式引出的完成通知

示例

URL 引出必需错误

消息流

表单模式流程

URL 模式流程

带引出必需错误的 URL 模式流程

响应动作

实现注意事项

状态性

用于敏感数据的 URL 模式引出

用于 OAuth 流程的 URL 模式引出

理解区别

实现模式

Error Handling

安全注意事项

安全 URL 处理

识别用户

表单模式安全

钓鱼攻击