Skip to main content

​
MCP 扩展

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

​
官方扩展仓库

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

​
MCP 授权扩展

modelcontextprotocol/ext-auth

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

​
MCP 应用

modelcontextprotocol/ext-apps

用于对话式 MCP 客户端中交互式 UI 元素的扩展。
要开始构建 MCP 应用，请参阅 快速入门指南 或阅读完整的 MCP 应用文档。

​
MCP Tasks

​
Experimental Extensions

Experimental extensions provide an incubation path for working groups and interest groups to prototype ideas and collaborate on extension concepts before formally submitting a SEP. Experimental extension repositories live within the MCP GitHub organization and use the experimental-ext- prefix (for example, experimental-ext-interceptors).

​
Basic Rules

  • Each experimental extension must be associated with a working group or interest group
  • Repositories and published packages must clearly indicate their experimental status (for example, in the README and package name)
  • Core maintainers retain oversight of experimental extension repositories, including the authority to archive or remove them

​
Promotion to Official Status

To promote an experimental extension to official status, it must go through the standard SEP process (the extension track). It is welcome to reference experimental repositories and any reference implementations built during incubation to demonstrate the extension’s usefulness.

​
创建扩展

官方扩展的生命周期遵循基于 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 字段里声明其对扩展的支持。

​
客户端能力

客户端在每个请求中的 _meta["io.modelcontextprotocol/clientCapabilities"] 中声明扩展支持：

​
服务器能力

服务器在 server/discover 响应中声明扩展支持：
每个扩展都会指定其设置对象的模式；空对象表示没有设置。

​
优雅降级

如果一方支持某个扩展而另一方不支持，支持方需要么回退到核心协议行为，要么在该扩展是强制性的情况下，使用适当的错误拒绝请求。 在扩展中记录预期的回退行为是一种良好做法。例如，提供 UI 增强工具的服务器仍应为不支持 UI 扩展的客户端返回有意义的文本内容。另一方面，需要特定身份验证扩展的服务器可以拒绝来自不支持该扩展的客户端的连接。