Preamble

Title: MCP Extension Specification and Directory Structure
Authors: Darin McAdams
Status: draft
Type: Standards Track
Created: 2025-09-19

Abstract

This SEP introduces the concept of official MCP-governed extensions—extensions defined and maintained through the MCP governance process - and proposes a directory structure for organizing extension specifications within the Model Context Protocol (MCP) specification repository. This is the first step in establishing a framework for optional MCP extensions - it defines what extensions are and addresses where MCP-governed extension specification documents should be located and how they should be structured within the repository. It stays clear of discovery and other complexities, which may be addressed in future SEPs.

Scope Note: This document covers only MCP-governed extensions. Extensions developed by other communities are outside the scope of this SEP.

Motivation

As the MCP ecosystem grows, certain use-cases require additional optional capabilities beyond the core protocol. These use-cases benefit from a structured way to define standardized behavior for their specialized requirements, while making it clear that implementations only need to support these extensions if they want the specific functionality.

Currently, there is no designated location within the MCP specification repository for extension specifications, nor guidance on how such specifications should be organized. This SEP addresses the immediate need for:

1. A designated location for MCP-governed extension specification documents within the repository
2. Basic organizational structure for extension documentation
3. Clear boundaries between core protocol requirements and optional extensions in documentation

This is an initial organizational step that enables future work on extension discovery, negotiation, and other mechanisms without predetermining how those systems will work.

Specification

Extension Definition

Extensions are optional capabilities that define additional functionality beyond the baseline MCP requirements to support specific use cases.

Extension Requirements:

1. Independence: Extension MUST provide complete documentation that can be implemented independently without dependencies on other extensions.
2. Composability: Extensions MUST be modular such that multiple extensions can be composed together within a single implementation without conflicts.

Conformance Model: Implementations MAY choose to adopt one or more extensions based on their specific requirements. Once an extension is adopted, implementations MUST conform to all requirements specified in that extension.

Directory Structure

A new extensions/ directory shall be created at the root level of the specification repository to contain MCP-governed extension specifications.

specification/
├── basic/                       # Core MCP specification
├── client/                       # Core MCP specification
├── server/                      # Core MCP specification
├── extensions/                 # Extension specifications (NEW)
│   ├── index.md               # Overview and index of extensions
│   ├── core/                  # Core extension framework specs (FUTURE)
│   │   ├── discovery.md       # Extension discovery protocol (FUTURE)
│   │   ├── negotiation.md     # Extension negotiation protocol (FUTURE)
│   │   └── metadata.md        # Extension metadata format (FUTURE)
│   ├── specifications/        # Individual extension specifications
│   │   ├── extension-name-1/
│   │   └── extension-name-2/
└── ...

Note: The core/ subdirectory is shown for future planning but is NOT included in this SEP. This SEP focuses only on establishing the extensions/ directory and specifications/ subdirectory structure.

Governance Scope

Extensions documented in the extensions/ directory are managed by the MCP governance process and MCP working groups. However, the broader concept of MCP extensions can be adopted by any community. The design, maintenance, and interoperability of external extensions are the responsibility of their respective communities.

What This SEP Does NOT Address

This SEP intentionally does NOT define:

• Extension metadata formats
• Automated discovery or compatibility negotiation
• A universal registry of all extensions, both MCP-governed and community managed
• Criteria for which extensions should be stewarded within the MCP specification repository versus developed independently by the broader community

The first three aspects may be addressed in future SEPs as the ecosystem and requirements mature. Extension stewardship decisions will be made through established MCP governance processes, considering factors such as broad applicability, interoperability benefits, and working group capacity.

Rationale

Design Decisions

Single Extensions Directory: A unified location makes it easy for specification readers to find optional capabilities without fragmenting the documentation.

Self-Contained Specifications: Each extension should be implementable based solely on its own documentation, ensuring clarity and reducing interdependencies.

Governance Integration: Extensions in the official directory benefit from MCP's established review processes while allowing the broader community to develop extensions elsewhere.

Documentation-First Approach: By focusing on specification organization first, we avoid premature decisions about runtime behavior and discovery mechanisms.

Alternative Approaches Considered

Separate Repository: Extension specifications could live in a separate repository, but this would fragment the specification ecosystem and make cross-referencing more difficult.

Inline with Core Specification: Extensions could be documented within the core specification, but this would blur the boundary between required and optional functionality.

Release and Versioning

Extensions in the official directory shall follow the same release cadence as the main MCP specification. While extensions could theoretically have independent release cycles, this approach keeps the specification maintenance process simple and ensures that official extensions remain synchronized with core protocol evolution.

Backwards Compatibility

This proposal is fully backwards compatible. It adds documentation structure without modifying existing protocol specifications or runtime behavior.

Reference Implementation

PR-1047 implements this directory structure alongside an initial specification for the OAuth Client Credentials flow. For reference, OAuth Client Credentials was previously approved in SEP-1046, but feedback on the implementation encouraged shifting this into an inaugural use of extensions.

Therefore, the PR now includes:

1. Extension Directory Creation: Adding the extensions/ directory structure with specifications/ subdirectory
2. Extension Documentation: Creating extensions/index.md with appropriate guidance
3. Initial Extension: The implementation of OAuth Client Credentials to demonstrate the extension format.

Security Considerations

This organizational change introduces no security considerations. Individual extension specifications will address security implications specific to their functionality.