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

# 客户端注册

<div id="enable-section-numbers" />

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

* **[Client ID Metadata Documents](#client-id-metadata-documents)**：当客户端和服务器没有既有关系时使用（最常见）
* **[Pre-registration](#pre-registration)**：当客户端和服务器已有关系时使用
* **[Dynamic Client Registration](#dynamic-client-registration)**：用于向后兼容或特定要求

支持所有选项的客户端 **SHOULD** 使用以下优先级顺序：

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

## Client ID Metadata Documents

MCP 客户端和授权服务器 **SHOULD** 支持 [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00) 中规定的 OAuth Client ID Metadata Documents，用于客户端注册。

这种方法使客户端能够使用 HTTPS URL 作为客户端标识符，其中该 URL 指向包含客户端元数据的 JSON 文档。这解决了 MCP 中常见的服务器和客户端没有既有关系的场景。

### Implementation Requirements

支持 Client ID Metadata Documents 的 MCP 实现 **MUST** 遵循 [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00) 中规定的要求。关键要求包括：

**对于 MCP 客户端：**

* 客户端 **MUST** 按照 RFC 要求在 HTTPS URL 上托管其元数据文档
* `client_id` URL **MUST** 使用 "https" scheme 并包含路径组件，例如 `https://example.com/client.json`
* 元数据文档 **MUST** 至少包含以下属性：`client_id`、`client_name`、`redirect_uris`
* 客户端 **MUST** 确保元数据中的 `client_id` 值与文档 URL 完全匹配
* 客户端 **MAY** 使用 `private_key_jwt` 进行客户端认证（例如，对令牌端点的请求），并采用 [Section 6.2 of Client ID Metadata Document](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-00.html#section-6.2) 中描述的适当 JWKS 配置

**对于授权服务器：**

* 遇到 URL 形式的 client\_ids 时，**SHOULD** 获取元数据文档
* **MUST** 验证所获取文档的 `client_id` 与该 URL 完全匹配
* **SHOULD** 按照 HTTP 缓存标头缓存元数据
* **MUST** 根据元数据文档中的重定向 URI 验证授权请求中呈现的重定向 URI
* **MUST** 验证文档结构是有效 JSON 且包含必需字段
* **SHOULD** 遵循 [Section 6 of Client ID Metadata Document](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-00.html#section-6) 和 [Client ID Metadata Document Security](/specification/draft/basic/authorization/security-considerations#client-id-metadata-document-security) 中的安全注意事项

### Example Metadata Document

```json theme={null}
{
  "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"
}
```

### Client ID Metadata Documents Flow

下图说明使用 Client ID Metadata Documents 时的完整流程：

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Client as MCP Client
    participant Server as Authorization Server
    participant Metadata as Metadata Endpoint<br/>(Client's HTTPS URL)
    participant Resource as MCP Server

    Note over Client,Metadata: Client hosts metadata at<br/>https://app.example.com/oauth/metadata.json

    User->>Client: Initiates connection to MCP Server
    Client->>Server: Authorization Request<br/>client_id=https://app.example.com/oauth/metadata.json<br/>redirect_uri=http://localhost:3000/callback

    Server->>User: Authentication prompt
    User->>Server: Provides credentials
    Note over Server: Authenticates user

    Note over Server: Detects URL-formatted client_id

    Server->>Metadata: GET https://app.example.com/oauth/metadata.json
    Metadata-->>Server: JSON Metadata Document<br/>{client_id, client_name, redirect_uris, ...}

    Note over Server: Validates:<br/>1. client_id matches URL<br/>2. redirect_uri in allowed list<br/>3. Document structure valid<br/>4. (Optional) Domain allowed via trust policy

    alt Validation Success
        Server->>User: Display consent page with client_name
        User->>Server: Approves access
        Server->>Client: Authorization code via redirect_uri
        Client->>Server: Exchange code for token<br/>client_id=https://app.example.com/oauth/metadata.json
        Server-->>Client: Access token
        Client->>Resource: MCP requests with access token
        Resource-->>Client: MCP responses
    else Validation Failure
        Server->>User: Error response<br/>error=invalid_client or invalid_request
    end

    Note over Server: Cache metadata for future requests<br/>(respecting HTTP cache headers)
```

### Advertising CIMD Support

授权服务器通过在其 OAuth 授权服务器元数据中包含以下属性，公布其支持使用 Client ID Metadata Documents 的客户端：

```json theme={null}
{
  "client_id_metadata_document_supported": true
}
```

MCP 客户端 **SHOULD** 检查此能力；如果不可用，**MAY** 回退到 [Dynamic Client Registration](#dynamic-client-registration) 或 [pre-registration](#pre-registration)。

## Pre-registration

MCP 客户端 **SHOULD** 支持静态客户端凭据选项，例如由预注册流程提供的凭据。这可以是：

1. 专门为 MCP 客户端与该授权服务器交互而硬编码客户端 ID（以及适用时的客户端凭据）；或者
2. 在用户自行注册 OAuth 客户端后（例如通过服务器托管的配置界面），向用户呈现 UI，允许他们输入这些详细信息。

## Dynamic Client Registration

<Warning>
  Dynamic Client Registration 已弃用。新实现应改用
  [Client ID Metadata Documents](#client-id-metadata-documents)。此选项保留用于与不支持 Client ID Metadata Documents 的授权服务器保持向后兼容。
</Warning>

MCP 客户端和授权服务器 **MAY** 支持 OAuth 2.0 Dynamic Client Registration Protocol [RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)，以允许 MCP 客户端在没有用户交互的情况下获取 OAuth 客户端 ID。包含此选项是为了与较早版本的 MCP 授权规范保持向后兼容。

### Application Type and Redirect URI Constraints

当授权服务器支持 OpenID Connect (OIDC) 和 Dynamic Client Registration 时，它们可能会基于 [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 中定义的 `application_type` 参数，对重定向 URI 施加额外约束。

MCP 客户端在 Dynamic Client Registration 期间 **MUST** 指定适当的 `application_type`。省略该参数时，在 OIDC 下默认为 `"web"`，这可能与原生风格的重定向 URI 冲突；非 OIDC 服务器可以安全地忽略该参数。

* **原生应用**（桌面应用、移动应用、CLI 工具，以及通过 `localhost` 访问的本地托管 Web 应用）**SHOULD** 使用 `application_type: "native"`
* **Web 应用**（由非本地主机提供的远程浏览器应用）**SHOULD** 使用 `application_type: "web"`

当授权服务器实现 OIDC 时，MCP 客户端 **MUST** 准备好处理由重定向 URI 约束导致的注册失败。当注册请求被拒绝时，客户端 **SHOULD** 向用户或开发者呈现有意义的错误。客户端 **MAY** 使用调整后的 `application_type`，或使用符合授权服务器对给定应用类型要求的重定向 URI 重试注册。

## Authorization Server Binding

使用预注册凭据，或持久化通过 Dynamic Client Registration 获得的客户端凭据的客户端，**MUST** 将这些凭据与颁发它们的特定授权服务器关联，并以授权服务器的 `issuer` 标识符作为键。当授权服务器发生变化（通过更新的[受保护资源元数据](/specification/draft/basic/authorization/authorization-server-discovery#authorization-server-location)检测到）时，客户端 **MUST NOT** 复用来自不同授权服务器的客户端凭据，并且 **MUST** 向新的授权服务器重新注册。

预注册凭据天然绑定到特定授权服务器。如果受保护资源元数据指示的授权服务器不再与凭据注册时使用的授权服务器匹配，客户端 **SHOULD** 呈现错误，而不是静默尝试使用不匹配的凭据。

基于 Client ID Metadata Documents 的客户端 ID 可在授权服务器之间移植，因为它们是由授权服务器按需解析的自托管 HTTPS URL。当授权服务器变化时，无需重新注册。