鸭梨公共文档

主题

授权 ​

协议修订版本：2025-11-25

1. 简介 ​

1.1 目的和范围 ​

Model Context Protocol 在传输层提供授权功能，使 MCP 客户端能够代表资源所有者向受保护的 MCP 服务器发出请求。本规范定义了基于 HTTP 传输的授权流程。

1.2 协议要求 ​

授权对于 MCP 实现是可选的。如果支持授权：

  • 使用基于 HTTP 传输的实现应该符合本规范。
  • 使用 STDIO 传输的实现不应该遵循本规范，而应该从环境中检索凭据。
  • 使用其他传输的实现必须遵循其协议的既定安全最佳实践。

1.3 标准合规性 ​

此授权机制基于以下已建立的规范，但实现了其功能的选定子集，以确保安全性和互操作性，同时保持简单性：

2. 角色 ​

受保护的 MCP 服务器 充当 OAuth 2.1 资源服务器，能够接受并响应使用访问令牌的受保护资源请求。

MCP 客户端 充当 OAuth 2.1 客户端，代表资源所有者发出受保护的资源请求。

授权服务器 负责与用户交互（如有必要）并颁发用于 MCP 服务器的访问令牌。授权服务器的实现细节超出了本规范的范围。

3. 概述 ​

  1. 授权服务器必须为机密客户端和公共客户端实现具有适当安全措施的 OAuth 2.1。

  2. 授权服务器和 MCP 客户端应该支持 OAuth Client ID Metadata Documents。

  3. 授权服务器和 MCP 客户端可以支持 OAuth 2.0 动态客户端注册协议 (RFC7591)。

  4. MCP 服务器必须实现 OAuth 2.0 受保护资源元数据 (RFC9728)。MCP 客户端必须使用 OAuth 2.0 受保护资源元数据进行授权服务器发现。

  5. MCP 授权服务器必须提供以下至少一种发现机制：

    MCP 客户端必须支持这两种发现机制以获取与授权服务器交互所需的信息。

4. 授权服务器发现 ​

4.1 授权服务器位置 ​

MCP 服务器必须实现 OAuth 2.0 受保护资源元数据 (RFC9728) 规范来指示授权服务器的位置。MCP 服务器返回的受保护资源元数据文档必须包含 authorization_servers 字段，其中包含至少一个授权服务器。

4.2 受保护资源元数据发现要求 ​

MCP 服务器必须实现以下发现机制之一，向 MCP 客户端提供授权服务器位置信息：

  1. WWW-Authenticate 头：在返回 401 Unauthorized 响应时，在 resource_metadata 下的 WWW-Authenticate HTTP 头中包含资源元数据 URL。

  2. Well-Known URI：在 well-known URI 上提供元数据，如 RFC9728 所规定。

MCP 服务器应该在 WWW-Authenticate 头中包含 scope 参数，以指示访问资源所需的作用域。

示例 401 响应带作用域指南：

http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         scope="files:read"

4.3 授权服务器元数据发现 ​

为处理不同的发行者 URL 格式并确保与 OAuth 2.0 授权服务器元数据和 OpenID Connect Discovery 1.0 规范的互操作性，MCP 客户端在发现授权服务器元数据时必须尝试多个 well-known 端点。

对于带有路径组件的发行者 URL（例如 https://auth.example.com/tenant1），客户端必须按以下优先顺序尝试端点：

  1. OAuth 2.0 授权服务器元数据带路径插入：https://auth.example.com/.well-known/oauth-authorization-server/tenant1
  2. OpenID Connect Discovery 1.0 带路径插入：https://auth.example.com/.well-known/openid-configuration/tenant1
  3. OpenID Connect Discovery 1.0 路径追加：https://auth.example.com/tenant1/.well-known/openid-configuration

5. 客户端注册方法 ​

MCP 支持三种客户端注册机制。根据您的场景选择：

  • Client ID Metadata Documents：当客户端和服务器没有预先存在的关系时（最常见）
  • 预注册：当客户端和服务器有现有关系时
  • 动态客户端注册：用于向后兼容性或特定需求

支持所有选项的客户端应该遵循以下优先顺序：

  1. 如果客户端有可用的预注册客户端信息，则使用它
  2. 如果授权服务器指示服务器支持（通过 OAuth 授权服务器元数据中的 client_id_metadata_document_supported），则使用 Client ID Metadata Documents
  3. 如果授权服务器支持（通过 OAuth 授权服务器元数据中的 registration_endpoint），则使用动态客户端注册作为回退
  4. 如果没有其他选项可用，则提示用户输入客户端信息

5.1 Client ID Metadata Documents ​

MCP 客户端和授权服务器应该支持 OAuth Client ID Metadata Documents。这种方法使客户端能够使用 HTTPS URL 作为客户端标识符，其中 URL 指向包含客户端元数据的 JSON 文档。

示例元数据文档：

json
{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "client_uri": "https://app.example.com",
  "logo_uri": "https://app.example.com/logo.png",
  "redirect_uris": [
    "http://127.0.0.1:3000/callback",
    "http://localhost:3000/callback"
  ],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

5.2 预注册 ​

MCP 客户端应该支持静态客户端凭据选项，例如由预注册流程提供的凭据。

5.3 动态客户端注册 ​

MCP 客户端和授权服务器可以支持 OAuth 2.0 动态客户端注册协议 RFC7591，以允许 MCP 客户端在没有用户交互的情况下获取 OAuth 客户端 ID。

6. 作用域选择策略 ​

在实现授权流程时，MCP 客户端应该遵循最小权限原则，仅请求其预期操作所需的作用域。在初始授权握手期间，MCP 客户端应该遵循此作用域选择的优先顺序：

  1. 使用 401 响应中初始 WWW-Authenticate 头的 scope 参数（如果提供）
  2. 如果 scope 不可用，则使用受保护资源元数据文档中 scopes_supported 定义的所有作用域，如果 scopes_supported 未定义则省略 scope 参数。

7. 授权流程步骤 ​

完整的授权流程如下：

8. 资源参数实现 ​

MCP 客户端必须实现 RFC 8707 中定义的 OAuth 2.0 资源指示器，以明确指定请求令牌的目标资源。resource 参数：

  1. 必须包含在授权请求和令牌请求中。
  2. 必须标识客户端打算使用令牌的 MCP 服务器。
  3. 必须使用 MCP 服务器的规范 URI。

9. 访问令牌使用 ​

9.1 令牌要求 ​

向 MCP 服务器发出请求时的访问令牌处理必须符合 OAuth 2.1 第 5 节"资源请求" 中定义的要求。

  1. MCP 客户端必须使用 Authorization 请求头字段：

    text
    Authorization: Bearer <access-token>

    注意，授权必须包含在从客户端到服务器的每个 HTTP 请求中，即使它们属于同一逻辑会话。

  2. 访问令牌不得包含在 URI 查询字符串中

9.2 令牌处理 ​

MCP 服务器必须验证访问令牌是专门为它们作为预期受众颁发的。如果验证失败，服务器必须根据错误处理要求进行响应。无效或过期的令牌必须收到 HTTP 401 响应。

MCP 服务器必须仅接受专门用于其自身资源的有效令牌。

MCP 服务器不得接受或传递任何其他令牌。

10. 错误处理 ​

服务器必须为授权错误返回适当的 HTTP 状态码：

状态码描述用途
401Unauthorized需要授权或令牌无效
403Forbidden无效作用域或权限不足
400Bad Request格式错误的授权请求

10.1 作用域挑战处理 ​

当客户端使用作用域不足的访问令牌发出请求时，服务器应该响应：

  • HTTP 403 Forbidden 状态码
  • WWW-Authenticate 头，带 Bearer 方案和附加参数：
    • error="insufficient_scope" - 指示特定类型的授权失败
    • scope="required_scope1 required_scope2" - 指定操作所需的最小作用域

示例作用域不足响应：

http
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
                         scope="files:read files:write user:profile",
                         resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         error_description="Additional file write permission required"

11. 安全考虑 ​

实现必须遵循 OAuth 2.1 第 7 节"安全考虑" 中规定的 OAuth 2.1 安全最佳实践。

11.1 令牌受众绑定和验证 ​

  • MCP 客户端必须在授权和令牌请求中包含 resource 参数
  • MCP 服务器必须验证呈现给它们的令牌是专门为它们的使用而颁发的

11.2 令牌盗窃 ​

客户端和服务器必须实施安全令牌存储并遵循 OAuth 最佳实践。

授权服务器应该颁发短期访问令牌以减少泄露令牌的影响。

11.3 通信安全 ​

  1. 所有授权服务器端点必须通过 HTTPS 提供服务。
  2. 所有重定向 URI 必须是 localhost 或使用 HTTPS。

11.4 授权码保护 ​

MCP 客户端必须根据 OAuth 2.1 第 7.5.2 节 实现 PKCE，并且必须在继续授权之前验证 PKCE 支持。

MCP 客户端必须在技术上能够时使用 S256 代码挑战方法。

11.5 开放重定向 ​

MCP 客户端必须在授权服务器注册重定向 URI。

授权服务器必须验证精确的重定向 URI 与预注册值匹配，以防止重定向攻击。

11.6 访问令牌权限限制 ​

MCP 服务器必须在处理请求之前验证访问令牌，确保访问令牌是专门为 MCP 服务器颁发的，并采取所有必要步骤确保不向未授权方返回数据。

如果 MCP 服务器向上游 API 发出请求，它可能充当它们的 OAuth 客户端。在上游 API 使用的访问令牌是单独的令牌，由上游授权服务器颁发。MCP 服务器不得传递它从 MCP 客户端收到的令牌。

12. MCP 授权扩展 ​

核心协议有几个授权扩展定义了额外的授权机制。这些扩展是：

  • 可选的 - 实现可以选择采用这些扩展
  • 附加的 - 扩展不修改或破坏核心协议功能；它们添加新功能同时保留核心协议行为
  • 可组合的 - 扩展是模块化的，设计为可以一起工作而不冲突
  • 独立版本化 - 扩展遵循核心 MCP 版本周期，但可能根据需要采用独立版本控制

支持的扩展列表可以在 MCP 授权扩展 仓库中找到。