Skip to main content

​
MCP 扩展

MCP 扩展是规范的可选补充，用来定义核心协议之外的能力。扩展可以启用模块化功能（例如认证这类独立能力）、专门能力（例如行业特定逻辑），或实验性能力（例如正在孵化、未来可能进入核心协议的功能）。 扩展使用唯一的_扩展标识符_识别，格式为 {vendor-prefix}/{extension-name}，例如 io.modelcontextprotocol/oauth-client-credentials。标识符遵循与 _meta keys 相同的规则，但必须包含前缀。官方扩展使用 io.modelcontextprotocol vendor prefix。
如果你正在构建第三方扩展，请使用你拥有域名的反向域名作为 vendor prefix，以避免冲突（类似 Java 包命名）。例如，拥有 example.com 的公司会使用 com.example/ 作为前缀（例如 com.example/my-extension）。

​
官方扩展仓库

官方扩展位于 Model Context Protocol GitHub organization 下，仓库名以 ext- 为前缀。

​
MCP Authorization Extensions

modelcontextprotocol/ext-auth

核心规范之外的补充授权机制扩展。
扩展说明
OAuth Client Credentials用于机器到机器认证的 OAuth 2.0 client credentials flow。
Enterprise-Managed Authorization面向需要集中访问控制的企业环境的框架。

​
MCP Apps

modelcontextprotocol/ext-apps

面向会话式 MCP client 中交互式 UI 元素的扩展。
扩展说明
MCP Apps允许 MCP servers 在对话内联显示交互式 UI 元素（图表、表单、视频播放器等）。
要开始构建 MCP Apps，请参阅快速开始指南，或阅读完整的 MCP Apps 文档。

​
MCP Tasks

扩展说明
MCP Tasks面向长时间运行操作的异步任务执行，支持轮询、执行中输入和持久句柄。

​
实验性扩展

实验性扩展为工作组与兴趣组提供孵化路径，让它们在正式提交 SEP 前可以原型化想法，并围绕扩展概念协作。 实验性扩展仓库位于 MCP GitHub organization 下，仓库名以 experimental-ext- 为前缀（例如 experimental-ext-interceptors）。

​
基本规则

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

​
晋升为官方状态

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

​
创建扩展

官方扩展的生命周期遵循基于 SEP 的流程。完整细节请参阅 SEP-2133: Extensions。
  1. 提出：在 MCP 主仓库中使用标准 SEP 指南创建 SEP，并将类型设为 Extensions Track。
  2. 实现：在官方 SDK 中构建至少一个参考实现，这是 SEP 进入评审前的必需条件。
  3. 评审：Core Maintainers 评审 SEP，并对是否纳入拥有最终权威。
  4. 发布：批准后，打开 PR 将扩展添加到扩展仓库。
  5. 采用：之后，其他 clients、servers 和 SDKs 也可以实现该扩展。

​
Requirements

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

​
SDK 实现

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

​
演进

扩展独立于核心协议演进。更新由扩展仓库维护者管理，不需要核心维护者评审。 不过，向后兼容仍然重要。当你需要修改扩展时，优先在扩展设置对象中使用 capability flags 或版本管理，而不是创建新的扩展标识符。如果不可避免地要引入 breaking change，请使用新标识符（例如 io.modelcontextprotocol/my-extension-v2）。 Breaking change 是任何会导致现有实现失败或行为不正确的修改，包括：
  • 删除或重命名字段
  • 修改字段类型
  • 改变现有行为语义
  • 添加新的必填字段

​
协商

Clients 和 servers 会在初始化握手期间，在各自 capabilities 的 extensions 字段中声明对扩展的支持。

​
客户端能力

Client 在 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"
    }
  }
}

​
服务器能力

Server 在 initialize 响应中声明扩展支持： 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {},
      "extensions": {
        "io.modelcontextprotocol/ui": {}
      }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "version": "1.0.0"
    }
  }
}
每个扩展都会指定其 settings object 的 schema；空对象表示没有设置。

​
优雅降级

如果一方支持某个扩展而另一方不支持，支持方需要回退到核心协议行为；如果该扩展是必需的，则应使用适当错误拒绝请求。 在扩展中记录预期的 fallback 行为是良好实践。例如，提供 UI 增强 tools 的 server，仍应为不支持 UI 扩展的 client 返回有意义的文本内容。另一方面，如果某个 server 需要特定认证扩展，它可以拒绝来自不支持该扩展的 client 的连接。