|
| 1 | +--- |
| 2 | +title: Extensions Overview |
| 3 | +description: Optional extensions to the Model Context Protocol |
| 4 | +--- |
| 5 | + |
| 6 | +# MCP Extensions |
| 7 | + |
| 8 | +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). |
| 9 | + |
| 10 | +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. |
| 11 | + |
| 12 | +<Tip> |
| 13 | + |
| 14 | +If you're building a third-party extension, use a reversed domain name you own as the vendor prefix to avoid collisions (similar to Java package naming). For example, a company owning `example.com` would use `com.example/` as their prefix (e.g., `com.example/my-extension`). |
| 15 | + |
| 16 | +</Tip> |
| 17 | + |
| 18 | +## Official Extension Repositories |
| 19 | + |
| 20 | +Official extensions live inside the [Model Context Protocol GitHub organization](https://github.com/modelcontextprotocol/) in repositories with the `ext-` prefix. |
| 21 | + |
| 22 | +### MCP Authorization Extensions |
| 23 | + |
| 24 | +<Card |
| 25 | + title="modelcontextprotocol/ext-auth" |
| 26 | + icon="github" |
| 27 | + href="https://github.com/modelcontextprotocol/ext-auth" |
| 28 | +> |
| 29 | + Extensions for supplementary authorization mechanisms beyond the core |
| 30 | + specification. |
| 31 | +</Card> |
| 32 | + |
| 33 | +| Extension | Description | |
| 34 | +| ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | |
| 35 | +| [OAuth Client Credentials](https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/oauth-client-credentials.mdx) | OAuth 2.0 client credentials flow for machine-to-machine authentication. | |
| 36 | +| [Enterprise-Managed Authorization](https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/enterprise-managed-authorization.mdx) | Framework for enterprise environments requiring centralized access control. | |
| 37 | + |
| 38 | +### MCP Apps |
| 39 | + |
| 40 | +<Card |
| 41 | + title="modelcontextprotocol/ext-apps" |
| 42 | + icon="github" |
| 43 | + href="https://github.com/modelcontextprotocol/ext-apps" |
| 44 | +> |
| 45 | + Extensions for interactive UI elements in conversational MCP clients. |
| 46 | +</Card> |
| 47 | + |
| 48 | +| Extension | Description | |
| 49 | +| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | |
| 50 | +| [MCP Apps](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx) | Allows MCP Servers to display interactive UI elements (charts, forms, video players) inline within conversations | |
| 51 | + |
| 52 | +To get started building MCP Apps, see the [quickstart guide](/docs/extensions/apps#getting-started) or read the full [MCP Apps documentation](https://modelcontextprotocol.github.io/ext-apps/api/documents/Quickstart.html). |
| 53 | + |
| 54 | +## Experimental Extensions |
| 55 | + |
| 56 | +Experimental extensions provide an incubation pathway for [Working Groups and Interest Groups](/community/working-interest-groups) to prototype ideas and collaborate on extension concepts before formal SEP submission. |
| 57 | + |
| 58 | +Experimental extension repositories live within the MCP GitHub organization with the `experimental-ext-` prefix (e.g., `experimental-ext-interceptors`). |
| 59 | + |
| 60 | +### Ground Rules |
| 61 | + |
| 62 | +- Every experimental extension needs to be associated with a Working Group or Interest Group |
| 63 | +- Repositories and published packages need to clearly indicate their experimental status (e.g., in the README and package name) |
| 64 | +- [Core Maintainers](/community/governance#core-maintainers) retain oversight of experimental extension repositories, including the ability to archive or remove them |
| 65 | + |
| 66 | +### Graduation to Official Status |
| 67 | + |
| 68 | +To promote an experimental extension to official status, it goes through the standard SEP process (Extensions Track). Feel free to reference the experimental repository and any reference implementations you built during incubation to demonstrate the extension's practicality. |
| 69 | + |
| 70 | +## Creating Extensions |
| 71 | + |
| 72 | +The lifecycle for official extensions follows a SEP-based process. For full details, see [SEP-2133: Extensions](/community/seps/2133-extensions). |
| 73 | + |
| 74 | +1. **Propose**: Create a SEP in the main MCP repository using the [standard SEP guidelines](/community/sep-guidelines) with type **Extensions Track**. |
| 75 | +2. **Implement**: Build at least one reference implementation in an official SDK — this is required before the SEP can be reviewed. |
| 76 | +3. **Review**: [Core Maintainers](/community/governance#core-maintainers) review the SEP and have final authority over inclusion. |
| 77 | +4. **Publish**: Once approved, open a PR to add the extension to the extension repository. |
| 78 | +5. **Adopt**: After that, other clients, servers, and SDKs can implement the extension too. |
| 79 | + |
| 80 | +### Requirements |
| 81 | + |
| 82 | +- Extension specifications need to use RFC 2119 language (MUST, SHOULD, MAY) |
| 83 | +- Extensions must have an associated working group or interest group |
| 84 | + |
| 85 | +### SDK Implementation |
| 86 | + |
| 87 | +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. |
| 88 | + |
| 89 | +<Note> |
| 90 | + |
| 91 | +Extensions are always disabled by default and require explicit opt-in from the developer. |
| 92 | + |
| 93 | +</Note> |
| 94 | + |
| 95 | +### Evolution |
| 96 | + |
| 97 | +Extensions evolve independently of the core protocol. Updates are managed by the extension repository maintainers and don't require core maintainer review. |
| 98 | + |
| 99 | +That said, backwards compatibility matters. When you need to change an extension, prefer using capability flags or versioning within the extension settings object rather than creating a new extension identifier. If a breaking change is unavoidable, use a new identifier (e.g., `io.modelcontextprotocol/my-extension-v2`). |
| 100 | + |
| 101 | +A **breaking change** is any modification that would cause existing implementations to fail or behave incorrectly, including: |
| 102 | + |
| 103 | +- Removing or renaming fields |
| 104 | +- Changing field types |
| 105 | +- Altering the semantics of existing behavior |
| 106 | +- Adding new required fields |
| 107 | + |
| 108 | +## Negotiation |
| 109 | + |
| 110 | +Clients and servers advertise their support for extensions in the `extensions` field within their respective capabilities during the [initialization handshake](/specification/latest/basic/lifecycle). |
| 111 | + |
| 112 | +### Client Capabilities |
| 113 | + |
| 114 | +Clients advertise extension support in the `initialize` request: |
| 115 | + |
| 116 | +```json |
| 117 | +{ |
| 118 | + "jsonrpc": "2.0", |
| 119 | + "id": 1, |
| 120 | + "method": "initialize", |
| 121 | + "params": { |
| 122 | + "protocolVersion": "2025-06-18", |
| 123 | + "capabilities": { |
| 124 | + "roots": { |
| 125 | + "listChanged": true |
| 126 | + }, |
| 127 | + "extensions": { |
| 128 | + "io.modelcontextprotocol/ui": { |
| 129 | + "mimeTypes": ["text/html;profile=mcp-app"] |
| 130 | + } |
| 131 | + } |
| 132 | + }, |
| 133 | + "clientInfo": { |
| 134 | + "name": "ExampleClient", |
| 135 | + "version": "1.0.0" |
| 136 | + } |
| 137 | + } |
| 138 | +} |
| 139 | +``` |
| 140 | + |
| 141 | +### Server Capabilities |
| 142 | + |
| 143 | +Servers advertise extension support in the `initialize` response: |
| 144 | + |
| 145 | +```json |
| 146 | +{ |
| 147 | + "jsonrpc": "2.0", |
| 148 | + "id": 1, |
| 149 | + "result": { |
| 150 | + "protocolVersion": "2025-06-18", |
| 151 | + "capabilities": { |
| 152 | + "tools": {}, |
| 153 | + "extensions": { |
| 154 | + "io.modelcontextprotocol/ui": {} |
| 155 | + } |
| 156 | + }, |
| 157 | + "serverInfo": { |
| 158 | + "name": "ExampleServer", |
| 159 | + "version": "1.0.0" |
| 160 | + } |
| 161 | + } |
| 162 | +} |
| 163 | +``` |
| 164 | + |
| 165 | +Each extension specifies the schema of its settings object; an empty object indicates no settings. |
| 166 | + |
| 167 | +### Graceful Degradation |
| 168 | + |
| 169 | +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. |
| 170 | + |
| 171 | +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. |
0 commit comments