SEP-1488:混合身份验证服务器的工具元数据中的 securitySchemes

SEP: securitySchemes in Tool Metadata for Mixed-Auth Servers

Authors: Duke Kim ([email protected]), Thiago Hirai ([email protected]) Status: Draft Sponsor: Nick Cooper ([email protected]) Type: Standards Track Created: 2025-09-17

Summary

我们建议在MCP工具描述符中添加一个可选的securitySchemes字段。这样就可以使服务器标记哪些工具对所有人开放，哪些需要身份验证。客户端可以：

• 显示清晰的用户界面标签（例如“公开” vs “需要登录”）。
• 要求用户在调用受保护的工具之前登录。
• 从相同工具的公开和经过身份验证的版本中选择。 这是一个小的、向后兼容的更改。目前，我们只支持两种方案类型：
• "noauth" → 工具可以在不提供凭证的情况下调用
• "oauth2" → 工具需要OAuth 2.0（可选的作用域列表） 以后可以在不更改字段形状的情况下添加更多方案类型。

理由

目前，客户端只能通过尝试失败或阅读文档来发现需要身份验证。这不是很好。 通过每个工具声明securitySchemes，服务器可以：

• 改善用户体验：客户端事先知道某个工具是公开的还是需要身份验证。
• 指导流程：客户端可以在调用受保护的工具之前提示用户登录。
• 减少错误：服务器可以将工具标记为公开或受保护。
• 保持灵活性：以后添加新的身份验证方案（API 密钥、mTLS 等）很容易。

工具描述符更改

每个工具都可以在其tools/list响应中包含一个新的可选securitySchemes字段：

{
  "name": "get_weather",
  "title": "Weather Info",
  "description": "Get current weather for a location",
  "inputSchema": {
    "type": "object",
    "properties": { "location": { "type": "string" } },
    "required": ["location"]
  },
  "securitySchemes": [
    { "type": "noauth" },
    { "type": "oauth2", "scopes": ["weather.read"] }
  ]
}

字段定义

securitySchemes（数组，可选）

• 如果缺失 → 工具遵循服务器的默认策略。
• 如果为空数组 → 建议不要使用，与缺失相同。
• 如果存在且包含条目 → 列出支持的身份验证方案。

方案类型（到目前为止）：

• noauth: 不需要凭证。
• oauth2: 需要OAuth2；如果相关，可以列出作用域。

多个方案

• 工具可以同时列出noauth和oauth2，表示“匿名工作，但身份验证提供了更多功能”。
• 客户端可以选择任何他们可以满足的方案，通常更喜欢经过身份验证的方案。
• 服务器必须无论客户端元数据如何都执行身份验证规则。

示例

公开且可选身份验证:

{
  "name": "search",
  "title": "Public Search",
  "description": "Search public documents.",
  "inputSchema": { "type": "object", "properties": { "q": { "type": "string" } }, "required": ["q"] },
  "securitySchemes": [
    { "type": "noauth" },
    { "type": "oauth2", "scopes": ["search.read"] }
  ]
}

身份验证必需:

{
  "name": "create_doc",
  "title": "Create Document",
  "description": "Make a new doc in your account.",
  "inputSchema": { "type": "object", "properties":
…