Extensions Overview
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. Identifiers follow the same rules as _meta keys, with a mandatory prefix. Official extensions use the io.modelcontextprotocol vendor prefix.
example.com would use com.example/ as their prefix (e.g., com.example/my-extension).Extension Lifecycle
Every extension is at one of three stages, and may later be promoted into the core specification. The stage decides which changes are allowed, who approves them, and what implementers can expect. For full details, see SEP-3392: Extension Lifecycle.
| Stage | Protocol changes | Changes approved by | Entry | What implementers can expect |
|---|---|---|---|---|
| Experimental | Any change, at any time, without notice | Extension Maintainer | Added by an Extension Maintainer | Nothing. The design may change or disappear. |
| Beta | Any change, with breaking changes expected to be rare | Extension Maintainer | Extensions Track SEP | Real usage is welcome. Breaking changes are documented. |
| Stable | Only with a new core protocol revision | Extension Maintainer | Second Extensions Track SEP | Behavior is fixed within a protocol revision. |
An extension starts as Experimental and must pass through Beta. From Beta it either becomes Stable, or a Standards Track SEP promotes it into the core specification. A Stable extension can also be promoted later. Each Beta extension states its intended destination, Stable or Core, which may change while it is in Beta.
An extension’s identifier does not change when its stage changes.
Official Extension Repositories
Official extensions live inside the Model Context Protocol GitHub organization in repositories with the ext- prefix. One repository can hold several related extensions at different stages. Inside the repository, the directory that holds an extension’s specification shows its stage: specification/experimental/, specification/beta/ or specification/stable/. Extensions that were promoted to the core specification or have ended move to specification/archived/.
MCP Authorization Extensions
modelcontextprotocol/ext-auth
Extensions for supplementary authorization mechanisms beyond the core specification.
| Extension | Stage | Description |
|---|---|---|
| OAuth Client Credentials | Stable | OAuth 2.0 client credentials flow for machine-to-machine authentication. |
| Enterprise-Managed Authorization | Stable | Framework for enterprise environments requiring centralized access control. |
MCP Apps
modelcontextprotocol/ext-apps
Extensions for interactive UI elements in conversational MCP clients.
| Extension | Stage | Description |
|---|---|---|
| MCP Apps | Stable | Allows MCP Servers to display interactive UI elements (charts, forms, video players) inline within conversations |
To get started building MCP Apps, see the quickstart guide or read the full MCP Apps documentation.
MCP Tasks
modelcontextprotocol/ext-tasks
Extensions for long-running operations.
| Extension | Stage | Description |
|---|---|---|
| MCP Tasks | Beta, to Core | Asynchronous task execution for long-running operations, with polling, mid-flight input, and durable handles. |
Skills over MCP
modelcontextprotocol/ext-skills
Discover and read Agent Skills from MCP servers.
| Extension | Stage | Description |
|---|---|---|
| Skills over MCP | Beta, destination not yet stated | Discover workflow instructions and read supporting files through MCP resources. |
See the Skills overview to get started and the client matrix for implementation support.
MCP Server Cards
modelcontextprotocol/ext-server-card
HTTP discovery of MCP server metadata.
| Extension | Stage | Description |
|---|---|---|
| Server Cards | Beta, destination not yet stated | Lets clients discover a server’s metadata before connecting to it. |
Experimental Extensions
Experimental extensions provide an incubation pathway for Working Groups and Interest Groups to prototype ideas and collaborate on extension concepts before or alongside a SEP.
An Experimental extension lives either under specification/experimental/ in an existing ext- repository, or in its own repository with the experimental-ext- prefix (e.g., experimental-ext-interceptors). Everything in an experimental-ext- repository is Experimental.
Ground Rules
- Every experimental extension needs to be associated with a Working Group or Interest Group
- Published packages need to clearly indicate their experimental status (e.g., in the README and package name)
- Implementers should pin to a tag or commit, because two revisions of an Experimental extension need not be compatible
- Core Maintainers retain oversight of experimental extensions, including the ability to archive or remove them
Creating Extensions
- Prototype: Add the extension under
specification/experimental/in anext-repository, or create anexperimental-ext-repository. - Propose Beta: Create a SEP in the main MCP repository using the standard SEP guidelines with type Extensions Track. State whether the extension is intended to become Stable or to be promoted to Core.
- Implement: Build at least one reference implementation in an official SDK. This is required before the SEP can be reviewed.
- Review: Core Maintainers review the SEP and have final authority over inclusion.
- Publish: Once the SEP is accepted, open a PR that moves the extension to
specification/beta/in anext-repository. A Core Maintainer approves the move. - Gather evidence: During Beta, keep a public list of known implementations and the feedback received from them.
- Stabilize or promote: A second Extensions Track SEP moves the extension to Stable. It needs two independent, interoperating implementations (one client-side, one server-side) and a conformance scenario. Alternatively, a Standards Track SEP promotes the extension into the core specification.
Requirements
- Extension specifications need to use RFC 2119 language (MUST, SHOULD, MAY)
- Extensions must have an associated working group or interest group, and at least one Extension Maintainer listed in the repository’s
MAINTAINERS.md
SDK Implementation
SDKs can choose to implement extensions, but it’s not required for protocol conformance. SDK maintainers have full autonomy over which extensions they support. Where an SDK does support extensions, SDK documentation should list which extensions are supported.
Evolution
Changes to an extension are approved by its Extension Maintainers and don’t require Core Maintainer review. What may change depends on the stage:
- Experimental: anything, at any time.
- Beta: prefer additive changes, such as new optional fields or capability flags in the settings object. Breaking changes are allowed but should be rare and batched, announced in the Working Group or Interest Group first, and recorded in a changelog. An extension that makes a breaking change should add or increment a
revisionstring in its settings object, so that peers can detect a mismatch. - Stable: published as revisions keyed to core protocol revisions, such as
specification/stable/<name>/2026-07-28/. A published revision is immutable. Changes accumulate in adraft/directory and take effect only with a new core protocol revision. The behavior of the extension for a pair of peers is the behavior defined for the protocol revision they negotiate.
Breaking changes keep the extension’s identifier. A new identifier (e.g., io.modelcontextprotocol/my-extension-v2) is used only when old and new behavior must coexist under one protocol revision.
A breaking change is any modification that would cause existing implementations to fail or behave incorrectly, including:
- Removing or renaming fields
- Changing field types
- Altering the semantics of existing behavior
- Adding new required fields
Promotion to Core
When a Standards Track SEP promotes an extension into the core specification in protocol revision R, the feature is core behavior for requests that declare R or later, whether or not the extension is advertised. For earlier revisions, the extension’s final revision still applies, so a client that supports earlier revisions should keep advertising the extension. The extension’s specification moves to specification/archived/ once R is released.
Negotiation
Clients and servers advertise their support for extensions in the extensions field within their respective capability declarations.
The examples below use protocol version 2026-07-28 and later. For 2025-11-25 and earlier, see Initialization-Based Versions.
Client Capabilities
Clients advertise extension support in _meta["io.modelcontextprotocol/clientCapabilities"] within each request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"location": "New York"
},
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {
"extensions": {
"io.modelcontextprotocol/ui": {
"mimeTypes": ["text/html;profile=mcp-app"]
}
}
},
"io.modelcontextprotocol/clientInfo": {
"name": "ExampleClient",
"version": "1.0.0"
}
}
}
}Server Capabilities
Servers advertise extension support in the server/discover response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resultType": "complete",
"supportedVersions": ["2026-07-28"],
"capabilities": {
"tools": {},
"extensions": {
"io.modelcontextprotocol/ui": {}
}
},
"_meta": {
"io.modelcontextprotocol/serverInfo": {
"name": "ExampleServer",
"version": "1.0.0"
}
},
"ttlMs": 3600000,
"cacheScope": "public"
}
}Each extension specifies the schema of its settings object; an empty object indicates no settings.
Initialization-Based Versions
Extensions became an official part of the protocol in version 2026-07-28. Before that, many SDKs, clients, and servers already negotiated extensions on 2025-11-25 and earlier during the initialize handshake, using params.capabilities.extensions in the request and result.capabilities.extensions in the response. The extension identifiers and settings objects follow the same rules as above.
extensions field is not part of the published schemas for these protocol versions, and supporting it is not required for conformance. SDKs that can carry capabilities.extensions through initialize are encouraged to do so, so that extensions work consistently across protocol versions. Check that your SDK can send and receive this field, and that the extension supports the negotiated protocol version. If the other side’s capabilities omit extensions, or omit a given extension, treat that extension as unsupported and follow Graceful Degradation.Client request
Clients advertise extension support in the initialize request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {
"roots": {
"listChanged": true
},
"extensions": {
"io.modelcontextprotocol/ui": {
"mimeTypes": ["text/html;profile=mcp-app"]
}
}
},
"clientInfo": {
"name": "ExampleClient",
"version": "1.0.0"
}
}
}Server response
Servers advertise extension support in the initialize response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2025-11-25",
"capabilities": {
"tools": {},
"extensions": {
"io.modelcontextprotocol/ui": {}
}
},
"serverInfo": {
"name": "ExampleServer",
"version": "1.0.0"
}
}
}Graceful Degradation
If one side supports an extension but the other doesn’t, the supporting side needs to either fall back to core protocol behavior or reject the request with an appropriate error if the extension is mandatory.
It’s a good practice to document expected fallback behavior in your extension. For example, a server offering UI-enhanced tools should still return meaningful text content for clients that don’t support the UI extension. On the other hand, a server that requires a specific authentication extension can reject connections from clients that don’t support it.