From 26e118cc1c4733d23e9b92387e12d4aeebd1d831 Mon Sep 17 00:00:00 2001 From: Peter Alexander Date: Thu, 22 Jan 2026 15:14:35 +0000 Subject: [PATCH 1/6] SEP: Extensions framework for MCP --- seps/0000-extensions.md | 230 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 seps/0000-extensions.md diff --git a/seps/0000-extensions.md b/seps/0000-extensions.md new file mode 100644 index 000000000..ddc7de1eb --- /dev/null +++ b/seps/0000-extensions.md @@ -0,0 +1,230 @@ +# SEP-0000: Extensions + +- **Status**: Draft +- **Type**: Standards Track +- **Created**: 2025-01-21 +- **Author(s)**: Peter Alexander (@pja-ant) +- **Sponsor**: None (seeking sponsor) +- **PR**: TBD + +## 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 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](https://modelcontextprotocol.io/specification/draft/basic/index#meta), 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. 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. + +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](https://www.rfc-editor.org/info/bcp14)] [[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)] [[RFC8174](https://datatracker.ietf.org/doc/html/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 + +For official extensions, the lifecycle is similar to a SEP, but delegated to the extension repository maintainers: + +1. Author creates 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. +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](http://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 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. + +Extensions should be versioned, but exact versioning approach is not specified here. + +### Negotiation + +Clients and servers advertise their support for extensions in the [ClientCapabilities](https://modelcontextprotocol.io/specification/2025-06-18/schema#clientcapabilities) and [ServerCapabilities](https://modelcontextprotocol.io/specification/2025-06-18/schema#servercapabilities) fields respectively, and in the [Server Card](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649) (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: + +```json +{ + "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: + +```json +{ + "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: + +```typescript +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 assume that features introduced by the extension will not work and revert to core protocol behavior. 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. + +### Legal Requirements + +#### 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 + +Extensions are purely additive in nature, so there are no backwards compatibility concerns. + +The design described in this SEP is consistent with existing official extensions ([ext-apps](https://github.com/modelcontextprotocol/ext-apps) and [ext-auth](https://github.com/modelcontextprotocol/ext-auth)), which already use the patterns specified here for capability negotiation and extension identifiers. + +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). + +## 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. + +## Reference Implementation + +To be provided. From adcee8a8047e415cbf73d9bdf7f94ac5f622c70e Mon Sep 17 00:00:00 2001 From: Peter Alexander Date: Thu, 22 Jan 2026 15:15:12 +0000 Subject: [PATCH 2/6] Update SEP number to 2133 --- seps/{0000-extensions.md => 2133-extensions.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename seps/{0000-extensions.md => 2133-extensions.md} (99%) diff --git a/seps/0000-extensions.md b/seps/2133-extensions.md similarity index 99% rename from seps/0000-extensions.md rename to seps/2133-extensions.md index ddc7de1eb..d673a5acd 100644 --- a/seps/0000-extensions.md +++ b/seps/2133-extensions.md @@ -1,11 +1,11 @@ -# SEP-0000: Extensions +# SEP-2133: Extensions - **Status**: Draft - **Type**: Standards Track - **Created**: 2025-01-21 - **Author(s)**: Peter Alexander (@pja-ant) - **Sponsor**: None (seeking sponsor) -- **PR**: TBD +- **PR**: [#2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133) ## Abstract From d4e17149e367289e933b34d4ed31e89f6178658c Mon Sep 17 00:00:00 2001 From: Peter Alexander Date: Fri, 23 Jan 2026 13:03:41 +0000 Subject: [PATCH 3/6] Update seps/2133-extensions.md Co-authored-by: Che Liu --- seps/2133-extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/seps/2133-extensions.md b/seps/2133-extensions.md index d673a5acd..71508ce5f 100644 --- a/seps/2133-extensions.md +++ b/seps/2133-extensions.md @@ -27,7 +27,7 @@ Extensions are identified using a unique _extension identifier_ with the format: 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. +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 From 683b6b3b8dcf4c8c7047517c55efa09bd266e77a Mon Sep 17 00:00:00 2001 From: Peter Alexander Date: Fri, 23 Jan 2026 13:04:11 +0000 Subject: [PATCH 4/6] Update seps/2133-extensions.md Co-authored-by: Che Liu --- seps/2133-extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/seps/2133-extensions.md b/seps/2133-extensions.md index 71508ce5f..08eca53f6 100644 --- a/seps/2133-extensions.md +++ b/seps/2133-extensions.md @@ -48,7 +48,7 @@ While day-to-day governance is delegated to extension repository maintainers, th For official extensions, the lifecycle is similar to a SEP, but delegated to the extension repository maintainers: -1. Author creates 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. +1. Author creates a SEP in the main MCP repository using the [standard SEP guidelines](https://modelcontextprotocol.io/community/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. 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_). From eb8d5379f0ae76dee4abd95850563ec8bb474d49 Mon Sep 17 00:00:00 2001 From: Peter Alexander Date: Fri, 23 Jan 2026 18:51:45 +0000 Subject: [PATCH 5/6] Address review feedback on SEP-2133 Extensions - Update definition to be more flexible (modular, specialized, experimental) - Add collision prevention guidance for extension identifiers - Define what constitutes a breaking change - Add example links to MAINTAINERS.md files - Add SHOULD for working/interest groups - Add hyperlink to SEP guidelines - Require reference implementation before acceptance - Clarify minor updates don't need SEP review - Update graceful degradation to allow rejecting requests - Clarify backwards compatibility concerns for extensions - Update to RFC 2119 language throughout --- seps/2133-extensions.md | 40 +++++++++++++++++++++++----------------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/seps/2133-extensions.md b/seps/2133-extensions.md index 08eca53f6..5dd3f60ed 100644 --- a/seps/2133-extensions.md +++ b/seps/2133-extensions.md @@ -21,9 +21,13 @@ MCP currently lacks any form of guidance on how extensions are to be proposed or ### 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). +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`. 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](https://modelcontextprotocol.io/specification/draft/basic/index#meta), except that the prefix is mandatory. +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](https://modelcontextprotocol.io/specification/draft/basic/index#meta), 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. @@ -36,11 +40,12 @@ Official extensions live inside the MCP github org at https://github.com/modelco 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. +- 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](https://github.com/modelcontextprotocol/ext-auth/blob/main/MAINTAINERS.md), [ext-apps MAINTAINERS.md](https://github.com/modelcontextprotocol/ext-apps/blob/main/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 should use the same language as the core specification (i.e. [[BCP 14](https://www.rfc-editor.org/info/bcp14)] [[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)] [[RFC8174](https://datatracker.ietf.org/doc/html/rfc8174)]) and should be worded as if they were part of the core specification. +- Extension specifications MUST use the same language as the core specification (i.e. [[BCP 14](https://www.rfc-editor.org/info/bcp14)] [[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)] [[RFC8174](https://datatracker.ietf.org/doc/html/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. @@ -50,20 +55,21 @@ For official extensions, the lifecycle is similar to a SEP, but delegated to the 1. Author creates a SEP in the main MCP repository using the [standard SEP guidelines](https://modelcontextprotocol.io/community/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. 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_). +3. Extension SEPs MUST have at least one reference implementation in an official SDK before being accepted. This ensures the extension is practical and implementable. +4. 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). +5. Approved extensions MAY be implemented in additional clients / servers / SDKs (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. +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](http://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). +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 extensions. Where implemented, extensions MUST be disabled by default and require explicit opt-in. SDK documentation SHOULD list supported extensions. +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: @@ -73,9 +79,9 @@ SDK maintainers have full autonomy over extension support in their SDKs: ### 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. +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. +Extensions SHOULD be versioned, but exact versioning approach is not specified here. ### Negotiation @@ -154,7 +160,7 @@ if (hasUISupport) { #### Graceful Degradation -If one party supports an extension but the other does not, the supporting party MUST assume that features introduced by the extension will not work and revert to core protocol behavior. 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. +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. 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. ### Legal Requirements @@ -171,7 +177,7 @@ If one party supports an extension but the other does not, the supporting party #### Licensing -Official extensions must be available under the Apache 2.0 license. +Official extensions MUST be available under the Apache 2.0 license. #### Contributor License Grant @@ -213,17 +219,17 @@ Some specific design choices: ## Backward Compatibility -Extensions are purely additive in nature, so there are no backwards compatibility concerns. +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](https://github.com/modelcontextprotocol/ext-apps) and [ext-auth](https://github.com/modelcontextprotocol/ext-auth)), which already use the patterns specified here for capability negotiation and extension identifiers. -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). +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. +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. +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 From f19398725c6ef464e1f3af0214cfde3ff4f80325 Mon Sep 17 00:00:00 2001 From: Peter Alexander Date: Mon, 26 Jan 2026 14:31:44 +0000 Subject: [PATCH 6/6] Add extensions capability to schema and create extensions docs page - Add 'extensions' field to ClientCapabilities and ServerCapabilities in draft schema - Create extensions.mdx documentation page listing ext-auth and ext-apps - Add extensions navigation to docs.json under Community tab - Add Extension Negotiation section to lifecycle specification - Add example JSON files for extension capabilities - Regenerate schema.json and schema.mdx --- docs/community/seps/2133-extensions.mdx | 263 ++++++++++++++++++ docs/community/seps/index.mdx | 3 +- docs/docs.json | 9 +- docs/extensions.mdx | 68 +++++ docs/specification/draft/basic/lifecycle.mdx | 38 +++ docs/specification/draft/changelog.mdx | 2 +- docs/specification/draft/schema.mdx | 10 +- .../extensions-ui-mime-types.json | 7 + .../ServerCapabilities/extensions-ui.json | 5 + schema/draft/schema.json | 18 ++ schema/draft/schema.ts | 18 ++ seps/2133-extensions.md | 30 +- 12 files changed, 455 insertions(+), 16 deletions(-) create mode 100644 docs/community/seps/2133-extensions.mdx create mode 100644 docs/extensions.mdx create mode 100644 schema/draft/examples/ClientCapabilities/extensions-ui-mime-types.json create mode 100644 schema/draft/examples/ServerCapabilities/extensions-ui.json diff --git a/docs/community/seps/2133-extensions.mdx b/docs/community/seps/2133-extensions.mdx new file mode 100644 index 000000000..8382185d6 --- /dev/null +++ b/docs/community/seps/2133-extensions.mdx @@ -0,0 +1,263 @@ +--- +title: "SEP-2133: Extensions" +sidebarTitle: "SEP-2133: Extensions" +description: "Extensions" +--- + +import { Badge } from "/snippets/badge.mdx"; + +
+ Draft + Standards Track +
+ +| Field | Value | +| ------------- | ------------------------------------------------------------------------------- | +| **SEP** | 2133 | +| **Title** | Extensions | +| **Status** | Draft | +| **Type** | Standards Track | +| **Created** | 2025-01-21 | +| **Author(s)** | Peter Alexander ([@pja-ant](https://github.com/pja-ant)) | +| **Sponsor** | None (seeking sponsor) | +| **PR** | [#2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/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](https://modelcontextprotocol.io/specification/draft/basic/index#meta), 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](https://github.com/modelcontextprotocol/ext-auth/blob/main/MAINTAINERS.md), [ext-apps MAINTAINERS.md](https://github.com/modelcontextprotocol/ext-apps/blob/main/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](https://www.rfc-editor.org/info/bcp14)] [[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)] [[RFC8174](https://datatracker.ietf.org/doc/html/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](https://github.com/modelcontextprotocol/modelcontextprotocol/) using the [standard SEP guidelines](https://modelcontextprotocol.io/community/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](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/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](http://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](https://modelcontextprotocol.io/specification/2025-06-18/schema#clientcapabilities) and [ServerCapabilities](https://modelcontextprotocol.io/specification/2025-06-18/schema#servercapabilities) fields respectively, and in the [Server Card](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649) (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: + +```json +{ + "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: + +```json +{ + "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: + +```typescript +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. + +### Legal Requirements + +#### 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](https://github.com/modelcontextprotocol/ext-apps) and [ext-auth](https://github.com/modelcontextprotocol/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. diff --git a/docs/community/seps/index.mdx b/docs/community/seps/index.mdx index ecd16f2fe..d89b2bf2b 100644 --- a/docs/community/seps/index.mdx +++ b/docs/community/seps/index.mdx @@ -14,13 +14,14 @@ Specification Enhancement Proposals (SEPs) are the primary mechanism for proposi ## Summary -- **Draft**: 1 +- **Draft**: 2 - **Final**: 21 ## All SEPs | SEP | Title | Status | Type | Created | | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------- | --------------- | ---------- | +| [SEP-2133](/community/seps/2133-extensions) | Extensions | Draft | Standards Track | 2025-01-21 | | [SEP-2085](/community/seps/2085-governance-succession-and-amendment) | Governance Succession and Amendment Procedures | Draft | Process | 2025-12-05 | | [SEP-1850](/community/seps/1850-pr-based-sep-workflow) | PR-Based SEP Workflow | Final | Process | 2025-11-20 | | [SEP-1730](/community/seps/1730-sdks-tiering-system) | SDKs Tiering System | Final | Standards Track | 2025-10-29 | diff --git a/docs/docs.json b/docs/docs.json index 6c30ac426..a572ff76b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -376,11 +376,18 @@ { "group": "Draft", "pages": [ - "community/seps/2085-governance-succession-and-amendment" + "community/seps/2085-governance-succession-and-amendment", + "community/seps/2133-extensions" ] } ] }, + { + "group": "Extensions", + "pages": [ + "extensions" + ] + }, { "group": "Roadmap", "pages": [ diff --git a/docs/extensions.mdx b/docs/extensions.mdx new file mode 100644 index 000000000..e2a87d14c --- /dev/null +++ b/docs/extensions.mdx @@ -0,0 +1,68 @@ +--- +title: Extensions +description: Optional extensions to the Model Context Protocol +--- + +# MCP Extensions + +MCP extensions are optional additions to the specification that define 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`. Official extensions use the `io.modelcontextprotocol` vendor prefix. + +## Official Extension Repositories + +Official extensions live inside the [MCP GitHub org](https://github.com/modelcontextprotocol/) in repositories with the `ext-` prefix. + +### ext-auth + +**Repository:** [github.com/modelcontextprotocol/ext-auth](https://github.com/modelcontextprotocol/ext-auth) + +Extensions for supplementary authorization mechanisms beyond the core specification. + +| Extension | Description | Specification | +| -------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| OAuth Client Credentials | OAuth 2.0 client credentials flow for machine-to-machine authentication | [Link](https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/oauth-client-credentials.mdx) | +| Enterprise-Managed Authorization | Framework for enterprise environments requiring centralized access control | [Link](https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/enterprise-managed-authorization.mdx) | + +### ext-apps + +**Repository:** [github.com/modelcontextprotocol/ext-apps](https://github.com/modelcontextprotocol/ext-apps) + +Extensions for interactive UI elements in conversational MCP clients. + +| Extension | Description | Specification | +| --------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| MCP Apps | Allows MCP Servers to display interactive UI elements (charts, forms, video players) inline within conversations | [Link](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) | + +## Creating Extensions + +The lifecycle for official extensions is similar to a SEP, but delegated to extension repository maintainers: + +1. **Propose**: Author creates a SEP in the main MCP repository using the [standard SEP guidelines](/community/sep-guidelines) with type **Extensions Track**. +2. **Review**: Extension SEPs are reviewed by the relevant extension repository maintainers. +3. **Implement**: Extension SEPs **MUST** have at least one reference implementation in an official SDK before being accepted. +4. **Publish**: Once approved, the author produces a PR that introduces the extension to the extension repository. +5. **Adopt**: Approved extensions **MAY** be implemented in additional clients, servers, and SDKs. + +### Requirements + +- Extension specifications **MUST** use RFC 2119 language (MUST, SHOULD, MAY) +- Extensions **SHOULD** have an associated working group or interest group + +### 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 which extensions they support +- Extension support is not required for protocol conformance + +### Evolution + +Extensions evolve independently of the core protocol. Updates to extensions are managed by the extension repository maintainers and do not require core maintainer review. + +Extensions **MUST** consider backwards compatibility in their design: + +- Extensions **SHOULD** maintain backwards compatibility through capability flags or versioning within the extension settings object, rather than creating a new extension identifier +- When backwards-incompatible changes are unavoidable, a new extension identifier **MUST** be used (e.g., `io.modelcontextprotocol/my-extension-v2`) diff --git a/docs/specification/draft/basic/lifecycle.mdx b/docs/specification/draft/basic/lifecycle.mdx index fc3884f35..8464ceb54 100644 --- a/docs/specification/draft/basic/lifecycle.mdx +++ b/docs/specification/draft/basic/lifecycle.mdx @@ -196,6 +196,7 @@ Key capabilities include: | Client | `sampling` | Support for LLM [sampling](/specification/draft/client/sampling) requests | | Client | `elicitation` | Support for server [elicitation](/specification/draft/client/elicitation) requests | | Client | `tasks` | Support for [task-augmented](/specification/draft/basic/utilities/tasks) client requests | +| Client | `extensions` | Support for optional [extensions](/extensions) beyond the core protocol | | Client | `experimental` | Describes support for non-standard experimental features | | Server | `prompts` | Offers [prompt templates](/specification/draft/server/prompts) | | Server | `resources` | Provides readable [resources](/specification/draft/server/resources) | @@ -203,6 +204,7 @@ Key capabilities include: | Server | `logging` | Emits structured [log messages](/specification/draft/server/utilities/logging) | | Server | `completions` | Supports argument [autocompletion](/specification/draft/server/utilities/completion) | | Server | `tasks` | Support for [task-augmented](/specification/draft/basic/utilities/tasks) server requests | +| Server | `extensions` | Support for optional [extensions](/extensions) beyond the core protocol | | Server | `experimental` | Describes support for non-standard experimental features | Capability objects can describe sub-capabilities like: @@ -211,6 +213,42 @@ Capability objects can describe sub-capabilities like: tools) - `subscribe`: Support for subscribing to individual items' changes (resources only) +#### Extension Negotiation + +Clients and servers can also negotiate support for optional [extensions](/extensions) beyond the core protocol. Extensions are advertised in the `extensions` field of capabilities, which is a map of extension identifiers to per-extension settings objects. + +Example client capabilities with extensions: + +```json +{ + "capabilities": { + "roots": {}, + "extensions": { + "io.modelcontextprotocol/apps": { + "mimeTypes": ["text/html;profile=mcp-app"] + } + } + } +} +``` + +Example server capabilities with extensions: + +```json +{ + "capabilities": { + "tools": {}, + "extensions": { + "io.modelcontextprotocol/apps": {} + } + } +} +``` + +Each extension specifies the schema of its settings object; an empty object indicates support with no additional settings. + +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. Extensions **SHOULD** document their expected fallback behavior. + ### Operation During the operation phase, the client and server exchange messages according to the diff --git a/docs/specification/draft/changelog.mdx b/docs/specification/draft/changelog.mdx index 0a7766fce..c6b4f6132 100644 --- a/docs/specification/draft/changelog.mdx +++ b/docs/specification/draft/changelog.mdx @@ -13,7 +13,7 @@ N/A ## Minor changes -N/A +1. Add `extensions` field to `ClientCapabilities` and `ServerCapabilities` to support optional [extensions](/extensions) beyond the core protocol. ## Other schema changes diff --git a/docs/specification/draft/schema.mdx b/docs/specification/draft/schema.mdx index a9ae74012..61fa152bf 100644 --- a/docs/specification/draft/schema.mdx +++ b/docs/specification/draft/schema.mdx @@ -546,8 +546,10 @@ without nested objects or arrays.

### `ClientCapabilities` -
interface ClientCapabilities {
  experimental?: { [key: string]: object };
  roots?: { listChanged?: boolean };
  sampling?: { context?: object; tools?: object };
  elicitation?: { form?: object; url?: object };
  tasks?: {
    list?: object;
    cancel?: object;
    requests?: {
      sampling?: { createMessage?: object };
      elicitation?: { create?: object };
    };
  };
}

Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities.

Experimental, non-standard capabilities that the client supports.

Present if the client supports listing roots.

Type Declaration
  • OptionallistChanged?: boolean

    Whether the client supports notifications for changes to the roots list.

Example: Roots — minimum baseline support
{
  "roots": {}
}
Example: Roots — list changed notifications
{
  "roots": {
    "listChanged": true
  }
}

Present if the client supports sampling from an LLM.

Type Declaration
  • Optionalcontext?: object

    Whether the client supports context inclusion via includeContext parameter. -If not declared, servers SHOULD only use includeContext: "none" (or omit it).

  • Optionaltools?: object

    Whether the client supports tool use via tools and toolChoice parameters.

Example: Sampling — minimum baseline support
{
  "sampling": {}
}
Example: Sampling — tool use support
{
  "sampling": {
    "tools": {}
  }
}
Example: Sampling — context inclusion support (soft-deprecated)
{
  "sampling": {
    "context": {}
  }
}

Present if the client supports elicitation from the server.

Example: Elicitation — form and URL mode support
{
  "elicitation": {
    "form": {},
    "url": {}
  }
}
Example: Elicitation — form mode only (implicit)
{
  "elicitation": {}
}

Present if the client supports task-augmented requests.

Type Declaration
  • Optionallist?: object

    Whether this client supports tasks/list.

  • Optionalcancel?: object

    Whether this client supports tasks/cancel.

  • Optionalrequests?: { sampling?: { createMessage?: object }; elicitation?: { create?: object } }

    Specifies which request types can be augmented with tasks.

    • Optionalsampling?: { createMessage?: object }

      Task support for sampling-related requests.

      • OptionalcreateMessage?: object

        Whether the client supports task-augmented sampling/createMessage requests.

    • Optionalelicitation?: { create?: object }

      Task support for elicitation-related requests.

      • Optionalcreate?: object

        Whether the client supports task-augmented elicitation/create requests.

+
interface ClientCapabilities {
  experimental?: { [key: string]: object };
  roots?: { listChanged?: boolean };
  sampling?: { context?: object; tools?: object };
  elicitation?: { form?: object; url?: object };
  tasks?: {
    list?: object;
    cancel?: object;
    requests?: {
      sampling?: { createMessage?: object };
      elicitation?: { create?: object };
    };
  };
  extensions?: { [key: string]: object };
}

Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities.

Experimental, non-standard capabilities that the client supports.

Present if the client supports listing roots.

Type Declaration
  • OptionallistChanged?: boolean

    Whether the client supports notifications for changes to the roots list.

Example: Roots — minimum baseline support
{
  "roots": {}
}
Example: Roots — list changed notifications
{
  "roots": {
    "listChanged": true
  }
}

Present if the client supports sampling from an LLM.

Type Declaration
  • Optionalcontext?: object

    Whether the client supports context inclusion via includeContext parameter. +If not declared, servers SHOULD only use includeContext: "none" (or omit it).

  • Optionaltools?: object

    Whether the client supports tool use via tools and toolChoice parameters.

Example: Sampling — minimum baseline support
{
  "sampling": {}
}
Example: Sampling — tool use support
{
  "sampling": {
    "tools": {}
  }
}
Example: Sampling — context inclusion support (soft-deprecated)
{
  "sampling": {
    "context": {}
  }
}

Present if the client supports elicitation from the server.

Example: Elicitation — form and URL mode support
{
  "elicitation": {
    "form": {},
    "url": {}
  }
}
Example: Elicitation — form mode only (implicit)
{
  "elicitation": {}
}

Present if the client supports task-augmented requests.

Type Declaration
  • Optionallist?: object

    Whether this client supports tasks/list.

  • Optionalcancel?: object

    Whether this client supports tasks/cancel.

  • Optionalrequests?: { sampling?: { createMessage?: object }; elicitation?: { create?: object } }

    Specifies which request types can be augmented with tasks.

    • Optionalsampling?: { createMessage?: object }

      Task support for sampling-related requests.

      • OptionalcreateMessage?: object

        Whether the client supports task-augmented sampling/createMessage requests.

    • Optionalelicitation?: { create?: object }

      Task support for elicitation-related requests.

      • Optionalcreate?: object

        Whether the client supports task-augmented elicitation/create requests.

Optional MCP extensions that the client supports. Keys are extension identifiers +(e.g., "io.modelcontextprotocol/oauth-client-credentials"), and values are +per-extension settings objects. An empty object indicates support with no settings.

Example: Extensions — UI extension with MIME type support
{
  "extensions": {
    "io.modelcontextprotocol/apps": {
      "mimeTypes": ["text/html;profile=mcp-app"]
    }
  }
}
@@ -568,7 +570,9 @@ or tools it provides, while a client might describe its intended use case.

< ### `ServerCapabilities` -
interface ServerCapabilities {
  experimental?: { [key: string]: object };
  logging?: object;
  completions?: object;
  prompts?: { listChanged?: boolean };
  resources?: { subscribe?: boolean; listChanged?: boolean };
  tools?: { listChanged?: boolean };
  tasks?: {
    list?: object;
    cancel?: object;
    requests?: { tools?: { call?: object } };
  };
}

Capabilities that a server may support. Known capabilities are defined here, in this schema, but this is not a closed set: any server can define its own, additional capabilities.

Experimental, non-standard capabilities that the server supports.

Present if the server supports sending log messages to the client.

Example: Logging — minimum baseline support
{
  "logging": {}
}

Present if the server supports argument autocompletion suggestions.

Example: Completions — minimum baseline support
{
  "completions": {}
}

Present if the server offers any prompt templates.

Type Declaration
  • OptionallistChanged?: boolean

    Whether this server supports notifications for changes to the prompt list.

Example: Prompts — minimum baseline support
{
  "prompts": {}
}
Example: Prompts — list changed notifications
{
  "prompts": {
    "listChanged": true
  }
}

Present if the server offers any resources to read.

Type Declaration
  • Optionalsubscribe?: boolean

    Whether this server supports subscribing to resource updates.

  • OptionallistChanged?: boolean

    Whether this server supports notifications for changes to the resource list.

Example: Resources — minimum baseline support
{
  "resources": {}
}
Example: Resources — subscription to individual resource updates (only)
{
  "resources": {
    "subscribe": true
  }
}
Example: Resources — list changed notifications (only)
{
  "resources": {
    "listChanged": true
  }
}
Example: Resources — all notifications
{
  "resources": {
    "subscribe": true,
    "listChanged": true
  }
}

Present if the server offers any tools to call.

Type Declaration
  • OptionallistChanged?: boolean

    Whether this server supports notifications for changes to the tool list.

Example: Tools — minimum baseline support
{
  "tools": {}
}
Example: Tools — list changed notifications
{
  "tools": {
    "listChanged": true
  }
}

Present if the server supports task-augmented requests.

Type Declaration
  • Optionallist?: object

    Whether this server supports tasks/list.

  • Optionalcancel?: object

    Whether this server supports tasks/cancel.

  • Optionalrequests?: { tools?: { call?: object } }

    Specifies which request types can be augmented with tasks.

    • Optionaltools?: { call?: object }

      Task support for tool-related requests.

      • Optionalcall?: object

        Whether the server supports task-augmented tools/call requests.

+
interface ServerCapabilities {
  experimental?: { [key: string]: object };
  logging?: object;
  completions?: object;
  prompts?: { listChanged?: boolean };
  resources?: { subscribe?: boolean; listChanged?: boolean };
  tools?: { listChanged?: boolean };
  tasks?: {
    list?: object;
    cancel?: object;
    requests?: { tools?: { call?: object } };
  };
  extensions?: { [key: string]: object };
}

Capabilities that a server may support. Known capabilities are defined here, in this schema, but this is not a closed set: any server can define its own, additional capabilities.

Experimental, non-standard capabilities that the server supports.

Present if the server supports sending log messages to the client.

Example: Logging — minimum baseline support
{
  "logging": {}
}

Present if the server supports argument autocompletion suggestions.

Example: Completions — minimum baseline support
{
  "completions": {}
}

Present if the server offers any prompt templates.

Type Declaration
  • OptionallistChanged?: boolean

    Whether this server supports notifications for changes to the prompt list.

Example: Prompts — minimum baseline support
{
  "prompts": {}
}
Example: Prompts — list changed notifications
{
  "prompts": {
    "listChanged": true
  }
}

Present if the server offers any resources to read.

Type Declaration
  • Optionalsubscribe?: boolean

    Whether this server supports subscribing to resource updates.

  • OptionallistChanged?: boolean

    Whether this server supports notifications for changes to the resource list.

Example: Resources — minimum baseline support
{
  "resources": {}
}
Example: Resources — subscription to individual resource updates (only)
{
  "resources": {
    "subscribe": true
  }
}
Example: Resources — list changed notifications (only)
{
  "resources": {
    "listChanged": true
  }
}
Example: Resources — all notifications
{
  "resources": {
    "subscribe": true,
    "listChanged": true
  }
}

Present if the server offers any tools to call.

Type Declaration
  • OptionallistChanged?: boolean

    Whether this server supports notifications for changes to the tool list.

Example: Tools — minimum baseline support
{
  "tools": {}
}
Example: Tools — list changed notifications
{
  "tools": {
    "listChanged": true
  }
}

Present if the server supports task-augmented requests.

Type Declaration
  • Optionallist?: object

    Whether this server supports tasks/list.

  • Optionalcancel?: object

    Whether this server supports tasks/cancel.

  • Optionalrequests?: { tools?: { call?: object } }

    Specifies which request types can be augmented with tasks.

    • Optionaltools?: { call?: object }

      Task support for tool-related requests.

      • Optionalcall?: object

        Whether the server supports task-augmented tools/call requests.

Optional MCP extensions that the server supports. Keys are extension identifiers +(e.g., "io.modelcontextprotocol/apps"), and values are per-extension settings +objects. An empty object indicates support with no settings.

Example: Extensions — UI extension support
{
  "extensions": {
    "io.modelcontextprotocol/apps": {}
  }
}
diff --git a/schema/draft/examples/ClientCapabilities/extensions-ui-mime-types.json b/schema/draft/examples/ClientCapabilities/extensions-ui-mime-types.json new file mode 100644 index 000000000..039913f83 --- /dev/null +++ b/schema/draft/examples/ClientCapabilities/extensions-ui-mime-types.json @@ -0,0 +1,7 @@ +{ + "extensions": { + "io.modelcontextprotocol/apps": { + "mimeTypes": ["text/html;profile=mcp-app"] + } + } +} diff --git a/schema/draft/examples/ServerCapabilities/extensions-ui.json b/schema/draft/examples/ServerCapabilities/extensions-ui.json new file mode 100644 index 000000000..f05e3c628 --- /dev/null +++ b/schema/draft/examples/ServerCapabilities/extensions-ui.json @@ -0,0 +1,5 @@ +{ + "extensions": { + "io.modelcontextprotocol/apps": {} + } +} diff --git a/schema/draft/schema.json b/schema/draft/schema.json index 2cc2c74fb..075c741bf 100644 --- a/schema/draft/schema.json +++ b/schema/draft/schema.json @@ -353,6 +353,15 @@ "description": "Experimental, non-standard capabilities that the client supports.", "type": "object" }, + "extensions": { + "additionalProperties": { + "additionalProperties": true, + "properties": {}, + "type": "object" + }, + "description": "Optional MCP extensions that the client supports. Keys are extension identifiers\n(e.g., \"io.modelcontextprotocol/oauth-client-credentials\"), and values are\nper-extension settings objects. An empty object indicates support with no settings.", + "type": "object" + }, "roots": { "description": "Present if the client supports listing roots.", "properties": { @@ -3338,6 +3347,15 @@ "description": "Experimental, non-standard capabilities that the server supports.", "type": "object" }, + "extensions": { + "additionalProperties": { + "additionalProperties": true, + "properties": {}, + "type": "object" + }, + "description": "Optional MCP extensions that the server supports. Keys are extension identifiers\n(e.g., \"io.modelcontextprotocol/apps\"), and values are per-extension settings\nobjects. An empty object indicates support with no settings.", + "type": "object" + }, "logging": { "additionalProperties": true, "description": "Present if the server supports sending log messages to the client.", diff --git a/schema/draft/schema.ts b/schema/draft/schema.ts index 6c052cb35..bdd0583ff 100644 --- a/schema/draft/schema.ts +++ b/schema/draft/schema.ts @@ -548,6 +548,15 @@ export interface ClientCapabilities { }; }; }; + /** + * Optional MCP extensions that the client supports. Keys are extension identifiers + * (e.g., "io.modelcontextprotocol/oauth-client-credentials"), and values are + * per-extension settings objects. An empty object indicates support with no settings. + * + * @example Extensions — UI extension with MIME type support + * {@includeCode ./examples/ClientCapabilities/extensions-ui-mime-types.json} + */ + extensions?: { [key: string]: object }; } /** @@ -656,6 +665,15 @@ export interface ServerCapabilities { }; }; }; + /** + * Optional MCP extensions that the server supports. Keys are extension identifiers + * (e.g., "io.modelcontextprotocol/apps"), and values are per-extension settings + * objects. An empty object indicates support with no settings. + * + * @example Extensions — UI extension support + * {@includeCode ./examples/ServerCapabilities/extensions-ui.json} + */ + extensions?: { [key: string]: object }; } /** diff --git a/seps/2133-extensions.md b/seps/2133-extensions.md index 5dd3f60ed..7c9c42b06 100644 --- a/seps/2133-extensions.md +++ b/seps/2133-extensions.md @@ -3,9 +3,9 @@ - **Status**: Draft - **Type**: Standards Track - **Created**: 2025-01-21 -- **Author(s)**: Peter Alexander (@pja-ant) +- **Author(s)**: Peter Alexander (@pja-ant) - **Sponsor**: None (seeking sponsor) -- **PR**: [#2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133) +- **PR**: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133 ## Abstract @@ -51,15 +51,25 @@ While day-to-day governance is delegated to extension repository maintainers, th ### Lifecycle -For official extensions, the lifecycle is similar to a SEP, but delegated to the extension repository maintainers: +#### Creation -1. Author creates a SEP in the main MCP repository using the [standard SEP guidelines](https://modelcontextprotocol.io/community/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. -2. Extension SEPs are reviewed by the relevant extension repository maintainers. -3. Extension SEPs MUST have at least one reference implementation in an official SDK before being accepted. This ensures the extension is practical and implementable. -4. 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). -5. Approved extensions MAY be implemented in additional clients / servers / SDKs (see _SDK Implementation_). +Extensions are initially created via a SEP in the [main MCP repository](https://github.com/modelcontextprotocol/modelcontextprotocol/) using the [standard SEP guidelines](https://modelcontextprotocol.io/community/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](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2148) for how maintainers are appointed. -Eventually, some extensions MAY transition to being core protocol features. This SHOULD be treated as a standard protocol SEP with separate core maintainer review. +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 @@ -160,7 +170,7 @@ if (hasUISupport) { #### 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. 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. +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. ### Legal Requirements