SEP-1724: Extensions

Track: Standards
Author: Peter Alexander
Status: WIP

Changelog:

• 2025-10-28: Clarified extension identifier name validation. Added note about core maintainer recommended extensions review.
• 2025-11-03: Added note that extensions page will have links to extension specifications.
• 2025-11-03: Add support for extension settings.
• 2025-11-17: Remove externally maintained extensions.

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.

In response to feedback, 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 or change to the spec that provides functionality or guidance that is either experimental in nature (i.e. not yet ready for core protocol inclusion) or only applies in a limited domain (e.g. internal to a company, or only within a specific industry).

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. Breaking changes should use a new identifier, e.g. io.modelcontextprotocol/oauth-client-credentials-v2. The names follow the same rules as the _meta keys, except that the prefix is mandatory.

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 later be introduced.

Official Extensions

Official extensions live inside the MCP github org at https://github.com/modelcontextprotocol/ and are officially developed and recommended by MCP maintainers.

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.

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 should 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.

Lifecycle

For official extensions, the lifecycle is similar to a SEP, but delegated to the extension repository maintainers:

1. Author creates a SEP using the standard SEP guidelines but with a new type: Extensions Track.
2. Extension SEPs are reviewed by the relevant extension repository maintainers.
3. 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).
4. Approved extensions may be implemented in clients / servers / SDKs immediately (see SDK Implementation).

Eventually, some extensions may transition to being core protocol features. This should be treated as a standard protocol SEP with separate core maintainer review.

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 optionally implement any number of extensions and where appropriate (and necessary) should provide facilities for enabling and configuring extensions. Extensions must be disabled by default and require opt-in. SDK documentation should list supported extensions.

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.

Extensions should be versioned, but exact versioning approach is not specified here.

Negotiation

Clients and servers must advertise their support for an extension as part of their client in the ClientCapabilities and ServerCapabilities field and in the Server Card.

A new “extensions” field will be introduced to each that is a map of strings of supported extension identifiers to unspecified per-extension settings, example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {},
      "elicitation": {},
      "extensions": {
        "com.example/websocket-transport": {
          /* example fine-grained settings */
          "keepaliveInterval": 10,
        },
        "io.modelcontextprotocol/oauth-client-credentials": {
          /* example with no settings */
        }
      }
    },
    "clientInfo": {
      "name": "ExampleClient",
      "title": "Example Client Display Name",
      "version": "1.0.0"
    }
  }
}

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

Extensions are purely additive in nature, so there are no backwards compatibility concerns.

Individual extensions themselves should consider and account for backwards compatibility in their design, both across core protocol versions and extension versions. 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).

Reference Implementation

To be provided.

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 be comprehensively validated.