SEP-1761: Add MCP extensions framework #1761
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,209 @@ | ||||||
| --- | ||||||
| title: Extensions Overview | ||||||
| description: Optional extensions to the Model Context Protocol | ||||||
| --- | ||||||
|
|
||||||
| Extensions allow the MCP ecosystem to evolve and experiment with new capabilities while maintaining core protocol stability. | ||||||
|
|
||||||
| ## What are Extensions? | ||||||
|
|
||||||
| Extensions are optional additions to the Model Context Protocol that provide functionality or guidance for specific use cases without requiring changes to the core specification. An extension is appropriate when a new feature is either: | ||||||
|
|
||||||
| - **Experimental** - There is sufficient uncertainty about an approach that would make it premature for the core specification, OR | ||||||
| - **Scoped** - The functionality is useful to a significant subset of users (e.g., specific industries or use cases) but may not be broadly applicable | ||||||
|
|
||||||
| Extensions provide a way for the MCP community to officially formalize and recommend approaches to common problems without the long-term commitment or scrutiny needed for core protocol changes. | ||||||
|
|
||||||
| ## Extension Types | ||||||
|
|
||||||
| MCP recognizes three categories of extensions: | ||||||
|
|
||||||
| | Type | Description | Governance | | ||||||
| | --------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | ||||||
| | **Official** | Maintained in MCP GitHub organization under `ext-` prefixed repositories | Core maintainer review and approval required | | ||||||
| | **Recommended** | Community-developed extensions that are vetted by core maintainers and listed in the [registry](/extensions/registry) | Listed after review | | ||||||
|
Member
There was a problem hiding this comment. If we have extensions that are maintained outside of the MCP organisation, we need to have a set of criteria or at least a lifecycle, to determine how we add and most importantly, remove recommendations for extensions. We need a set of minimum standard required in terms of licenses, usage, trademarks, etc. |
||||||
| | **Unofficial** | Developed independently without MCP oversight | No MCP involvement | | ||||||
|
|
||||||
| ### Official Extensions | ||||||
|
|
||||||
| Official extensions are maintained by the MCP core team and extension maintainers in repositories within the [modelcontextprotocol GitHub organization](https://github.com/modelcontextprotocol). These extensions: | ||||||
|
|
||||||
| - Follow the same [governance and contribution process](https://modelcontextprotocol.io/community/governance#processes) as the core protocol | ||||||
| - Are held to the same quality and documentation standards | ||||||
| - Use the `modelcontextprotocol.io` vendor prefix | ||||||
|
|
||||||
| ### Recommended Extensions | ||||||
|
|
||||||
| Recommended extensions are community-developed but have been reviewed and endorsed by MCP maintainers. To be listed as recommended, an extension must: | ||||||
|
|
||||||
| - Demonstrate clear value to a significant subset of MCP users | ||||||
| - Meet quality and documentation standards | ||||||
| - Be actively maintained | ||||||
| - Not conflict with core protocol principles | ||||||
| - Use custom vendor prefixes | ||||||
|
|
||||||
pja-ant marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| ### Unofficial Extensions | ||||||
|
|
||||||
| Unofficial extensions are developed independently and may be used by any implementation. These extensions: | ||||||
|
|
||||||
| - Do not require MCP approval or review | ||||||
| - Are used at implementers' own discretion | ||||||
| - May later become recommended or official extensions | ||||||
| - Use custom vendor prefixes | ||||||
|
|
||||||
| ## Extension Identifiers | ||||||
|
|
||||||
| All extensions are identified using a consistent format: | ||||||
|
|
||||||
| ``` | ||||||
| {vendor-prefix}/{extension-name} | ||||||
| ``` | ||||||
|
|
||||||
| **Examples:** | ||||||
|
|
||||||
| - `modelcontextprotocol.io/official-extension` (official) | ||||||
| - `example.com/custom-extension` (recommended or unofficial) | ||||||
| - `mycompany.io/proprietary-feature` (unofficial) | ||||||
|
Comment on lines
+64
to
+66
Member
There was a problem hiding this comment. At this point we should probably define this label mechanism with a reverse-dns name as a prefix in a central way. This is not necessarily part of this SEP, but we should do this, given it shows up everywhere now.
Contributor
Author
There was a problem hiding this comment. There's a separate PR for that. Will update if/when that is accepted. |
||||||
|
|
||||||
| The `vendor-prefix` follows the same format and reservation rules as prefixes in [`_meta`](/specification/draft/basic#meta). Specifically, any prefix beginning with zero or more valid labels, followed by `modelcontextprotocol` or `mcp`, followed by any valid label, is **reserved** for MCP use. | ||||||
|
|
||||||
| The vendor prefix helps avoid naming collisions and clearly indicates the source and governance of an extension. | ||||||
|
|
||||||
| ## Extension Negotiation | ||||||
|
|
||||||
| Extensions are negotiated during the MCP initialization phase through the `extensions` field within capabilities in the initialize request and response. | ||||||
|
Member
There was a problem hiding this comment. One of the interesting pieces here is seeing if extensions will require versioning as well. This could explode the complexity in negotiation. Curious what you think.
Contributor
Author
There was a problem hiding this comment. The SEP does not specify anything about versioning and version negotiation of extensions to keep things simple. Extensions may choose to speicfy that if they like (and they could implement using the per-extention capabilities). I agree that trying to specify this in a general way could be complex, which is why I've avoided it in this intentionally lightweight SEP, but the capabilities struct does provide some mechanisms if individual extensions need it. |
||||||
|
|
||||||
| ### How It Works | ||||||
|
|
||||||
| 1. During initialization, clients declare supported extensions in the `extensions` field | ||||||
| 2. Servers respond with their own supported extensions in their `extensions` field | ||||||
| 3. Each extension specification defines whether support from both parties is required | ||||||
| 4. Extensions may include optional capability parameters | ||||||
|
|
||||||
| ### Example: Client Initialization with Extensions | ||||||
|
|
||||||
| ```json | ||||||
| { | ||||||
| "jsonrpc": "2.0", | ||||||
| "id": 1, | ||||||
| "method": "initialize", | ||||||
| "params": { | ||||||
| "protocolVersion": "2025-11-25", | ||||||
| "capabilities": { | ||||||
| "roots": { | ||||||
| "listChanged": true | ||||||
| }, | ||||||
| "extensions": { | ||||||
| "example.com/custom-extension": { | ||||||
| "exampleSetting": "value" | ||||||
| }, | ||||||
| "modelcontextprotocol.io/official-extension": {} | ||||||
| } | ||||||
| }, | ||||||
| "clientInfo": { | ||||||
| "name": "ExampleClient", | ||||||
| "version": "1.0.0" | ||||||
| } | ||||||
| } | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| ### Example: Server Response with Extensions | ||||||
|
|
||||||
| ```json | ||||||
| { | ||||||
| "jsonrpc": "2.0", | ||||||
| "id": 1, | ||||||
| "result": { | ||||||
| "protocolVersion": "2025-11-25", | ||||||
| "capabilities": { | ||||||
| "logging": {}, | ||||||
| "extensions": { | ||||||
| "modelcontextprotocol.io/official-extension": { | ||||||
| "serverConfig": "enabled" | ||||||
| } | ||||||
| } | ||||||
| }, | ||||||
| "serverInfo": { | ||||||
| "name": "ExampleServer", | ||||||
| "version": "1.0.0" | ||||||
| } | ||||||
| } | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| ### Extension Capabilities | ||||||
|
|
||||||
| Each extension in the `extensions` object can have an associated capabilities object: | ||||||
|
|
||||||
| - **Empty object `{}`**: Indicates support for the extension with default settings | ||||||
| - **Capabilities object**: Provides extension-specific capabilities and parameters | ||||||
| - **Omission**: Extension is not supported | ||||||
|
|
||||||
| Implementations **SHOULD**: | ||||||
|
|
||||||
| - Ignore extensions they don't recognize | ||||||
| - Gracefully handle missing capability parameters | ||||||
| - Validate capability values before using them | ||||||
|
|
||||||
| For detailed protocol-level documentation on capability negotiation, see the [Lifecycle documentation](/specification/draft/basic/lifecycle#extension-negotiation). | ||||||
|
|
||||||
| ## Extension Repositories | ||||||
|
|
||||||
| Extension repositories are official repositories within the [modelcontextprotocol GitHub organization](https://github.com/modelcontextprotocol) with the `ext-` prefix. Each repository focuses on a specific area and is maintained by appointed maintainers. | ||||||
|
|
||||||
| | Repository | Description | Maintainers | | ||||||
| | ------------------------------------------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------- | | ||||||
| | [ext-auth](https://github.com/modelcontextprotocol/ext-auth) | Authentication and authorization extensions for MCP | [MAINTAINERS.md](https://github.com/modelcontextprotocol/ext-auth/blob/main/MAINTAINERS.md) | | ||||||
|
Comment on lines
+155
to
+157
Member
There was a problem hiding this comment. Is this table supposed to live here? It seems redundant with the extensions registry page.
Contributor
Author
There was a problem hiding this comment. Yeah, I wanted to keep the registry page only for the extensions that exist and what they do, i.e. things that end users will care about. This page is more for developers that want to know how things are specified and where things live.
Member
There was a problem hiding this comment.
Oh, correlating with your other comment, these repositories are not for a single extension. I was thinking each extension would have its own repository. |
||||||
|
|
||||||
| ## Available Extensions | ||||||
|
|
||||||
| See the [Extension Registry](/extensions/registry) for a complete list of official and recommended extensions. | ||||||
|
|
||||||
| ## Using Extensions | ||||||
|
|
||||||
| ### For Implementers | ||||||
|
|
||||||
| Extensions are **optional**. MCP clients and servers can choose which extensions to implement based on their requirements. When implementing an extension: | ||||||
|
|
||||||
| - Consider the extension's status (Draft, Approved, etc.) | ||||||
| - Review the extension's specification carefully | ||||||
| - Check SDK documentation to see if the extension is supported | ||||||
| - Declare the extension in the `extensions` field during initialization | ||||||
| - Implement proper handling for missing or unrecognized extensions | ||||||
pja-ant marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| Extensions are negotiated through the [initialization exchange](/specification/draft/basic/lifecycle#extension-negotiation) during session initialization. Each extension specification defines whether support from both parties is required. | ||||||
|
|
||||||
| ### SDK Support | ||||||
|
|
||||||
| MCP SDKs may provide built-in support for extensions. Check your SDK's documentation for: | ||||||
|
|
||||||
| - List of supported extensions | ||||||
| - How to enable/disable extensions | ||||||
| - Any SDK-specific configuration required | ||||||
|
|
||||||
| ### For Specification Writers | ||||||
|
|
||||||
| If you're writing specifications that reference MCP, you may wish to reference specific extensions. When doing so: | ||||||
|
|
||||||
| - Clearly indicate that the referenced capability is an **extension** | ||||||
| - Link to the extension's specification | ||||||
| - Note that support for the extension is optional | ||||||
|
|
||||||
| ## Proposing a New Official Extension | ||||||
|
|
||||||
| Official extensions are proposed through the SEP (Specification Enhancement Proposal) process: | ||||||
|
|
||||||
| 1. **Create a SEP** with Track set to "Extensions" | ||||||
| 2. **Engage with maintainers** of the relevant extension repository or working group to build alignment | ||||||
|
Member
There was a problem hiding this comment. Should this be?
Suggested change
(If you're proposing a new extension, then the "relevant extension repository" wouldn't exist yet, right?)
Contributor
Author
There was a problem hiding this comment. Extension repositories are not per extension, they are group (e.g. ext-auth) |
||||||
| 3. **Submit for review** following the standard [standard SEP approval process](https://modelcontextprotocol.io/community/sep-guidelines#submitting-a-sep) | ||||||
| 4. **Implement the extension**, once approved, by creating a PR to the extension repository | ||||||
|
|
||||||
| See the [SEP guidelines](/community/sep-guidelines) for detailed information about the SEP process and the extension governance model. | ||||||
|
|
||||||
| ## Extension Governance | ||||||
|
Member
There was a problem hiding this comment. This needs to go into detail on governance requirements for externally maintained extensions. |
||||||
|
|
||||||
| - **Extension Repository Maintainers** oversee extensions within their repository and ensure consistency and quality | ||||||
| - **Core Maintainers** retain authority over the extension system, including the ability to require changes, deprecate, or promote extensions to the core protocol | ||||||
|
|
||||||
| Extensions evolve independently of the core protocol, allowing for rapid iteration while maintaining protocol stability. | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| --- | ||
| title: Registry | ||
| description: Official and recommended MCP extensions | ||
| --- | ||
|
|
||
| Extensions are listed below, grouped by their repository. Each extension includes a link to its specification and a brief description. | ||
|
|
||
| ## Authentication | ||
|
|
||
| - **[OAuth 2.0 Client Credentials](https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/oauth-client-credentials.mdx)** - Defines how MCP clients can authenticate with servers using the OAuth 2.0 Client Credentials flow, enabling secure machine-to-machine authentication. | ||
| - **[Enterprise-Managed Authorization](https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/enterprise-managed-authorization.mdx)** - Provides mechanisms for enterprise SSO integration and centralized authorization management, allowing organizations to use their existing identity providers and access control systems with MCP. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
II feel this is more important than experimentation. I think the protocol has enough facilities for experimentation already.