SEP-1761: Add MCP extensions framework by pja-ant · Pull Request #1761 · modelcontextprotocol/modelcontextprotocol

pja-ant · 2025-11-03T16:50:10Z

Specification of #1724 (pending acceptance).

Changes:

Add extensions field to ClientCapabilities and ServerCapabilities
Add extension negotiation section to lifecycle documentation
Add extensions overview to architecture documentation
Create /extensions page with Overview and Registry subpages
Link ext-auth repository and its OAuth 2.0 and Enterprise-Managed Authorization extensions in registry

Motivation and Context

Implementing SEP.

How Has This Been Tested?

Local docs generation / manual read.

Breaking Changes

N/A

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

This commit implements the extensions framework as outlined in SEP-1724, allowing optional, composable extensions to the MCP protocol. Changes: - Add extensions field to ClientCapabilities and ServerCapabilities - Add extension negotiation section to lifecycle documentation - Add extensions overview to architecture documentation - Create /extensions page with Overview and Registry subpages - Document extension types (Official, Recommended, Unofficial) - Document extension identifier format and vendor prefix reservation rules - Add examples showing extension negotiation in initialize request/response - Link ext-auth repository and its OAuth 2.0 and Enterprise-Managed Authorization extensions in registry The extensions field is nested within capabilities and follows the same vendor prefix reservation rules as _meta fields. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

jonathanhefner

Nice! 😄

docs/extensions/index.mdx

docs/specification/draft/basic/lifecycle.mdx

jonathanhefner · 2025-11-04T16:26:35Z

schema/draft/schema.ts

+  /**
+   * Optional extensions that the client supports.
+   *
+   * Keys are extension identifiers in the format `{vendor-prefix}/{extension-name}`.
+   * The vendor-prefix follows the same format and reservation rules as prefixes in _meta.
+   * Prefixes containing `modelcontextprotocol` or `mcp` are reserved for MCP use.
+   *
+   * Values are optional configuration objects specific to each extension.
+   *
+   * Examples:
+   * - `modelcontextprotocol.io/official-extension`
+   * - `example.com/custom-extension`
+   *
+   * An empty object `{}` indicates support without additional configuration.
+   */
+  extensions?: { [key: string]: object };


I really like including all this documentation in the TypeDoc, but it would be nice to deduplicate between ClientCapabilities and ServerCapabilities.

jonathanhefner · 2025-11-04T16:27:52Z

schema/draft/schema.ts

+   * Keys are extension identifiers in the format `{vendor-prefix}/{extension-name}`.
+   * The vendor-prefix follows the same format and reservation rules as prefixes in _meta.
+   * Prefixes containing `modelcontextprotocol` or `mcp` are reserved for MCP use.
+   *
+   * Values are optional configuration objects specific to each extension.
+   *
+   * Examples:
+   * - `modelcontextprotocol.io/official-extension`
+   * - `example.com/custom-extension`
+   *
+   * An empty object `{}` indicates support without additional configuration.


Seems like the grouping should be:

Suggested change

* Keys are extension identifiers in the format `{vendor-prefix}/{extension-name}`.

* The vendor-prefix follows the same format and reservation rules as prefixes in _meta.

* Prefixes containing `modelcontextprotocol` or `mcp` are reserved for MCP use.

*

* Values are optional configuration objects specific to each extension.

*

* Examples:

* - `modelcontextprotocol.io/official-extension`

* - `example.com/custom-extension`

*

* An empty object `{}` indicates support without additional configuration.

* Keys are extension identifiers in the format `{vendor-prefix}/{extension-name}`.

* The vendor-prefix follows the same format and reservation rules as prefixes in `_meta`.

* Prefixes containing `modelcontextprotocol` or `mcp` are reserved for MCP use.

*

* Examples:

* - `modelcontextprotocol.io/official-extension`

* - `example.com/custom-extension`

*

* Values are optional configuration objects specific to each extension.

* An empty object `{}` indicates support without additional configuration.

jonathanhefner · 2025-11-04T16:28:13Z

schema/draft/schema.ts

+   * Keys are extension identifiers in the format `{vendor-prefix}/{extension-name}`.
+   * The vendor-prefix follows the same format and reservation rules as prefixes in _meta.
+   * Prefixes containing `modelcontextprotocol` or `mcp` are reserved for MCP use.
+   *
+   * Values are optional configuration objects specific to each extension.
+   *
+   * Examples:
+   * - `modelcontextprotocol.io/official-extension`
+   * - `example.com/custom-extension`
+   *
+   * An empty object `{}` indicates support without additional configuration.


Suggested change

* Keys are extension identifiers in the format `{vendor-prefix}/{extension-name}`.

* The vendor-prefix follows the same format and reservation rules as prefixes in _meta.

* Prefixes containing `modelcontextprotocol` or `mcp` are reserved for MCP use.

*

* Values are optional configuration objects specific to each extension.

*

* Examples:

* - `modelcontextprotocol.io/official-extension`

* - `example.com/custom-extension`

*

* An empty object `{}` indicates support without additional configuration.

* Keys are extension identifiers in the format `{vendor-prefix}/{extension-name}`.

* The vendor-prefix follows the same format and reservation rules as prefixes in `_meta`.

* Prefixes containing `modelcontextprotocol` or `mcp` are reserved for MCP use.

*

* Examples:

* - `modelcontextprotocol.io/official-extension`

* - `example.com/custom-extension`

*

* Values are optional configuration objects specific to each extension.

* An empty object `{}` indicates support without additional configuration.

jonathanhefner · 2025-11-04T16:30:18Z

schema/draft/schema.ts

+   *
+   * Keys are extension identifiers in the format `{vendor-prefix}/{extension-name}`.
+   * The vendor-prefix follows the same format and reservation rules as prefixes in _meta.
+   * Prefixes containing `modelcontextprotocol` or `mcp` are reserved for MCP use.


Does this need to be more specific? Or do we just want to delegate explanation to the _meta documentation?

Or perhaps it would be better to factor out "reserved key" documentation, and point both _meta and extensions at that.

dsp-ant · 2025-11-05T12:08:06Z

docs/extensions/index.mdx

+
+## What are Extensions?
+
+Extensions allow the MCP ecosystem to evolve and experiment with new capabilities while maintaining core protocol stability. An extension is appropriate when:


My interpretation is that extensions are not necessarily for experimentation. They can serve a certain domain. For example MCP-UI might be an extension that is only for clients that support HTML rendering. The Financial Services Interest Group would define an extension that is only applicable to MCP clients in the financial sector. These are more than just mere experimentations.

The intention was for these to be an "or" (i.e. experimental and/or scoped, rather than both) - does that make sense? Or you don't feel extensions should be used for experimental features at all?

dsp-ant · 2025-11-05T12:08:40Z

docs/extensions/index.mdx

+Extensions allow the MCP ecosystem to evolve and experiment with new capabilities while maintaining core protocol stability. An extension is appropriate when:
+
+- **Experimental** - There is sufficient uncertainty about an approach that would make it premature for the core specification
+- **Scoped** - The functionality is useful to a significant subset of users (e.g., specific industries or use cases) but may not be broadly applicable


II feel this is more important than experimentation. I think the protocol has enough facilities for experimentation already.

dsp-ant · 2025-11-05T12:13:34Z

docs/extensions/index.mdx

+- `modelcontextprotocol.io/official-extension` (official)
+- `example.com/custom-extension` (recommended or unofficial)
+- `mycompany.io/proprietary-feature` (unofficial)


At this point we should probably define this label mechanism with a reverse-dns name as a prefix in a central way. This is not necessarily part of this SEP, but we should do this, given it shows up everywhere now.

There's a separate PR for that. Will update if/when that is accepted.

dsp-ant · 2025-11-05T12:14:37Z

docs/extensions/index.mdx

+
+## Extension Negotiation
+
+Extensions are negotiated during the MCP initialization phase through the `extensions` field within capabilities in the initialize request and response.


One of the interesting pieces here is seeing if extensions will require versioning as well. This could explode the complexity in negotiation. Curious what you think.

The SEP does not specify anything about versioning and version negotiation of extensions to keep things simple. Extensions may choose to speicfy that if they like (and they could implement using the per-extention capabilities). I agree that trying to specify this in a general way could be complex, which is why I've avoided it in this intentionally lightweight SEP, but the capabilities struct does provide some mechanisms if individual extensions need it.

dsp-ant · 2025-11-05T12:18:03Z

docs/extensions/index.mdx

+}
+```
+
+### Extension Configuration


We don't allow configuration in MCP in-band via the protocol. This was a deliberate choice and learning from LSP. I do believe this remains true for extensions.

Mabye "configuration" is the wrong name here, it's more capabilities within the extension that you can use similar to existing core capabilities, but scoped to extensions. I'll rename to capabilities.

dsp-ant · 2025-11-05T12:18:44Z

docs/extensions/index.mdx

+
+See the [SEP guidelines](/community/sep-guidelines) for detailed information about the SEP process and the extension governance model.
+
+## Extension Governance


This needs to go into detail on governance requirements for externally maintained extensions.

dsp-ant · 2025-11-05T12:19:54Z

docs/extensions/index.mdx

+| Type            | Description                                                                                                           | Governance                                   |
+| --------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| **Official**    | Maintained in MCP GitHub organization under `ext-` prefixed repositories                                              | Core maintainer review and approval required |
+| **Recommended** | Community-developed extensions that are vetted by core maintainers and listed in the [registry](/extensions/registry) | Listed after review                          |


If we have extensions that are maintained outside of the MCP organisation, we need to have a set of criteria or at least a lifecycle, to determine how we add and most importantly, remove recommendations for extensions. We need a set of minimum standard required in terms of licenses, usage, trademarks, etc.

Co-authored-by: Jonathan Hefner <jonathan@hefner.pro>

pja-ant · 2026-01-22T15:47:27Z

Replacing with #2133

mintlify bot deployed to staging - docs November 3, 2025 16:54 View deployment

Update generated JSON schema for extensions field

04513cc

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

pja-ant mentioned this pull request Nov 3, 2025

SEP-1724: Extensions #1724

Closed

jonathanhefner reviewed Nov 4, 2025

View reviewed changes

dsp-ant reviewed Nov 5, 2025

View reviewed changes

localden linked an issue Nov 6, 2025 that may be closed by this pull request

SEP-1724: Extensions #1724

Closed

pja-ant and others added 2 commits November 6, 2025 18:18

Update docs/extensions/index.mdx

af69a5d

Co-authored-by: Jonathan Hefner <jonathan@hefner.pro>

Update docs/extensions/index.mdx

3cb3748

Co-authored-by: Jonathan Hefner <jonathan@hefner.pro>

mintlify bot deployed to staging - docs November 6, 2025 18:18 View deployment

pja-ant added 10 commits November 6, 2025 18:25

Improve extensions overview

df7e527

Add vendor prefix to recommended extensions

da4dbe9

use 'custom vendor' language

f142d8b

SHOULD emphasis

b4d20b9

Rename extension configuration to extension capabilities

79718b0

update list order

f705b2c

update negotiation section

cb218e2

remove broken link

54f11d9

Refactor table + submission list update

849b9b3

update list oreder

5a64cb4

mintlify bot deployed to staging - docs November 6, 2025 21:36 View deployment

simplify architecture section

aac3d29

mintlify bot deployed to staging - docs November 6, 2025 21:42 View deployment

lifecycle page fixes

d6934d4

mintlify bot deployed to staging - docs November 6, 2025 21:43 View deployment

dsp-ant added SEP proposal SEP proposal without a sponsor. labels Jan 14, 2026

localden added this to SEP Review Pipeline Jan 21, 2026

localden changed the title ~~Add MCP extensions framework (SEP-1724)~~ SEP-1761: Add MCP extensions framework Jan 21, 2026

pja-ant closed this Jan 22, 2026

localden removed this from SEP Review Pipeline Jan 28, 2026


		## What are Extensions?

		Extensions allow the MCP ecosystem to evolve and experiment with new capabilities while maintaining core protocol stability. An extension is appropriate when:


		## Extension Negotiation

		Extensions are negotiated during the MCP initialization phase through the `extensions` field within capabilities in the initialize request and response.


		See the [SEP guidelines](/community/sep-guidelines) for detailed information about the SEP process and the extension governance model.

		## Extension Governance

Conversation

pja-ant commented Nov 3, 2025

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

jonathanhefner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pja-ant commented Jan 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants