Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
263 changes: 263 additions & 0 deletions docs/community/seps/2133-extensions.mdx

Large diffs are not rendered by default.

3 changes: 2 additions & 1 deletion docs/community/seps/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 | <Badge color="gray">Draft</Badge> | Standards Track | 2025-01-21 |
| [SEP-2085](/community/seps/2085-governance-succession-and-amendment) | Governance Succession and Amendment Procedures | <Badge color="gray">Draft</Badge> | Process | 2025-12-05 |
| [SEP-1850](/community/seps/1850-pr-based-sep-workflow) | PR-Based SEP Workflow | <Badge color="green">Final</Badge> | Process | 2025-11-20 |
| [SEP-1730](/community/seps/1730-sdks-tiering-system) | SDKs Tiering System | <Badge color="green">Final</Badge> | Standards Track | 2025-10-29 |
Expand Down
9 changes: 8 additions & 1 deletion docs/docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down
68 changes: 68 additions & 0 deletions docs/extensions.mdx
Original file line number Diff line number Diff line change
@@ -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`)
38 changes: 38 additions & 0 deletions docs/specification/draft/basic/lifecycle.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -196,13 +196,15 @@ 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) |
| Server | `tools` | Exposes callable [tools](/specification/draft/server/tools) |
| 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:
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/specification/draft/changelog.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
10 changes: 7 additions & 3 deletions docs/specification/draft/schema.mdx

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"extensions": {
"io.modelcontextprotocol/apps": {
"mimeTypes": ["text/html;profile=mcp-app"]
}
}
}
5 changes: 5 additions & 0 deletions schema/draft/examples/ServerCapabilities/extensions-ui.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"extensions": {
"io.modelcontextprotocol/apps": {}
}
}
18 changes: 18 additions & 0 deletions schema/draft/schema.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

18 changes: 18 additions & 0 deletions schema/draft/schema.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 };
}

/**
Expand Down Expand Up @@ -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 };
}

/**
Expand Down
Loading