授权 - Model Context Protocol 中文文档

Introduction

Purpose and Scope

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

Protocol Requirements

授权对于 MCP 实现是 OPTIONAL 的。支持授权时：

使用基于 HTTP 的传输的实现 SHOULD 遵循本规范。
使用 STDIO 传输的实现 SHOULD NOT 遵循本规范，而应从环境中检索凭据。
使用替代传输的实现 MUST 遵循其协议已建立的安全最佳实践。

Standards Compliance

此授权机制基于下列既有规范，但只实现其中选定的功能子集，以在保持简单性的同时确保安全性和互操作性：

OAuth 2.1 IETF DRAFT (draft-ietf-oauth-v2-1-13)
OAuth 2.0 Bearer Token Usage (RFC6750)
OAuth 2.0 Authorization Server Metadata (RFC8414)
OAuth 2.0 Dynamic Client Registration Protocol (RFC7591)
Resource Indicators for OAuth 2.0 (RFC8707)
OAuth 2.0 Protected Resource Metadata (RFC9728)
OAuth 2.0 Authorization Server Issuer Identification (RFC9207)
OAuth Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document-00)
OpenID Connect Discovery 1.0
OpenID Connect Dynamic Client Registration 1.0 (OpenID Connect Registration)

Roles

受保护的 MCP 服务器 充当 OAuth 2.1 资源服务器，能够使用访问令牌接受并响应受保护资源请求。 MCP 客户端 充当 OAuth 2.1 客户端，代表资源所有者发起受保护资源请求。 授权服务器 负责与用户交互（如有必要），并颁发供 MCP 服务器使用的访问令牌。授权服务器的实现细节超出本规范范围。它可以与资源服务器共同托管，也可以由独立实体托管。授权服务器发现规定 MCP 服务器如何向客户端指示其对应授权服务器的位置。

概览

授权服务器 MUST 实现 OAuth 2.1，并为机密客户端和公共客户端采用适当的安全措施。
授权服务器和 MCP 客户端 SHOULD 支持 OAuth Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document-00).
授权服务器和 MCP 客户端 MAY 支持 OAuth 2.0 Dynamic Client Registration Protocol (RFC7591)。请注意， Dynamic Client Registration 已弃用，保留它是为了与不支持 Client ID Metadata Documents 的授权服务器保持向后兼容。
MCP 服务器 MUST 实现 OAuth 2.0 Protected Resource Metadata (RFC9728)。 MCP 客户端 MUST 使用 OAuth 2.0 受保护资源元数据进行授权服务器发现。
MCP 授权服务器 MUST 至少提供以下发现机制之一：
- OAuth 2.0 Authorization Server Metadata (RFC8414)
- OpenID Connect Discovery 1.0
MCP 客户端 MUST 同时支持这两种发现机制，以获得与授权服务器交互所需的信息。

Authorization Server Discovery

MCP 服务器通过 OAuth 2.0 受保护资源元数据公布其关联的授权服务器，MCP 客户端通过授权服务器元数据发现来确定授权服务器端点和受支持能力。实现 MUST 遵循授权服务器发现中定义的规范性发现要求。

Client Registration

发起授权流程之前，MCP 客户端 MUST 通过三种注册机制之一获取客户端 ID：Client ID Metadata Documents、pre-registration 或 Dynamic Client Registration，并遵循客户端注册中定义的要求和选择优先级。

Scope Selection Strategy

MCP 服务器 SHOULD 按照 RFC 6750 Section 3 的定义，在 WWW-Authenticate 标头中包含 scope 参数，以指示访问资源所需的作用域。这会立即向客户端提供授权期间应请求哪些适当作用域的指导，遵循最小权限原则，并防止客户端请求过多权限。 WWW-Authenticate 质询中包含的作用域 MAY 与 scopes_supported 匹配，可以是它的子集或超集，也可以是既非严格子集也非超集的另一组作用域。客户端 MUST NOT 假定被质询的作用域集合与 scopes_supported 之间存在任何特定集合关系。客户端 MUST 将质询中提供的作用域视为当前操作的权威要求。这些作用域是满足当前请求所必需的。重新授权时，客户端 SHOULD 将这些作用域与此前已授予的任何作用域一并包含，以避免丢失其他操作所需的权限（请参见 Step-up 授权流程）。服务器 SHOULD 努力保持其构造作用域集合的方式一致，但不要求通过 scopes_supported 暴露每个动态颁发的作用域。带有作用域指导的 401 响应示例：

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

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

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

这种方法适应 MCP 客户端的通用性质，因为它们通常缺乏领域特定知识，无法对单个作用域选择做出充分判断。请求所有可用作用域允许授权服务器和最终用户在同意流程中确定适当权限。这种方法在遵循最小权限原则的同时最大限度减少用户阻力。scopes_supported 字段旨在表示基本功能所需的最小作用域集合（请参见作用域最小化），额外作用域则通过作用域质询处理部分描述的 step-up 授权流程步骤逐步请求。

Authorization Flow Steps

流程中显示的注册步骤使用客户端注册中定义的机制之一。完整授权流程如下：

Authorization Response Validation

重定向用户代理之前，客户端 MUST 记录所选授权服务器已验证元数据文档中的 issuer 值（请参见授权服务器元数据发现），并将其与用于存储 PKCE code verifier（以及 state 值，如果使用）的同一按请求记录关联。本节中的验证依赖所记录值的真实性；如果预期 issuer 来自未经验证的来源，则它不提供保护。 MCP 授权服务器 SHOULD 按照 RFC9207 Section 2 的定义，在授权响应（包括错误响应）中包含 iss 参数。包含 iss 参数的授权服务器 MUST 通过在其元数据中将 authorization_response_iss_parameter_supported 设置为 true 来公布这一点（RFC9207 Section 2.3）。收到授权响应时，MCP 客户端 MUST 在将授权码传输到任何令牌端点之前，应用 RFC9207 Section 2.4 中的验证：

`authorization_response_iss_parameter_supported`	响应中的 `iss`	客户端动作
`true`	存在	使用简单字符串比较与记录的 issuer 比较（RFC3986 Section 6.2.1）
`true`	不存在	拒绝该响应
`false` 或不存在	存在	使用简单字符串比较与记录的 issuer 比较（RFC3986 Section 6.2.1）
`false` 或不存在	不存在	继续

第三行应用了 RFC9207 Section 2.4 中的本地策略规定：本规范会将存在的 iss 与记录的 issuer 比较，而不管元数据是否公布支持，以适应先发出 iss、后更新元数据的授权服务器。本规范未来的修订预计会将授权服务器包含 iss 的要求从 SHOULD 升级为 MUST。鼓励实现者现在就发出并验证 iss，以简化该过渡；在该修订定义升级路径之前，客户端在缺少 iss 时的拒绝行为仍将以 authorization_response_iss_parameter_supported 为依据。按照 RFC 9207 Section 2.4 从 application/x-www-form-urlencoded 响应中解码 iss 值后，客户端在比较前 MUST NOT 应用 scheme 或 host 大小写折叠、默认端口省略、尾随斜杠处理或百分号编码规范化（RFC 3986 Sections 6.2.2-6.2.3）。此验证同样适用于错误响应；如果不匹配，客户端 MUST NOT 处理或显示 error、error_description 或 error_uri。

Resource Parameter Implementation

MCP 客户端 MUST 实现 RFC 8707 中定义的 OAuth 2.0 Resource Indicators，以显式指定正在为其请求令牌的目标资源。resource 参数：

MUST 同时包含在授权请求和令牌请求中。
MUST 标识客户端打算与该令牌一起使用的 MCP 服务器。
MUST 使用 RFC 8707 Section 2 中定义的 MCP 服务器规范 URI。

Canonical Server URI

就本规范而言，MCP 服务器的规范 URI 定义为 RFC 8707 Section 2 中规定的资源标识符，并与 RFC 9728 中的 resource 参数保持一致。 MCP 客户端 SHOULD 遵循 RFC 8707 中的指导，为其打算访问的 MCP 服务器提供尽可能具体的 URI。虽然规范形式使用小写的 scheme 和 host 组件，但实现 SHOULD 接受大写的 scheme 和 host 组件，以增强稳健性和互操作性。有效规范 URI 示例：

https://mcp.example.com/mcp
https://mcp.example.com
https://mcp.example.com:8443
https://mcp.example.com/server/mcp（当需要路径组件来标识单个 MCP 服务器时）

无效规范 URI 示例：

mcp.example.com（缺少 scheme）
https://mcp.example.com#fragment（包含 fragment）

注意： 根据 RFC 3986，https://mcp.example.com/（带尾随斜杠）和 https://mcp.example.com（不带尾随斜杠）在技术上都是有效的绝对 URI；但除非尾随斜杠对特定资源具有语义意义，否则实现 SHOULD 一致使用不带尾随斜杠的形式，以获得更好的互操作性。

例如，如果访问位于 https://mcp.example.com 的 MCP 服务器，授权请求会包含：

&resource=https%3A%2F%2Fmcp.example.com

无论授权服务器是否支持此参数，MCP 客户端 MUST 发送它。

Access Token Usage

Token Requirements

向 MCP 服务器发起请求时的访问令牌处理 MUST 符合 OAuth 2.1 Section 5 “Resource Requests” 中定义的要求。具体而言：

MCP 客户端 MUST 使用 OAuth 2.1 Section 5.1.1 中定义的 Authorization 请求标头字段：

Authorization: Bearer <access-token>

请注意，每个从客户端到服务器的 HTTP 请求中都 MUST 包含授权信息。

访问令牌 MUST NOT 包含在 URI 查询字符串中

请求示例：

GET /mcp HTTP/1.1
Host: mcp.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token Handling

MCP 服务器作为 OAuth 2.1 资源服务器，MUST 按照 OAuth 2.1 Section 5.2 中的描述验证访问令牌。MCP 服务器 MUST 根据 RFC 8707 Section 2 验证访问令牌是专门以它们为预期受众颁发的。如果验证失败，服务器 MUST 按照 OAuth 2.1 Section 5.3 的错误处理要求响应。无效或过期的令牌 MUST 收到 HTTP 401 响应。 MCP 客户端 MUST NOT 向 MCP 服务器发送非该 MCP 服务器授权服务器颁发的令牌。 MCP 服务器 MUST 只接受对其自身资源有效的令牌。 MCP 服务器 MUST NOT 接受或传递任何其他令牌。

Refresh Tokens

本节为 MCP 客户端和 MCP 服务器在处理或颁发 OAuth 与 OpenID Connect 刷新令牌时提供指导。需要刷新令牌的 MCP 客户端：

MUST 按照 OAuth 2.1 Section 4.3 的规定，在传输和存储中保持刷新令牌机密
SHOULD 在其 grant_types 客户端元数据中包含 refresh_token
当授权服务器元数据的 scopes_supported 中包含 offline_access 时，MAY 将 offline_access 添加到授权请求和令牌请求的 scope 参数中
MUST NOT 假定一定会颁发刷新令牌；AS 保留决定权

MCP 服务器（受保护资源）SHOULD NOT 在 WWW-Authenticate scope 或受保护资源元数据的 scopes_supported 中包含 offline_access，因为刷新令牌不是资源要求。

Error Handling

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

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

Scope Challenge Handling

本节涵盖运行时操作期间 insufficient scope 错误的处理方式，此时客户端已经拥有令牌，但需要额外权限。这遵循 OAuth 2.1 Section 5 中定义的错误处理模式，并利用 RFC 9728 (OAuth 2.0 Protected Resource Metadata) 中的元数据字段。

Runtime Insufficient Scope Errors

当客户端在运行时操作期间使用作用域不足的访问令牌发起请求时，服务器 SHOULD 以如下方式响应：

HTTP 403 Forbidden 状态码（根据 RFC 6750 Section 3.1）
带有 Bearer scheme 和附加参数的 WWW-Authenticate 标头：
- error="insufficient_scope" - 表示授权失败的具体类型
- scope="required_scope1 required_scope2" - 指定该操作所需的最小作用域
resource_metadata - 受保护资源元数据文档的 URI（与 401 响应保持一致）
- error_description（可选）- 人类可读的错误描述

服务器作用域管理：响应 insufficient scope 错误时，服务器 SHOULD 按照 RFC 6750 Section 3.1，在 scope 参数中包含满足当前操作所需的作用域。scope 属性描述访问所请求资源所需的作用域；服务器不需要包含客户端此前已授予的作用域。服务器可以灵活决定包含哪些作用域：

最小方法：仅包含触发错误的特定操作所需的作用域。
推荐方法：包含当前操作所需的作用域，以及通常一起使用的相关作用域，以减少 step-up 授权轮次。
扩展方法：包含当前操作所需的作用域、相关作用域，以及服务器预期客户端近期可能需要的任何其他作用域。

选择取决于服务器对用户体验影响和授权阻力的评估。无论选择哪种方法，服务器 SHOULD 在单个质询中包含当前操作所需的所有作用域。增量质询（先返回一个缺失作用域，再在后续重试中返回另一个）会迫使单个操作经历多次授权往返，并降低用户体验。所需作用域可以基于具体请求参数和上下文动态确定，但一旦确定，就应一起发出。服务器 SHOULD 在其作用域包含策略上保持一致，以向客户端提供可预测的行为。服务器在确定响应中包含哪些作用域时 SHOULD 考虑用户体验影响，因为配置错误的作用域可能需要频繁的用户交互。

跨操作的作用域累积是客户端侧责任。如 Step-up 授权流程中所述，客户端在发起重新授权时 SHOULD 计算此前请求的作用域与新质询作用域的并集。这允许服务器在客户端作用域集合方面保持无状态，同时确保客户端不会丢失此前授予的权限。

insufficient scope 响应示例：

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
                         scope="files:write",
                         resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         error_description="File write permission required for this operation"

Step-Up Authorization Flow

客户端会在初始授权期间或运行时收到与作用域相关的错误（insufficient_scope）。客户端 SHOULD 通过 step-up 授权流程请求具有更多作用域的新访问令牌来响应这些错误，或以其他适当方式处理错误。代表用户行事的客户端 SHOULD 尝试 step-up 授权流程。代表自身行事的客户端（client_credentials 客户端）MAY 尝试 step-up 授权流程，或立即中止请求。流程如下：

从授权服务器响应或 WWW-Authenticate 标头中解析错误信息
通过计算客户端此前请求的作用域集合与当前质询中作用域的并集，确定所需作用域。这确保当服务器按照 RFC 6750 Section 3.1 发出按操作划分的作用域质询时，此前授予的权限会被保留。客户端 MAY 还可以参考作用域选择策略获取初始作用域选择指导。
使用确定的作用域集合发起（重新）授权
使用新授权重试原始请求，重试次数不超过几次；若仍失败，则将其视为永久授权失败

客户端 SHOULD 实现重试限制，并且 SHOULD 跟踪作用域升级尝试，以避免同一资源和操作组合反复失败。

层级作用域：某些授权服务器定义作用域层级，其中较宽泛的作用域隐含较窄的作用域（例如，admin 作用域包含 read）。累积作用域时，客户端的并集可能包含语义上冗余的条目；例如，此前已授予宽泛作用域的令牌，可能又被质询一个它已经隐含的较窄作用域。客户端无需按层级去重；授权服务器通常会在令牌颁发期间规范化此类冗余。服务器方面在决定令牌是否足以执行某项操作时必须考虑层级，但这不影响它们在质询中发出的作用域。

安全 Considerations

本规范的实现 MUST 遵循安全注意事项中的规范性安全要求，涵盖令牌受众绑定与验证、令牌盗窃、通信安全、授权码保护、mix-up 和 confused deputy 攻击、开放重定向，以及 Client ID Metadata Document 安全。

MCP Authorization Extensions

核心协议有多个授权扩展，用于定义额外的授权机制。这些扩展是：

可选 - 实现可以选择采用这些扩展
增量 - 扩展不会修改或破坏核心协议功能；它们在保留核心协议行为的同时添加新能力
可组合 - 扩展是模块化的，并设计为可以无冲突地协同工作，允许实现同时采用多个扩展
独立版本化 - 扩展遵循核心 MCP 版本周期，但可按需采用独立版本控制

支持的扩展列表可在 MCP Authorization Extensions 仓库中找到。

基础协议

客户端能力

服务器能力

授权

Introduction

Purpose and Scope

Protocol Requirements

Standards Compliance

Roles

概览

Authorization Server Discovery

Client Registration

Scope Selection Strategy

Authorization Flow Steps

Authorization Response Validation

Resource Parameter Implementation

Canonical Server URI

Access Token Usage

Token Requirements

Token Handling

Refresh Tokens

Error Handling

Scope Challenge Handling

Runtime Insufficient Scope Errors

Step-Up Authorization Flow

安全 Considerations

MCP Authorization Extensions

​Introduction

​Purpose and Scope

​Protocol Requirements

​Standards Compliance

​Roles

​概览

​Authorization Server Discovery

​Client Registration

​Scope Selection Strategy

​Authorization Flow Steps

​Authorization Response Validation

​Resource Parameter Implementation

​Canonical Server URI

​Access Token Usage

​Token Requirements

​Token Handling

​Refresh Tokens

​Error Handling

​Scope Challenge Handling

​Runtime Insufficient Scope Errors

​Step-Up Authorization Flow

​安全 Considerations

​MCP Authorization Extensions

Introduction

Purpose and Scope

Protocol Requirements

Standards Compliance

Roles

概览

Authorization Server Discovery

Client Registration

Scope Selection Strategy

Authorization Flow Steps

Authorization Response Validation

Resource Parameter Implementation

Canonical Server URI

Access Token Usage

Token Requirements

Token Handling

Refresh Tokens

Error Handling

Scope Challenge Handling

Runtime Insufficient Scope Errors

Step-Up Authorization Flow

安全 Considerations

MCP Authorization Extensions