Repository navigation
Description
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:
- Author creates a SEP using the standard SEP guidelines but with a new type: Extensions Track.
- Extension SEPs are reviewed by the relevant extension repository maintainers.
- 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 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.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsFinal
Activity
[-]SEP-1722: Extensions[/-][+]SEP-1724: Extensions[/+]jonathanhefner commentedon Oct 28, 2025
I like this design — it's simple and lightweight! 😃
Since there has been a lot of discussion around what "extensions" should and should not be, an alternative way of framing this could be "custom capabilities" (if that is helpful).
In that vein, will extensions be binary only (present / not present), or can they fine-grained a la current MCP capabilities? For example, could an extension be declared with something like
"modelcontextprotocol.io/oauth-client-credentials": { /* fine-grained settings */ }?Are there any restrictions on the format of
extension-name? For example, could it beoauth-client-credentials/v2instead ofoauth-client-credentials-v2?tulshi commentedon Oct 28, 2025
This is great, thanks for putting this together!
A few minor comments:
In the recommended extensions paragraph, the line:
Could be restated with an indication of the process, e.g. "MCP Maintainers will create and review the list of recommended extensions periodically".
Extension definition: Does the extension have a way of reqiuring a certain minimum MCP version? I thought this might be required, which is why in the Profiles SEP, I've included a minMcpVersion field in the definition of a profile.
pja-ant commentedon Oct 28, 2025
The SEP has the support for extensions as a binary thing on clients/servers. However, there's nothing stopping an extension from introducing
_metafields for additional settings.No restrictions, so what you've suggested is allowed. I think the only restriction is that the vendor prefix should not contain a
/. The intention is to follow the same restrictions as the_metafield (see https://modelcontextprotocol.io/specification/2025-06-18/basic/index#meta). Can add that clarification.Sure, will add!
There is no provision for this in the proposed protocol. I do think it's a good idea, but decided to omit in the spirit of keeping this initial SEP simple. We could definitely follow-up and add version constraints. Also happy to add them now if there's enough desire.
For what's it worth, I don't think there's anything stopping ad hoc implementations of this? e.g.
example.com/ext-foodocumentation says that it requires protocol version 2025-06-18pcarleton commentedon Oct 29, 2025
I'll sponsor this SEP!
jonathanhefner commentedon Oct 29, 2025
I'm thinking post-SEP-1442 client capabilities will be included in every request. So if an extension has fine-grained settings, it would need to inject those into the
_metaof every request.Are there reasons that we do not want to implement extensions as custom capabilities? For example:
{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-11-25", "capabilities": { "roots": { "listChanged": true }, "sampling": {}, "elicitation": {}, "modelcontextprotocol.io/oauth-client-credentials": { /* fine-grained settings */ }, "example.com/websocket-transport": { /* fine-grained settings */ } }, "clientInfo": { "name": "ExampleClient", "title": "Example Client Display Name", "version": "1.0.0" } } }tulshi commentedon Oct 29, 2025
@pja-ant I thought about extension discovery a bit, and I think there might be an issue with discovering details of an extension. Say a server card indicates that it supports a few extensions. Those extensions will have their unique URIs, but the client has no way of knowing what those extensions are. If they are official extensions, the client will know their details from the relevant "ext-" repo. If they are recommended or unofficial extensions, then the client will only have the URI.
For recommended extensions, I hope we can write the list of recommended extensions in such a way that it also provides a link to the URL where the extension has been defined. (So each entry will be a pair - the URI and the definition URL).
In a large enterprise, where possibly there are many unofficial extensions being used, it will be good for a client to discover what each extension means when it is going through the server discovery process. I think this can be achieved by having an entry in the Server Card that specifies not just the extension, but also the definition URL.
This is kind of why in the Profiles SEP, the profile definition URL serves as the unique identifier for the Profile.
pja-ant commentedon Oct 30, 2025
I assume this is about humans looking at a server card (or enabled extensions UI in a host application) trying to understand what
example.com/random-unofficial-extensionmeans? I agree that you won't immediately know where to find a description based on the ID, but Google should be effective for ad hoc lookups.For something more structured, I did actually consider this, but decided against it on the following grounds:
example.com/neat-extension.md, it becomes popular, everyone puts it in their server card, it eventually becomes recommended, maybe even official... and then I take my website down. Either you have to live with a broken link, or everyone has to update their server card. Yes, https://w3id.org/ help, but then you have to convince everyone to use it... seems a bit janky.I imagine in the future we could build a simple registry of extension ID to extension metadata. Could be as simple as
https://github.com/modelcontextprotocol/extensions/{extension-id}/metadata.jsonor companies could have their own registries for internal-only extensions (forking or augmenting the public one).tulshi commentedon Oct 30, 2025
@pja-ant , thanks. Would the list of recommended extensions include their description URLs?
13 remaining items
dsp-ant commentedon Nov 7, 2025
Core Maintainers did not approve this for now.
The common understanding in the core maintainer meeting was that this requires more detail:
On governance
Protocol changes
I am sure I missed a lot of pieces here, but @pcarleton and @pja-ant can fill those in.
He-Pin commentedon Nov 20, 2025
Nice, I have just submitted this to a
taskrelated thing too.#1831
matteo8p commentedon Jan 10, 2026
Hi team, are there any updates on this Extensions SEP? It's a blocker on MCP Apps SEP.
feat(client): add UI extension capabilities for client capability neg…
fix(server): wrap case block with braces to fix no-case-declarations …
github-actions commentedon Jan 16, 2026
Maintainer Activity Check
Hi @pcarleton!
You're assigned to this SEP but there hasn't been any activity from you in 69 days.
Please provide an update on:
If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.
This is an automated message from the SEP lifecycle bot.
comradelemoncake commentedon Jan 19, 2026
This is amazing work, thank you!
feat: React renderer for MCP Apps (#147)
localden commentedon Jan 21, 2026
For ease of tracking, will close this - #1761 is the pull request that we maintain moving forward with this SEP (per guidelines, SEPs are now just PRs).