> ## 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.

# 扩展概览

> Model Context Protocol 的可选扩展

# MCP 扩展

MCP 扩展是规范的可选补充，用来定义核心协议之外的能力。扩展可以启用模块化功能（例如认证这类独立能力）、专门能力（例如行业特定逻辑），或实验性能力（例如正在孵化、未来可能进入核心协议的功能）。

扩展使用唯一的\_扩展标识符\_识别，格式为 `{vendor-prefix}/{extension-name}`，例如 `io.modelcontextprotocol/oauth-client-credentials`。标识符遵循与 [`_meta` 键](/specification/draft/basic/index#meta) 相同的规则，但必须包含前缀。官方扩展使用 `io.modelcontextprotocol` 供应商前缀。

<Tip>
  如果你正在构建第三方扩展，请使用你拥有域名的反向域名作为供应商前缀，以避免冲突（类似 Java 包命名）。例如，拥有 `example.com` 的公司会使用 `com.example/` 作为前缀（例如 `com.example/my-extension`）。
</Tip>

## 官方扩展仓库

官方扩展位于 [Model Context Protocol GitHub 组织](https://github.com/modelcontextprotocol/) 下，仓库名以 `ext-` 为前缀。

### MCP 授权扩展

<Card title="modelcontextprotocol/ext-auth" icon="github" href="https://github.com/modelcontextprotocol/ext-auth">
  核心规范之外的补充授权机制扩展。
</Card>

| 扩展                                                                                    | 说明                                          |
| ------------------------------------------------------------------------------------- | ------------------------------------------- |
| [OAuth Client Credentials](/extensions/auth/oauth-client-credentials)                 | 用于机器到机器认证的 OAuth 2.0 client credentials 流程。 |
| [Enterprise-Managed Authorization](/extensions/auth/enterprise-managed-authorization) | 面向需要集中访问控制的企业环境的框架。                         |

### MCP Apps

<Card title="modelcontextprotocol/ext-apps" icon="github" href="https://github.com/modelcontextprotocol/ext-apps">
  面向会话式 MCP 客户端中交互式 UI 元素的扩展。
</Card>

| 扩展                                    | 说明                                        |
| ------------------------------------- | ----------------------------------------- |
| [MCP Apps](/extensions/apps/overview) | 允许 MCP 服务器在对话内联显示交互式 UI 元素（图表、表单、视频播放器等）。 |

要开始构建 MCP Apps，请参阅[快速开始指南](/extensions/apps/build#getting-started)，或阅读完整的 [MCP Apps 文档](https://apps.extensions.modelcontextprotocol.io/api/documents/Quickstart.html)。

### MCP Tasks

| 扩展                                      | 说明                                |
| --------------------------------------- | --------------------------------- |
| [MCP Tasks](/extensions/tasks/overview) | 面向长时间运行操作的异步任务执行，支持轮询、执行中输入和持久句柄。 |

## 实验性扩展

实验性扩展为[工作组与兴趣组](/community/working-interest-groups)提供孵化路径，让它们在正式提交 SEP 前可以原型化想法，并围绕扩展概念协作。

实验性扩展仓库位于 MCP GitHub organization 下，仓库名以 `experimental-ext-` 为前缀（例如 `experimental-ext-interceptors`）。

### 基本规则

* 每个实验性扩展都需要关联到一个工作组或兴趣组。
* 仓库和已发布包需要清楚标明其实验状态（例如在 README 和包名中）。
* [Core Maintainers](/community/contributor-ladder#core-maintainer) 保留对实验性扩展仓库的监督权，包括归档或移除它们的能力。

### 晋升为官方状态

要将实验性扩展提升为官方扩展，需要走标准 SEP 流程（Extensions Track）。你可以引用实验仓库以及孵化期间构建的任何参考实现，以证明扩展的实用性。

## 创建扩展

官方扩展的生命周期遵循基于 SEP 的流程。完整细节请参阅 [SEP-2133: Extensions](/seps/2133-extensions)。

1. **提出**：在 MCP 主仓库中使用[标准 SEP 指南](/community/sep-guidelines)创建 SEP，并将类型设为 **Extensions Track**。
2. **实现**：在官方 SDK 中构建至少一个参考实现，这是 SEP 进入评审前的必需条件。
3. **评审**：[Core Maintainers](/community/contributor-ladder#core-maintainer) 评审 SEP，并对是否纳入拥有最终权威。
4. **发布**：批准后，打开 PR 将扩展添加到扩展仓库。
5. **采用**：之后，其他客户端、服务器和 SDK 也可以实现该扩展。

### 要求

* 扩展规范需要使用 RFC 2119 语言（MUST、SHOULD、MAY）。
* 扩展必须关联一个工作组或兴趣组。

### SDK 实现

SDK 可以选择实现扩展，但这不是协议一致性的必需条件。SDK 维护者可以完全自主决定支持哪些扩展。如果某个 SDK 支持扩展，其 SDK 文档应列出支持的扩展。

<Note>
  扩展默认始终禁用，需要开发者显式选择启用。
</Note>

### 演进

扩展独立于核心协议演进。更新由扩展仓库维护者管理，不需要核心维护者评审。

不过，向后兼容仍然重要。当你需要修改扩展时，优先在扩展设置对象中使用能力标志或版本管理，而不是创建新的扩展标识符。如果不可避免地要引入破坏性变更，请使用新标识符（例如 `io.modelcontextprotocol/my-extension-v2`）。

**破坏性变更** 是任何会导致现有实现失败或行为不正确的修改，包括：

* 删除或重命名字段
* 修改字段类型
* 改变现有行为语义
* 添加新的必填字段

## 协商

客户端和服务器会在[初始化握手](/specification/latest/basic/lifecycle)期间，在各自能力的 `extensions` 字段中声明对扩展的支持。

### 客户端能力

客户端在 `initialize` 请求中声明扩展支持：

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "extensions": {
        "io.modelcontextprotocol/ui": {
          "mimeTypes": ["text/html;profile=mcp-app"]
        }
      }
    },
    "clientInfo": {
      "name": "ExampleClient",
      "version": "1.0.0"
    }
  }
}
```

### 服务器能力

服务器在 `initialize` 响应中声明扩展支持：

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {},
      "extensions": {
        "io.modelcontextprotocol/ui": {}
      }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "version": "1.0.0"
    }
  }
}
```

每个扩展都会指定其设置对象的 schema；空对象表示没有设置。

### 优雅降级

如果一方支持某个扩展而另一方不支持，支持方需要回退到核心协议行为；如果该扩展是必需的，则应使用适当错误拒绝请求。

在扩展中记录预期的回退行为是良好实践。例如，提供 UI 增强工具的服务器，仍应为不支持 UI 扩展的客户端返回有意义的文本内容。另一方面，如果某个服务器需要特定认证扩展，它可以拒绝来自不支持该扩展的客户端的连接。