Skip to main content

​
MCP 扩展

MCP 扩展是规范的可选补充，定义了核心协议之外的能力。扩展支持模块化（例如，身份验证等独立功能）、专业化（例如，特定行业的逻辑）或实验性（例如，正在孵化以潜在纳入核心的功能）的功能。 扩展使用唯一的_扩展标识符_进行标识，格式为：{vendor-prefix}/{extension-name}，例如 io.modelcontextprotocol/oauth-client-credentials。官方扩展使用 io.modelcontextprotocol 供应商前缀。
如果您正在构建第三方扩展，请使用您拥有的反向域名作为供应商前缀以避免冲突（类似于 Java 包命名）。例如，拥有 example.com 的公司将使用 com.example/ 作为其前缀（例如，com.example/my-extension）。

​
官方扩展仓库

官方扩展位于 模型上下文协议 GitHub 组织 内，仓库名称带有 ext- 前缀。

​
MCP 授权扩展

modelcontextprotocol/ext-auth

核心规范之外的补充授权机制扩展。
扩展描述
OAuth 客户端凭证用于机器到机器身份验证的 OAuth 2.0 客户端凭证流程。
企业托管授权需要集中访问控制的企业环境框架。

​
MCP 应用

modelcontextprotocol/ext-apps

用于对话式 MCP 客户端中交互式 UI 元素的扩展。
扩展描述
MCP 应用允许 MCP 服务器在对话中内联显示交互式 UI 元素（图表、表单、视频播放器）
要开始构建 MCP 应用，请参阅 快速入门指南 或阅读完整的 MCP 应用文档。

​
实验性扩展

实验性扩展为 工作组和兴趣小组 提供了孵化途径，以便在正式提交 SEP 之前原型化想法并就扩展概念进行协作。 实验性扩展仓库位于 MCP GitHub 组织内，带有 experimental-ext- 前缀（例如，experimental-ext-interceptors）。

​
基本规则

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

​
晋升为官方状态

要将实验性扩展晋升为官方状态，它需要经过标准的 SEP 流程（扩展轨道）。欢迎引用实验性仓库以及在孵化期间构建的任何参考实现，以证明扩展的实用性。

​
创建扩展

官方扩展的生命周期遵循基于 SEP 的流程。有关详细信息，请参阅 SEP-2133: 扩展。
  1. 提议：使用 标准 SEP 指南 在主 MCP 仓库中创建 SEP，类型为 扩展轨道。
  2. 实现：在官方 SDK 中构建至少一个参考实现——这是 SEP 可以被审查之前的必要条件。
  3. 审查：核心维护者 审查 SEP 并对是否纳入拥有最终决定权。
  4. 发布：一旦获批，打开一个 PR 将扩展添加到扩展仓库。
  5. 采用：之后，其他客户端、服务器和 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 扩展的客户端返回有意义的文本内容。另一方面，需要特定身份验证扩展的服务器可以拒绝来自不支持该扩展的客户端的连接。