引出

• 表单模式 (Form mode)：服务器可以向用户请求结构化数据，并使用可选的 JSON 架构来验证响应。
• URL 模式 (URL mode)：服务器可以将用户引导至外部 URL 进行敏感交互，这些交互不得通过 MCP 客户端。

​

用户交互模型

​

功能

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

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

​

协议消息

​

信息引导请求

• "form"：带内 (In-band) 结构化数据收集，具有可选的架构验证。数据对客户端可见。
• "url"：通过 URL 导航进行的带外 (Out-of-band) 交互。除了 URL 本身以外的数据不会暴露给客户端。

​

表单模式引导请求

​

请求的架构 (Schema)

1. 字符串架构 (String Schema)
   复制

   {
     "type": "string",
     "title": "Display Name",
     "description": "Description text",
     "minLength": 3,
     "maxLength": 50,
     "pattern": "^[A-Za-z]+$",
     "format": "email",
     "default": "[email protected]"
   }
   
   支持的格式：email, uri, date, date-time
2. 数字架构 (Number Schema)
   复制

   {
     "type": "number", // or "integer"
     "title": "Display Name",
     "description": "Description text",
     "minimum": 0,
     "maximum": 100,
     "default": 50
   }
   
3. 布尔架构 (Boolean Schema)
   复制

   {
     "type": "boolean",
     "title": "Display Name",
     "description": "Description text",
     "default": false
   }
   
4. 枚举架构 (Enum Schema) 单选枚举（不带标题）：
   复制

   {
     "type": "string",
     "title": "Color Selection",
     "description": "Choose your favorite color",
     "enum": ["Red", "Green", "Blue"],
     "default": "Red"
   }
   
   单选枚举（带标题）
   复制

   {
     "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"
   }
   
   多选枚举（不带标题）
   复制

   {
     "type": "array",
     "title": "Color Selection",
     "description": "Choose your favorite colors",
     "minItems": 1,
     "maxItems": 2,
     "items": {
       "type": "string",
       "enum": ["Red", "Green", "Blue"]
     },
     "default": ["Red", "Green"]
   }
   
   多选枚举（带标题）
   复制

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

1. 生成适当的输入表单
2. 在发送前验证用户输入
3. 为用户提供更好的引导

​

示例：简单文本请求

{
  "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": "[email protected]",
      "age": 30
    }
  }
}

​

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

​

URL 模式引导的完成通知

• 必须 (MUST) 仅向发起引导请求的客户端发送通知。
• 必须 (MUST) 包含在原始 elicitation/create 请求中建立的 elicitationId。

• 必须 (MUST) 忽略引用未知或已完成 ID 的通知。
• 可以 (MAY) 等待此通知，以自动重试之前收到 URLElicitationRequiredError 的请求、更新用户界面或以其他方式继续交互。
• 如果通知未送达，应当 (SHOULD) 仍然提供手动控制项，让用户能够重试或取消原始请求（或以其他方式恢复与客户端的交互）。

​

示例

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

​

需要 URL 引导错误 (URL Elicitation Required Error)

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

1. 接受 (Accept) (action: "accept")：用户显式批准并提交了数据。
   • 对于表单模式：content 字段包含与请求架构匹配的提交数据。
   • 对于 URL 模式：省略 content 字段。
   • 示例：用户点击了“提交”、“确定”、“确认”等。
2. 拒绝 (Decline) (action: "decline")：用户显式拒绝了请求。
   • 通常省略 content 字段。
   • 示例：用户点击了“拒绝”、“拒绝接受”、“否”等。
3. 取消 (Cancel) (action: "cancel")：用户在未做出明确选择的情况下关闭了请求。
   • 通常省略 content 字段。
   • 示例：用户关闭了对话框、点击了外部区域、按下了 Esc 键、浏览器加载失败等。

• 接受：处理提交的数据。
• 拒绝：处理显式拒绝（例如，提供替代方案）。
• 取消：处理关闭操作（例如，稍后再次提示）。

​

实现注意事项

​

状态性 (Statefulness)

• 是否已收集所需信息（例如，通过表单模式引导获取用户的显示名称）。
• 资源访问的状态（例如，通过 URL 模式引导获取 API 密钥或支付流程）。

• 状态绝不能 (MUST NOT) 仅与会话 ID 关联。
• 状态存储必须 (MUST) 受到保护，防止未经授权的访问。
• 对于远程 MCP 服务器，在可能的情况下，用户标识必须 (MUST) 源自通过 MCP 授权 获取的凭据（例如 sub 声明）。

​

敏感数据的 URL 模式引导

1. 服务器将用户引导至一个安全的网页（通过 HTTPS 提供）。
2. 该页面在用户信任的域上呈现品牌化的表单 UI。
3. 用户直接将敏感凭据输入安全表单。
4. 服务器安全地存储凭据，并将其与用户的身份绑定。
5. 后续的 MCP 请求使用这些存储的凭据进行 API 访问。

​

OAuth 流程的 URL 模式引导

​

理解区别

• MCP 授权：MCP 客户端与 MCP 服务器之间所需的 OAuth 流程（在 授权规范 中涵盖）。
• 外部（第三方）授权：MCP 服务器与第三方资源服务器之间可选的授权，通过 URL 模式引导启动。

• OAuth 资源服务器（对 MCP 客户端而言）。
• OAuth 客户端（对第三方资源服务器而言）。

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

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

​

实现模式

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

​

错误处理

• 当请求在引导完成前无法处理时：-32042 (URLElicitationRequiredError)。

• 服务器发送了客户端能力中未声明模式的 elicitation/create 请求：-32602 (Invalid params)。

​

安全注意事项

1. 服务器必须 (MUST) 将引导请求与客户端及用户身份绑定。
2. 客户端必须 (MUST) 明确指示是哪个服务器在请求信息。
3. 客户端应当 (SHOULD) 实施用户批准控制项。
4. 客户端应当 (SHOULD) 允许用户随时拒绝引导请求。
5. 客户端应当 (SHOULD) 实施速率限制。
6. 客户端应当 (SHOULD) 以一种能清晰说明正在请求什么信息以及原因的方式呈现引导请求。

​

安全的 URL 处理

1. 绝不能 (MUST NOT) 在发送给客户端的 URL 引导请求的 URL 中包含有关最终用户的敏感信息，包括凭据、个人身份信息等。
2. 绝不能 (MUST NOT) 提供已预先验证可访问受保护资源的 URL，因为该 URL 可能会被恶意客户端用来冒充用户。
3. 在表单模式引导请求的任何字段中，不应当 (SHOULD NOT) 包含旨在可点击的 URL。
4. 对于非开发环境，应当 (SHOULD) 使用 HTTPS URL。

1. 绝不能 (MUST NOT) 自动预取 URL 或其任何元数据。
2. 未经用户明确同意，绝不能 (MUST NOT) 打开该 URL。
3. 必须 (MUST) 在征得同意前向用户显示完整的 URL 以供检查。
4. 必须 (MUST) 以安全的方式打开服务器提供的 URL，使客户端或 LLM 无法检查其内容或用户输入。例如，在 iOS 上，SFSafariViewController 是合适的，但 WkWebView 不合适。
5. 应当 (SHOULD) 突出显示 URL 的域名，以减轻子域名欺骗风险。
6. 对于歧义/可疑的 URI（即包含 Punycode 的 URI），应当 (SHOULD) 发出警告。
7. 除了 URL 引导请求中的 url 字段（具有上述限制）外，不应当 (SHOULD NOT) 将引导请求任何字段中的 URL 渲染为可点击状态。

​

标识用户

• 错误：将用户输入（如“我是 [email protected]”）视为权威标识。
• 正确：依靠 授权 来识别用户。

​

表单模式安全

1. 服务器绝不能 (MUST NOT) 通过表单模式请求敏感信息（密码、API 密钥等）。
2. 客户端应当 (SHOULD) 根据提供的架构验证所有响应。
3. 服务器应当 (SHOULD) 验证接收到的数据是否符合请求的架构。

​

网络钓鱼 (Phishing)

1. 连接到合法服务器的恶意用户 (Alice) 触发了一个引导请求。
2. 合法服务器生成了一个授权 URL，作为第三方授权服务器的 OAuth 客户端。
3. Alice 的客户端显示该 URL 并请求同意。
4. Alice 并没有点击链接，而是诱导同一合法服务器的受害用户 (Bob) 点击它。
5. Bob 打开链接并完成了授权，以为是在授权自己与该合法服务器的连接。
6. 合法服务器收到了来自第三方授权服务器的回调/重定向，并认为这是 Alice 的请求。
7. 访问第三方服务器的令牌被绑定到了 Alice 的会话和身份上，而不是 Bob 的，从而导致账号被接管。