Merge pull request modelcontextprotocol#2791 from modelcontextprotocol/draft-spec-language-updates

docs(spec): incorporate SEP-2596 and SEP-1865 into the draft spec; clarify Streamable HTTP

Author: dsp-ant

docs/community/feature-lifecycle.mdx

@@ -0,0 +1,135 @@
+---
+title: Feature Lifecycle and Deprecation Policy
+description: How individual MCP specification features move through Active, Deprecated, and Removed states, and the timeline implementers can plan against.
+---
+
+This policy defines a lifecycle for individual features within the Model
+Context Protocol specification. It defines three feature states (Active,
+Deprecated, Removed), the criteria and procedure for moving between them, a
+minimum window between deprecation and removal, and the documentation required
+at each transition.
+
+This policy was adopted via
+[SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596).
+
+## Scope
+
+This policy governs **features** of the MCP core specification: protocol
+messages, capabilities, transports, schema types, and normative behavioral
+requirements. Tthe revision lifecycle of the specification document itself
+(Draft, Current, Final), is defined in the [versioning guide](/docs/learn/versioning).
+
+## Feature States
+
+A specification feature is in exactly one of three states:
+
+| State          | Meaning                                                                                                                                                       | Implementer expectation                                                                                                     |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| **Active**     | The feature is part of the Current specification revision.                                                                                                    | Implement per the feature's normative requirements.                                                                         |
+| **Deprecated** | The feature remains in the specification but is scheduled for removal. A migration path is documented (see below).                                            | New implementations should not adopt the feature. Existing implementations should migrate before the earliest removal date. |
+| **Removed**    | The feature has been deleted from `draft` and will be absent from the next Current revision. It remains documented in the Final revision it last appeared in. | Implementations targeting that next Current revision must not depend on the feature.                                        |
+
+A Deprecated feature MAY be restored to Active by a SEP that supersedes the
+deprecation SEP and documents the changed circumstances. Restoration follows
+the same approval path as deprecation. If the feature is later deprecated
+again, the minimum deprecation window in
+[Deprecating a feature](#deprecating-a-feature) is measured afresh from the
+revision in which the new deprecation takes effect.
+
+### SDKs
+
+Removal from the specification does not oblige an SDK to drop the feature from
+releases. That timeline is governed by the SDK's own revision-support policy.
+
+## Deprecating a Feature
+
+A feature may be proposed for deprecation due to
+
+- it has been superseded by another feature that covers the same use cases,
+- it presents a security, privacy, or interoperability risk that cannot be
+  mitigated in place,
+- ecosystem telemetry or SDK maintainer consensus indicates negligible adoption
+  relative to its maintenance cost,
+- or any other reasons the Core Maintainers seem to deem appropriate.
+
+Deprecation is a specification change and therefore requires a SEP per the
+[SEP guidelines](/community/sep-guidelines). The deprecation SEP must:
+
+1. Identify the feature by name and link to its definition in `schema.ts`
+   (where applicable) and the specification prose.
+2. State the rationale against the criteria above.
+3. Document the migration path, or state explicitly that none is required. If
+   the migration path names a replacement feature, that feature must be Active
+   in the revision in which the deprecation takes effect; the replacement and
+   the deprecation may land in the same revision.
+4. Specify the **minimum deprecation window**: the number of months, at least
+   twelve, that the feature must remain Deprecated before it is eligible for
+   removal. The window is measured from the release of the specification
+   revision in which the feature is first marked Deprecated, not from the date
+   the SEP reaches Final. The feature becomes eligible for removal in the first
+   specification revision released as Current on or after the window elapses;
+   that point is the feature's **earliest removal**.
+
+When the deprecation SEP is accepted and reaches Final, the deprecation is scheduled.
+
+- The feature's entry in `schema.ts` gains a `@deprecated` JSDoc tag
+  referencing the deprecation SEP and the revision in which the deprecation
+  takes effect.
+- The specification prose for the feature gains a deprecation notice with the
+  same information.
+- The `changelog.mdx` for that revision gains an entry under a "Deprecated"
+  heading. "Deprecated" and "Removed" are standing changelog headings alongside
+  the existing Major/Minor/Other groupings.
+- The feature is added to the
+  [deprecated registry](#the-deprecated-registry) with its deprecation SEP, the
+  revision in which it became Deprecated, its migration path, and its earliest
+  removal.
+
+The feature becomes Deprecated when the revision carrying these changes is released
+and becomes the new Current revision (see [versioning guide](/docs/learn/versioning)).
+The minimum deprecation window is counted from that release.
+
+## The Deprecated Registry
+
+[`docs/specification/draft/deprecated.mdx`](/specification/draft/deprecated) is
+a single page listing every feature Deprecated or Removed state. It is
+the canonical answer to "what is on its way out, and by when," so that an
+implementer does not have to reconstruct that picture from deprecation entries
+spread across revision changelogs.
+
+## Tier 1 SDK Obligations
+
+Once the revision in which a feature becomes Deprecated is
+released as Current, Tier 1 SDKs:
+
+- Must mark the corresponding API surface deprecated using the language's
+  native mechanism (for example `@Deprecated` in Java, `[Obsolete]` in .NET,
+  `@deprecated` JSDoc in TypeScript, the `Deprecated:` doc convention in Go) in
+  their next release, referencing the deprecation SEP and the earliest removal
+  date where the mechanism permits.
+- Should emit a runtime warning when a deprecated feature is exercised, using
+  the language's idiomatic mechanism (for example Python's
+  `DeprecationWarning`, Node.js's `process.emitWarning`, or a configurable
+  logger).
+
+## Removing a Feature
+
+1. Once a feature is set for removal, the removal is executed at the discretion
+   of the Core Maintainers after the minimum deprecation window has elapsed.
+2. The removal needs to be documented in the `changelog.mdx` and [registry](#the-deprecated-regsitry)
+3. A SEP is required for any change to the original deprecation or removal SEP, for
+   example extending or shortening the timeline
+   ([Expedited removal](#expedited-removal)) or restoring the feature to Active
+   ([Feature states](#feature-states)).
+
+## Expedited Removal
+
+The twelve-month floor may be shortened when the feature presents an active
+security risk, meaning a vulnerability with a published security advisory or
+documented in-the-wild exploitation for which no in-place mitigation exists.
+Shortening the window requires Core Maintainer approval under the
+[governance decision process](/community/governance#decision-process), recorded
+in the deprecation SEP or, where the risk surfaces after that SEP is already
+Final, in a short expedited-removal SEP that references it. The shortened
+window must still provide at least ninety days between the feature becoming
+Deprecated and its earliest removal.

docs/docs.json

@@ -316,6 +316,7 @@
             "pages": [
               "specification/draft/index",
               "specification/draft/changelog",
+              "specification/draft/deprecated",
               "specification/draft/architecture/index",
               {
                 "group": "Base Protocol",
@@ -484,6 +485,7 @@
             "pages": [
               "community/governance",
               "community/contributor-ladder",
+              "community/feature-lifecycle",
               "community/sdk-tiers",
               "community/antitrust"
             ]

docs/docs/learn/versioning.mdx

@@ -26,6 +26,22 @@ Revisions may be marked as:
 
 The **current** protocol version is [**2025-11-25**](/specification/2025-11-25/).
 
+## Feature States
+
+Individual features of the specification may additionally be marked as
+**Deprecated** under the
+[feature lifecycle and deprecation policy](/community/feature-lifecycle):
+the feature remains part of the specification, but is scheduled for removal.
+Deprecated features document a migration path (or state that none is required)
+and remain in the specification for at least twelve months, or at least
+ninety days under the policy's
+[expedited-removal exception](/community/feature-lifecycle#expedited-removal)
+, before they become eligible for removal, after which they may be **Removed**
+in a future revision.
+
+Features that are currently Deprecated are listed in the
+[deprecated features registry](/specification/draft/deprecated).
+
 ## Negotiation
 
 Version negotiation happens during

docs/specification/draft/basic/index.mdx

@@ -232,12 +232,12 @@ in `_meta`. Servers use these to identify the client and the protocol version in
 without relying on any prior connection state. See
 [Lifecycle][lifecycle] for version negotiation rules.
 
-| Key                                          | Type                 | Required | Description                                                 |
-| -------------------------------------------- | -------------------- | -------- | ----------------------------------------------------------- |
-| `io.modelcontextprotocol/protocolVersion`    | `string`             | Yes      | Protocol version for this request (e.g., `"DRAFT-2026-v1"`) |
-| `io.modelcontextprotocol/clientInfo`         | `Implementation`     | Yes      | Client name and version                                     |
-| `io.modelcontextprotocol/clientCapabilities` | `ClientCapabilities` | Yes      | Client capabilities relevant to this request                |
-| `io.modelcontextprotocol/logLevel`           | `LoggingLevel`       | No       | Minimum log level the server should emit for this request   |
+| Key                                          | Type                 | Required | Description                                               |
+| -------------------------------------------- | -------------------- | -------- | --------------------------------------------------------- |
+| `io.modelcontextprotocol/protocolVersion`    | `string`             | Yes      | Protocol version for this request (e.g., `"2026-07-28"`)  |
+| `io.modelcontextprotocol/clientInfo`         | `Implementation`     | Yes      | Client name and version                                   |
+| `io.modelcontextprotocol/clientCapabilities` | `ClientCapabilities` | Yes      | Client capabilities relevant to this request              |
+| `io.modelcontextprotocol/logLevel`           | `LoggingLevel`       | No       | Minimum log level the server should emit for this request |
 
 A server **MUST NOT** rely on capabilities the client has not declared. If
 processing a request requires a capability the client did not include in

docs/specification/draft/basic/lifecycle.mdx

@@ -71,7 +71,7 @@ listing the versions it does support:
     "code": -32004,
     "message": "Unsupported protocol version",
     "data": {
-      "supported": ["DRAFT-2026-v1", "2025-11-25"],
+      "supported": ["2026-07-28", "2025-11-25"],
       "requested": "1900-01-01"
     }
   }
@@ -130,29 +130,30 @@ Clients and servers can negotiate support for optional
 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:
+The following is an example of a client that advertises the
+[MCP Apps extension](/extensions/apps/overview) identified as `io.modelcontextprotocol/ui`:
 
 ```json
 {
   "capabilities": {
     "roots": {},
     "extensions": {
-      "io.modelcontextprotocol/apps": {
+      "io.modelcontextprotocol/ui": {
         "mimeTypes": ["text/html;profile=mcp-app"]
       }
     }
   }
 }
 ```
 
-Example server capabilities with extensions:
+An example of [Tasks extension](/extensions/tasks/overview) identified as `io.modelcontextprotocol/tasks`:
 
 ```json
 {
   "capabilities": {
     "tools": {},
     "extensions": {
-      "io.modelcontextprotocol/apps": {}
+      "io.modelcontextprotocol/tasks": {}
     }
   }
 }