扩展概览

MCP 扩展

MCP 扩展是规范的可选补充，定义了核心协议之外的功能。扩展使功能可以是模块化的（例如，身份验证等不同功能）、专业化的（例如，行业特定逻辑）或实验性的（例如，正在为核心引入而孵化的功能）。

扩展使用唯一的_扩展标识符_识别，格式为：{vendor-prefix}/{extension-name}，例如 io.modelcontextprotocol/oauth-client-credentials。官方扩展使用 io.modelcontextprotocol 供应商前缀。

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

官方扩展仓库

官方扩展位于 MCP GitHub 组织中带有 ext- 前缀的仓库内。

MCP 授权扩展

仓库： github.com/modelcontextprotocol/ext-auth

核心规范之外的补充授权机制的扩展。

扩展	描述
OAuth Client Credentials	用于机器对机器身份验证的 OAuth 2.0 客户端凭证流程。
Enterprise-Managed Authorization	需要集中访问控制的企业环境的框架。

MCP Apps

仓库： github.com/modelcontextprotocol/ext-apps

用于对话式 MCP 客户端中交互式 UI 元素的扩展。

扩展	描述
MCP Apps	允许 MCP 服务器在对话内联显示交互式 UI 元素（图表、表单、视频播放器）

要开始构建 MCP Apps，请参阅快速入门指南或阅读完整的 MCP Apps 文档。

实验性扩展

实验性扩展为工作组和兴趣组提供了一条孵化途径，可以在正式提交 SEP 之前原型化想法并协作扩展概念。

实验性扩展仓库位于 MCP GitHub 组织中，使用 experimental-ext- 前缀（例如，experimental-ext-interceptors）。

基本规则

每个实验性扩展都需要与工作组或兴趣组相关联
仓库和发布的包需要清楚标明其实验性状态（例如，在 README 和包名称中）
核心维护者保留对实验性扩展仓库的监督权，包括归档或删除它们的权限

晋升为官方状态

要将实验性扩展提升为官方状态，需要通过标准的 SEP 流程（扩展轨道）。请随意参考实验性仓库以及您在孵化期间构建的任何参考实现，以证明扩展的实用性。

创建扩展

官方扩展的生命周期遵循基于 SEP 的流程。有关完整详细信息，请参阅 SEP-2133：扩展。

提案：使用标准 SEP 指南在主 MCP 仓库中创建类型为扩展轨道的 SEP。
实现：在官方 SDK 中构建至少一个参考实现 — 这是 SEP 可以审查前的必需步骤。
审查：核心维护者审查 SEP 并对纳入拥有最终决定权。
发布：批准后，打开 PR 将扩展添加到扩展仓库。
采用：之后，其他客户端、服务器和 SDK 也可以实现该扩展。

要求

扩展规范需要使用 RFC 2119 语言（MUST、SHOULD、MAY）
扩展必须具有相关的工作组或兴趣组

SDK 实现

SDK 可以选择实现扩展，但这不是协议一致性所必需的。SDK 维护者对他们支持的扩展拥有完全自主权。在 SDK 支持扩展的地方，SDK 文档应列出支持的扩展。

注意： 扩展始终默认禁用，需要开发人员明确选择加入。

演化

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

也就是说，向后兼容性很重要。当您需要更改扩展时，优先使用扩展设置对象中的能力标志或版本控制，而不是创建新的扩展标识符。如果无法避免破坏性更改，请使用新的标识符（例如，io.modelcontextprotocol/my-extension-v2）。

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

删除或重命名字段
更改字段类型
更改现有行为的语义
添加新的必需字段

协商

客户端和服务器在初始化握手期间，在其各自能力的 extensions 字段中宣告其对扩展的支持。

客户端能力

客户端在 initialize 请求中宣告扩展支持：

{
  "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 响应中宣告扩展支持：

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

每个扩展指定其设置对象的模式；空对象表示没有设置。

优雅降级

如果一方支持扩展而另一方不支持，支持方需要回退到核心协议行为，或者在扩展是强制性的情况下拒绝请求并返回适当的错误。

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

MCP Apps