> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.920929.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 授权

<Info>**协议版本**: 2025-03-26</Info>

## 1. 简介

### 1.1 目的和范围

模型上下文协议在传输层提供授权功能，使MCP客户端能够代表资源所有者向受限的MCP服务器发出请求。本规范定义了基于HTTP的传输的授权流程。

### 1.2 协议要求

授权对MCP实现是**可选的**。当支持时：

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

### 1.3 标准合规性

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

* [OAuth 2.1 IETF草案](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)
* OAuth 2.0授权服务器元数据
  ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414))
* OAuth 2.0动态客户端注册协议
  ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591))

## 2. 授权流程

### 2.1 概述

1. MCP认证实现**必须**实现OAuth 2.1，并为机密客户端和公共客户端提供适当的安全措施。

2. MCP认证实现**应该**支持OAuth 2.0动态客户端注册协议([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591))。

3. MCP服务器**应该**且MCP客户端**必须**实现OAuth 2.0授权服务器元数据([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414))。不支持授权服务器元数据的服务器**必须**遵循默认URI模式。

### 2.1.1 OAuth授权类型

OAuth指定了不同的流程或授权类型，这些是获取访问令牌的不同方式。每种类型针对不同的用例和场景。

MCP服务器**应该**支持最符合目标受众的OAuth授权类型。例如：

1. 授权码：当客户端代表（人类）最终用户行动时有用。
   * 例如，代理调用由SaaS系统实现的MCP工具。
2. 客户端凭据：客户端是另一个应用程序（非人类）
   * 例如，代理调用安全的MCP工具来检查特定商店的库存。无需模拟最终用户。

### 2.2 示例：授权码授权

这演示了用于用户认证的OAuth 2.1授权码授权类型流程。

**注意**：以下示例假设MCP服务器也充当授权服务器。然而，授权服务器可能作为其自己的独立服务部署。

人类用户通过Web浏览器完成OAuth流程，获取一个能够识别他们个人身份并允许客户端代表他们行动的访问令牌。

当需要授权且客户端尚未证明时，服务器**必须**响应\_HTTP 401 Unauthorized\_。

客户端在收到\_HTTP 401 Unauthorized\_后启动[OAuth 2.1 IETF草案](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#name-authorization-code-grant)授权流程。

以下演示了使用PKCE的公共客户端的基本OAuth 2.1流程。

```mermaid theme={null}
sequenceDiagram
    participant B as 用户代理（浏览器）
    participant C as 客户端
    participant M as MCP服务器

    C->>M: MCP请求
    M->>C: HTTP 401 Unauthorized
    Note over C: 生成code_verifier和code_challenge
    C->>B: 使用授权URL + code_challenge打开浏览器
    B->>M: GET /authorize
    Note over M: 用户登录并授权
    M->>B: 重定向到回调URL，带有授权码
    B->>C: 带有授权码的回调
    C->>M: 带有code + code_verifier的令牌请求
    M->>C: 访问令牌（+ 刷新令牌）
    C->>M: 带有访问令牌的MCP请求
    Note over C,M: 开始标准MCP消息交换
```

### 2.3 服务器元数据发现

对于服务器能力发现：

* MCP客户端\_必须\_遵循[RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)中定义的OAuth 2.0授权服务器元数据协议。
* MCP服务器\_应该\_遵循OAuth 2.0授权服务器元数据协议。
* 不支持OAuth 2.0授权服务器元数据协议的MCP服务器\_必须\_支持回退URL。

发现流程如下图所示：

```mermaid theme={null}
sequenceDiagram
    participant C as 客户端
    participant S as 服务器

    C->>S: GET /.well-known/oauth-authorization-server
    alt 发现成功
        S->>C: 200 OK + 元数据文档
        Note over C: 使用元数据中的端点
    else 发现失败
        S->>C: 404 Not Found
        Note over C: 回退到默认端点
    end
    Note over C: 继续授权流程
```

### 2.3.1 服务器元数据发现头部

MCP客户端\_应该\_在服务器元数据发现期间包含头部`MCP-Protocol-Version: <protocol-version>`，以允许MCP服务器根据MCP协议版本响应。

例如：`MCP-Protocol-Version: 2024-11-05`

### 2.3.2 授权基本URL

授权基本URL**必须**从MCP服务器URL中确定，丢弃任何现有的`path`组件。例如：

如果MCP服务器URL是`https://api.example.com/v1/mcp`，那么：

* 授权基本URL是`https://api.example.com`
* 元数据端点**必须**位于`https://api.example.com/.well-known/oauth-authorization-server`

这确保了授权端点在托管MCP服务器的域的根级别一致地定位，无论MCP服务器URL中有任何路径组件。

### 2.3.3 不支持元数据发现的服务器的回退

对于不实现OAuth 2.0授权服务器元数据的服务器，客户端**必须**使用以下默认端点路径（相对于授权基本URL，如[第2.3.2节](#232-授权基本url)所定义）：

| 端点 | 默认路径 | 描述 |
| - | - | - |
| 授权端点 | /authorize | 用于授权请求 |
| 令牌端点 | /token | 用于令牌交换和刷新 |
| 注册端点 | /register | 用于动态客户端注册 |

例如，MCP服务器位于`https://api.example.com/v1/mcp`，默认端点将是：

* `https://api.example.com/authorize`
* `https://api.example.com/token`
* `https://api.example.com/register`

客户端**必须**首先尝试通过元数据文档发现端点，然后回退到默认路径。当使用默认路径时，所有其他协议要求保持不变。

### 2.4 动态客户端注册

MCP客户端和服务器**应该**支持[OAuth 2.0动态客户端注册协议](https://datatracker.ietf.org/doc/html/rfc7591)，以允许MCP客户端在没有用户交互的情况下获取OAuth客户端ID。这为MCP提供了一种标准化的方式，使客户端能够自动注册到新服务器，这对于MCP至关重要：

* 客户端无法提前知道所有可能的服务器
* 手动注册会为用户创建摩擦
* 它使连接到新服务器变得无缝
* 服务器可以实施自己的注册策略

任何不支持动态客户端注册的MCP服务器需要提供获取客户端ID（和客户端密钥，如果适用）的替代方式。对于其中一个服务器，MCP客户端将不得不：

1. 为该MCP服务器硬编码客户端ID（和客户端密钥，如果适用），或
2. 向用户呈现一个UI，允许他们输入这些详细信息，之后注册OAuth客户端（例如，通过服务器托管的配置界面）。

### 2.5 授权流程步骤

完整的授权流程如下所示：

```mermaid theme={null}
sequenceDiagram
    participant B as 用户代理（浏览器）
    participant C as 客户端
    participant M as MCP服务器

    C->>M: GET /.well-known/oauth-authorization-server
    alt 服务器支持发现
        M->>C: 授权服务器元数据
    else 没有发现
        M->>C: 404（使用默认端点）
    end

    alt 动态客户端注册
        C->>M: POST /register
        M->>C: 客户端凭据
    end

    Note over C: 生成PKCE参数
    C->>B: 使用授权URL + code_challenge打开浏览器
    B->>M: 授权请求
    Note over M: 用户/授权
    M->>B: 重定向到回调URL，带有授权码
    B->>C: 授权码回调
    C->>M: 带有code_verifier的令牌请求
    M->>C: 访问令牌（+ 刷新令牌）
    C->>M: 带有访问令牌的API请求
```

#### 2.5.1 决策流程概述

```mermaid theme={null}
flowchart TD
    A[开始授权流程] --> B{检查元数据发现}
    B -->|可用| C[使用元数据端点]
    B -->|不可用| D[使用默认端点]

    C --> G{检查注册端点}
    D --> G

    G -->|可用| H[执行动态注册]
    G -->|不可用| I[需要替代注册]

    H --> J[开始OAuth流程]
    I --> J

    J --> K[生成PKCE参数]
    K --> L[请求授权]
    L --> M[用户授权]
    M --> N[交换代码以获取令牌]
    N --> O[使用访问令牌]
```

### 2.6 访问令牌使用

#### 2.6.1 令牌要求

访问令牌处理**必须**符合[OAuth 2.1第5节](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5)的资源请求要求。具体来说：

1. MCP客户端**必须**使用授权请求头部字段[第5.1.1节](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1)：

```
Authorization: Bearer <access-token>
```

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

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

示例请求：

```http theme={null}
GET /v1/contexts HTTP/1.1
Host: mcp.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

#### 2.6.2 令牌处理

资源服务器**必须**按照[第5.2节](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.2)验证访问令牌。如果验证失败，服务器**必须**按照[第5.3节](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3)错误处理要求进行响应。无效或过期的令牌**必须**收到HTTP 401响应。

### 2.7 安全考虑

以下安全要求**必须**实施：

1. 客户端**必须**安全存储令牌，遵循OAuth 2.0最佳实践
2. 服务器**应该**实施令牌过期和轮换
3. 所有授权端点**必须**通过HTTPS提供
4. 服务器**必须**验证重定向URI，以防止开放重定向漏洞
5. 重定向URI**必须**是localhost URL或HTTPS URL

### 2.8 错误处理

服务器**必须**返回适当的HTTP状态代码用于授权错误：

| 状态代码 | 描述 | 用法 |
| - | - | - |
| 401 | 未授权 | 授权需要或令牌无效 |
| 403 | 禁止 | 无效作用域或权限不足 |
| 400 | 错误请求 | 格式错误的授权请求 |

### 2.9 实施要求

1. 实施**必须**遵循OAuth 2.1安全最佳实践
2. PKCE是**必需**的所有客户端
3. 令牌轮换**应该**实施，以增强安全性
4. 令牌生命周期**应该**根据安全要求进行限制

### 2.10 第三方授权流程

#### 2.10.1 概述

MCP服务器**可以**支持通过第三方授权服务器进行委托授权。在此流程中，MCP服务器充当OAuth客户端（对第三方授权服务器）和OAuth授权服务器（对MCP客户端）。

#### 2.10.2 流程描述

第三方授权流程包括以下步骤：

1. MCP客户端启动标准OAuth流程与MCP服务器
2. MCP服务器将用户重定向到第三方授权服务器
3. 用户在第三方服务器上授权
4. 第三方服务器将用户重定向回MCP服务器，带有授权码
5. MCP服务器用授权码交换第三方访问令牌
6. MCP服务器生成其自己的访问令牌，绑定到第三方会话
7. MCP服务器完成原始OAuth流程与MCP客户端

```mermaid theme={null}
sequenceDiagram
    participant B as 用户代理（浏览器）
    participant C as MCP客户端
    participant M as MCP服务器
    participant T as 第三方授权服务器

    C->>M: 初始OAuth请求
    M->>B: 重定向到第三方/authorize
    B->>T: 授权请求
    Note over T: 用户授权
    T->>B: 重定向到MCP服务器回调，带有授权码
    B->>M: 授权码
    M->>T: 交换代码以获取令牌
    T->>M: 第三方访问令牌
    Note over M: 生成绑定MCP令牌
    M->>B: 重定向到MCP客户端回调
    B->>C: MCP授权码
    C->>M: 交换代码以获取令牌
    M->>C: MCP访问令牌
```

#### 2.10.3 会话绑定要求

实施第三方授权的MCP服务器**必须**：

1. 维护第三方令牌和发行MCP令牌之间的安全映射
2. 在使用MCP令牌之前验证第三方令牌状态
3. 实施适当的令牌生命周期管理
4. 处理第三方令牌过期和续订

#### 2.10.4 安全考虑

实施第三方授权时，服务器**必须**：

1. 验证所有重定向URI
2. 安全存储第三方凭据
3. 实施适当的会话超时处理
4. 考虑令牌链的安全影响
5. 实施适当的错误处理以处理第三方授权失败

## 3. 最佳实践

#### 3.1 本地客户端作为公共OAuth 2.1客户端

我们强烈建议本地客户端以公共OAuth 2.1客户端的形式实施OAuth 2.1：

1. 使用代码挑战（PKCE）进行授权请求，以防止拦截攻击
2. 实施适合本地系统的安全令牌存储
3. 遵循令牌刷新最佳实践以维护会话
4. 正确处理令牌过期和续订

#### 3.2 授权元数据发现

我们强烈建议所有客户端实施元数据发现。这减少了用户需要手动提供端点或客户端回退到定义的默认值的需要。

#### 3.3 动态客户端注册

由于客户端无法提前知道MCP服务器集，因此我们强烈建议实施动态客户端注册。这使应用程序能够自动注册到MCP服务器，并消除了用户需要手动获取客户端ID的需要。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.