Skip to main content
FinalStandards Track
FieldValue
SEP2133
TitleExtensions
StatusFinal
TypeStandards Track
Created2025-01-21
Author(s)Peter Alexander (@pja-ant)
SponsorNone (seeking sponsor)
PR#2133

​
Abstract

This SEP establishes a lightweight framework for extending the Model Context Protocol through optional, composable extensions. This proposal defines a governance model and presentation structure for extensions that allows the MCP ecosystem to evolve while maintaining core protocol stability. Extensions enable experimentation with new capabilities without forcing adoption across all implementations, providing clear extension points for the community to propose, review, and adopt enhanced functionality. At this stage we are only defining official extensions, i.e. those maintained by MCP maintainers. Externally maintained extensions will likely come at a later stage once this initial SEP is approved.

​
Motivation

MCP currently lacks any form of guidance on how extensions are to be proposed or adopted. Without a process, it is unclear how these extensions are governed, what expectations there are around implementation, how they should be referenced in the specification, etc.

​
Specification

​
Definition

An MCP extension is an optional addition to the specification that defines capabilities beyond the core protocol. Extensions enable functionality that may be modular (e.g., distinct features like authentication), specialized (e.g., industry-specific logic), or experimental (e.g., features being incubated for potential core inclusion). Extensions are identified using a unique extension identifier with the format: {vendor-prefix}/{extension-name}, e.g. io.modelcontextprotocol/oauth-client-credentials or com.example/websocket-transport. The names follow the same rules as the _meta keys, except that the prefix is mandatory. To prevent identifier collisions, the vendor prefix SHOULD be a reversed domain name that the extension author owns or controls (similar to Java package naming conventions). For example, a company owning example.com would use com.example/ as their prefix. Breaking changes MUST use a new identifier, e.g. io.modelcontextprotocol/oauth-client-credentials-v2. A breaking change is any modification that would cause existing compliant implementations to fail or behave incorrectly, including: removing or renaming fields, changing field types, altering the semantics of existing behavior, or adding new required fields. Extensions may have settings that are sent in client/server messages for fine-grained configuration. For now, we only define Official Extensions. Unofficial extensions will not yet be recognized by MCP governance, but may be introduced and governed by developers and distributed in non official channels like GitHub.

​
Official Extensions

Official extensions live inside the MCP github org at https://github.com/modelcontextprotocol/ and are officially developed and recommended by MCP maintainers. Official extensions use the io.modelcontextprotocol vendor prefix in their extension identifiers. An extension repository is a repository within the official modelcontextprotocol github org with the ext- prefix, e.g. https://github.com/modelcontextprotocol/ext-auth.
  • Extension repositories are created at the core maintainers discretion with the purpose of grouping extensions in a specific area (e.g. auth, transport, financial services).
  • A repository has a set of maintainers (identified by MAINTAINERS.md) appointed by the core maintainers that are responsible for the repository and extensions within it (e.g. ext-auth MAINTAINERS.md, ext-apps MAINTAINERS.md).
  • Extensions SHOULD have an associated working group or interest group to guide their development and gather community input.
An extension is a versioned specification document within an extension repository, e.g. https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/oauth-client-credentials.mdx
  • Extension specifications MUST use the same language as the core specification (i.e. [BCP 14] [RFC2119] [RFC8174]) and SHOULD be worded as if they were part of the core specification.
While day-to-day governance is delegated to extension repository maintainers, the core maintainers retain ultimate authority over official extensions, including the ability to modify, deprecate, or remove any extension.

​
Lifecycle

​
Creation

Extensions are initially created via a SEP in the main MCP repository using the standard SEP guidelines but with a new type: Extensions Track. This type follows the same review and acceptance process as Standards Track SEPs, but clearly indicates that the proposal is for an extension rather than a core protocol addition. The SEP must identify the Working Group and Extension Maintainers that will be responsible for the extension. See SEP-2148 for how maintainers are appointed. Extension SEPs:
  • SHOULD be discussed and iterated on in a relevant working group prior to submission.
  • MUST have at least one reference implementation in an official SDK prior to review to ensure the extension is practical and implementable.
  • Will be reviewed by the Core Maintainers, who have the final authority over its inclusion as an Offical Extension.
Once approved, the author SHOULD produce a PR that introduces the extension to the extension repository and reference in the main spec (see Spec Recommendation section). Approved extensions MAY be implemented in additional clients / servers / SDKs (see SDK Implementation).

​
Iteration

Once accepted, extensions may be iterated on without further review from the Core Maintainers. The extension repository maintainers are responsible for the review and acceptance of changes to an extension and SHOULD coordinate change via the relevant working group(s). As extensions are independent of the core protocol, extensions may be updated and deployed at any time, but changes MUST ensure they account for backwards compatibility in their design.

​
Promotion to Core Protocol (Optional)

Eventually, some extensions MAY transition to being core protocol features. This SHOULD be treated as a Standards Track SEP with separate core maintainer review. Note that not all extensions are suitable for inclusion in the core protocol (e.g. those specific to an industry) and may remain as extensions indefinitely.

​
Spec Recommendation

Extensions will be referenced from a new page on the MCP website at modelcontextprotocol.io/extensions (to be created) with links to their specification. Links to relevant extensions MAY also be added to the core specification as appropriate (e.g. https://modelcontextprotocol.io/specification/draft/basic/authorization may link to ext-auth extensions), but they MUST be clearly advertised as optional extensions and SHOULD be links only (not copies of specification text).

​
SDK Implementation

SDKs MAY implement extensions. Where implemented, extensions MUST be disabled by default and require explicit opt-in. SDK documentation SHOULD list supported extensions. SDK maintainers have full autonomy over extension support in their SDKs:
  • Maintainers are solely responsible for the implementation and maintenance of any extensions they choose to support.
  • Maintainers are under no obligation to implement any extension or accept contributed implementations. Extension support is not required for 100% protocol conformance or the upcoming SDK conformance tiers.
  • This SEP does not prescribe how SDKs should structure or package extensions. Maintainers may provide extension points, plugin systems, or any other mechanism they see fit.

​
Evolution

All extensions evolve independently of the core protocol, i.e. a new version of an extension MAY be published without review by the core maintainers. Minor updates, bug fixes, and non-breaking enhancements to an extension do not require a new SEP; these changes are managed by the extension repository maintainers. Extensions SHOULD be versioned, but exact versioning approach is not specified here.

​
Negotiation

Clients and servers advertise their support for extensions in the ClientCapabilities and ServerCapabilities fields respectively, and in the Server Card (currently in progress). A new “extensions” field will be introduced to each that is a map of extension identifiers to per-extension settings objects. Each extension specifies the schema of its settings object; an empty object indicates no settings.

​
Client Capabilities

Clients advertise extension support in the initialize request: 
{
  "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 Capabilities

Servers advertise extension support in the initialize response: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {},
      "extensions": {
        "io.modelcontextprotocol/ui": {}
      }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "version": "1.0.0"
    }
  }
}

​
Server-Side Capability Checking

Servers SHOULD check client capabilities before offering extension-specific features: 
const hasUISupport = clientCapabilities?.extensions?.[
  "io.modelcontextprotocol/ui"
]?.mimeTypes?.includes("text/html;profile=mcp-app");

if (hasUISupport) {
  // Register tools with UI features
} else {
  // Register text-only fallback
}

​
Graceful Degradation

If one party supports an extension but the other does not, the supporting party MUST either revert to core protocol behavior or reject the request with an appropriate error if the extension is mandatory. Extensions SHOULD document their expected fallback behavior. For example, a server offering UI-enhanced tools should still return meaningful text content for clients that do not support the UI extension, while a server requiring a specific authentication extension MAY reject connections from clients that do not support it.

​
Trademark Policy

  • Use of MCP trademarks in extension identifiers does not grant trademark rights. Third parties may not use ‘MCP’, ‘Model Context Protocol’, or confusingly similar marks in ways that imply endorsement or affiliation.
  • MCP makes no judgment about trademark validity of terms used in extensions.

​
Antitrust

  • Extension developers acknowledge that they may compete with other participants, have no obligation to implement any extension, are free to develop competing extensions and protocols, and may license their technology to third parties including for competing solutions.
  • Status as an official extension does not create an exclusive relationship.
  • Extension repository maintainers act in individual capacity using best technical judgment.

​
Licensing

Official extensions MUST be available under the Apache 2.0 license.

​
Contributor License Grant

By submitting a contribution to an official MCP extension repository, you represent that:
  1. You have the legal authority to grant the rights in this agreement
  2. Your contribution is your original work, or you have sufficient rights to submit it
  3. You grant to Linux Foundation and recipients of the specification a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable license to:
    • Reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute the contribution
    • Make, have made, use, offer to sell, sell, import, and otherwise transfer implementations

​
No Other Rights

Except as explicitly set forth in this section, no other patent, trademark, copyright, or other intellectual property rights are granted under this agreement, including by implication, waiver, or estoppel.

​
Not Specified

This SEP does not specify all aspects of an extension system. The following is an incomplete list of what this SEP does not address:
  • Schema: we do not specify a mechanism for extensions to advertise how they modify the schema.
  • Dependencies: we do not specify if/how extensions may have dependencies on specific core protocol versions, or interdependencies with other extensions (or versions of extensions).
  • Profiles: we do not specify a way of grouping extensions.
These are omitted not because they are unimportant, but because they may be added later and the goal of this SEP is simply to get some initial extension structure off the ground and defers detailed technical discussion around more complex/debatable aspects of extensions.

​
Rationale

This design for extensions uses the following principles:
  • Start simple: the intention is to have a relatively simple mechanism that allows people to start building and proposing extensions in a structured way.
  • Clear governance: For now, the focus is on clear governance and less on implementation details.
  • Refine later: Over time, once we have more experience with extensions, we can adjust the approach appropriately.
Some specific design choices:
  • Why extension repositories instead of individual/independent extensions? Repositories provide a natural group and governance structure that allows for the repository maintainers to enforce structure and conformity to extensions. It avoids a failure case of different extensions in an area working in incompatible ways. Also provides a way to delegate much of the governance work.
  • Why not require core maintainer review for official extensions? Delegated reviews allows for extensions to evolve autonomously without being bottlenecked on core maintainer review, which is already a (often months) long process.
  • Why separate versioning? Extensions are additions to the spec and optional so there is no need to tie versions together. Separate versions allow for more rapid iteration.

​
Backward Compatibility

The extension framework itself is purely additive to the core protocol, so there are no backwards compatibility concerns with the core specification. The design described in this SEP is consistent with existing official extensions (ext-apps and ext-auth), which already use the patterns specified here for capability negotiation and extension identifiers. However, individual extensions may have their own backwards compatibility concerns. Extensions MUST consider and account for backwards compatibility in their design, both across core protocol versions and extension versions. Breaking changes within an extension MUST use a new extension identifier (see Definition section). Extensions SHOULD also document their approach to backwards compatibility and stability (e.g. an extension MAY advertise itself as “experimental” indicating that it may break without notice).

​
Security Implications

Extensions MUST implement all related security best practices in the area that they extend. Clients and servers SHOULD treat any new fields or data introduced as part of an extension as untrusted and SHOULD comprehensively validate them.

​
Reference Implementation

To be provided.