Skip to content

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

Merged
dsp-ant merged 10 commits into
mainfrom
draft-spec-language-updates
May 27, 2026
Merged

docs(spec): incorporate SEP-2596 and SEP-1865 into the draft spec; clarify Streamable HTTP#2791
dsp-ant merged 10 commits into
mainfrom
draft-spec-language-updates

Conversation

@dsp-ant

@dsp-ant dsp-ant commented May 26, 2026

Copy link
Copy Markdown
Member

Summary

Aligns the draft (2026-07-28 RC) specification language with SEP-2596 (feature lifecycle and deprecation policy), SEP-2577 (Roots/Sampling/Logging deprecation), and SEP-1865 (MCP Apps), and improves the readability and historical context of the Streamable HTTP transport page.

SEP-2596: feature lifecycle and deprecation policy

  • Add the standalone policy doc at docs/community/feature-lifecycle.mdx (under Community → Governance), extracted from SEP-2596's Specification section
  • Add the deprecated features registry at docs/specification/draft/deprecated.mdx, listing Roots/Sampling/Logging (SEP-2577) plus the grandfathered HTTP+SSE transport and includeContext values
  • Add a standing Deprecated changelog section and a governance entry for the policy itself
  • Rewrite the Roots/Sampling/Logging deprecation notices to reference SEP-2577, the policy's twelve-month window, and migration paths; use the concrete 2026-07-28 revision in prose
  • Retire the "soft-deprecated" wording and mark includeContext "thisServer"/"allServers" as @deprecated in schema.ts (revision 2025-11-25 per the registry)
  • Add a deprecation notice for the HTTP+SSE transport on the transports page
  • Reference feature states from the versioning guide, with the expedited-removal caveat
  • All policy links target /community/feature-lifecycle rather than the rendered SEP

SEP-2577: schema annotations

  • Add @deprecated JSDoc tags to all 19 still-present items SEP-2577 §Schema changes lists (ClientCapabilities.roots/.sampling, ServerCapabilities.logging, Root, ListRootsRequest/Result, CreateMessageRequest/Params/Result, SamplingMessage/ContentBlock, ToolChoice, ToolUseContent, ToolResultContent, ModelPreferences, ModelHint, LoggingLevel, LoggingMessageNotification/Params), plus the _meta key io.modelcontextprotocol/logLevel that replaced the SEP-listed SetLevelRequest* types
  • typedoc.plugin.mjs: strip non-unique @deprecated block ids in the generated schema reference (extends the existing @see workaround)

SEP-1865: MCP Apps

  • Name and link the MCP Apps extension in the Extension Negotiation section of the lifecycle page (client example only — io.modelcontextprotocol/ui is a client-advertised capability per ext-apps)
  • Use the Tasks extension (io.modelcontextprotocol/tasks, SEP-2663) for the ServerCapabilities.extensions example, since that one is server-advertised

Streamable HTTP clarity

  • Add an at-a-glance overview at the top of the Streamable HTTP section and a new Message Flow section with sequence diagrams for request/response, MRTR, and subscriptions/listen
  • Note how this revision differs from Streamable HTTP in protocol versions 2025-03-26 through 2025-11-25, with backward compatibility guidance for those revisions

Schema artifacts (schema.json, schema.mdx) are regenerated via npm run generate:schema; npm run check is clean.

dsp-ant added 3 commits May 26, 2026 20:38
…aft spec

- Add the deprecated features registry (deprecated.mdx) and link it from the
  docs navigation
- Add a Deprecated changelog section covering SEP-2577 and the features
  grandfathered by SEP-2596, plus a governance entry for the policy itself
- Rewrite the Roots, Sampling, and Logging deprecation notices to reference
  SEP-2577, the policy's twelve-month window, and migration paths
- Retire the "soft-deprecated" wording for includeContext values in the
  sampling docs
- Document feature states in the versioning guide
- Mark CreateMessageRequestParams.includeContext values "thisServer" and
  "allServers" as deprecated per SEP-2596 and retire the "soft-deprecated"
  wording
- Name and link the MCP Apps extension (SEP-1865) in extension negotiation
  and correct its identifier to io.modelcontextprotocol/ui
- Regenerate schema.json and the schema reference doc
…rams

- Add an at-a-glance overview and a Message Flow section with sequence
  diagrams for request/response, MRTR, and subscriptions/listen
- Note how this revision differs from Streamable HTTP in protocol versions
  2025-03-26 through 2025-11-25 and add backward compatibility guidance for
  those revisions
- Add a deprecation notice for the HTTP+SSE transport per the feature
  lifecycle policy
@dsp-ant
dsp-ant requested review from a team as code owners May 26, 2026 19:51
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label May 26, 2026
@mintlify

mintlify Bot commented May 26, 2026

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
mcp-staging 🟢 Ready View Preview May 26, 2026, 7:59 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@mintlify

mintlify Bot commented May 26, 2026

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
mcp 🟢 Ready View Preview May 26, 2026, 8:04 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@vaaraio

vaaraio commented May 26, 2026

Copy link
Copy Markdown

Nice consolidation. The message-flow diagrams in particular land well.

One angle worth surfacing on SEP-2596: the deprecation policy intersects with audit-chain compliance for runtime governance layers. Under EU AI Act Article 12, high-risk AI systems must reconstruct operation from logs, which means audit-time reconstruction (sometimes +6 months per Article 26(6)) needs to know which features were deprecated AT CALL TIME, not just the current state.

Concrete suggestion: expose the deprecated registry as machine-readable metadata (effective date, scheduled removal date, replacement reference) at a well-known path so runtime governance layers can fetch and hash into per-call audit receipts. Doesn't require changes to the deprecation policy itself, just an additional surface alongside the human-readable mdx page.

Comment thread docs/docs/learn/versioning.mdx Outdated
Comment thread docs/specification/draft/client/sampling.mdx Outdated
Comment thread docs/specification/draft/client/sampling.mdx Outdated
Comment thread docs/specification/draft/client/sampling.mdx Outdated
Comment thread docs/specification/draft/server/utilities/logging.mdx Outdated
Comment thread docs/specification/draft/server/utilities/logging.mdx Outdated
Comment thread docs/specification/draft/changelog.mdx
Comment thread docs/specification/draft/deprecated.mdx Outdated
…n deprecation notices

- Extract SEP-2596 policy into docs/community/feature-lifecycle.mdx and add
  to Governance nav group
- Retarget all /seps/2596-* policy links to /community/feature-lifecycle
  (versioning guide, roots/sampling/logging warnings, transports HTTP+SSE
  notice, deprecated registry, changelog)
- Replace DRAFT-2026-v1 with 2026-07-28 in deprecation prose (warning
  blocks and registry table); registry earliest-removal now reads
  'first revision released on or after 2027-07-28'
- Changelog governance entry links both the new doc and the SEP PR
- includeContext note links the policy #transition anchor

Wire-level DRAFT-2026-v1 strings (schema.ts, examples, header samples)
left for the draft->2026-07-28 directory cut.

:house: Remote-Dev: homespace
SEP-2577 schema annotations:
- Add @deprecated JSDoc tags to all Roots/Sampling/Logging schema items
  SEP-2577 lists (ClientCapabilities.roots/.sampling, ServerCapabilities.logging,
  Root, ListRootsRequest/Result, CreateMessageRequest/Params/Result,
  SamplingMessage/ContentBlock, ToolChoice, ToolUseContent, ToolResultContent,
  ModelPreferences, ModelHint, LoggingLevel, LoggingMessageNotification/Params).
  Types removed by SEP-2575/2322 (RootsListChangedNotification, SetLevel*,
  *ResultResponse) are not present and so not annotated.
- Align includeContext @deprecated revision with the registry (2025-11-25,
  not DRAFT-2026-v1).

SEP-1865 server-capability example:
- ext-apps defines io.modelcontextprotocol/ui as a client-only capability.
  Scope the SEP-1865 attribution in lifecycle.mdx to the client example and
  use io.modelcontextprotocol/tasks (SEP-2663) for the ServerCapabilities
  example. Rename and update the corresponding schema example file.

Policy-doc corrections:
- feature-lifecycle.mdx: fix /community/sdk-tiers anchor (#tier-relegation,
  not #tier-relegation-process); scope the 'well over twelve months'
  Transition rationale to HTTP+SSE only (includeContext was 2025-11-25).
- versioning.mdx: qualify the twelve-month floor with the expedited-removal
  exception so the summary doesn't overstate the policy guarantee.

Regenerated schema.json and schema.mdx.

:house: Remote-Dev: homespace
…e anchor ids

- Tag RequestMetaObject."io.modelcontextprotocol/logLevel" as @deprecated
  (SEP-2577). It is the SEP-2575 successor to the SetLevelRequest* types
  SEP-2577 lists; its value type (LoggingLevel) and the notification it
  gates (LoggingMessageNotification) were already tagged in 906af9d.
- typedoc.plugin.mjs: strip non-unique @deprecated block ids alongside the
  existing @see workaround. The 19 SEP-2577 tags otherwise produce 18
  colliding id="deprecated" anchors in the generated schema reference.
- Regenerated schema.mdx.

:house: Remote-Dev: homespace
…not just ids

The previous one-liner stripped the colliding ids but left dangling
href="#deprecated" / href="#see" permalink icons pointing at nothing.
These tag-block sub-headings aren't useful link targets (you'd link to the
type's own anchor), so drop both the id and the anchor icon.

Also clears 7 pre-existing dangling href="#see" permalinks in
draft/schema.mdx that the original @see workaround left behind.

:house: Remote-Dev: homespace
Replace the DRAFT-2026-v1 placeholder with the locked RC date across
schema/draft/ and docs/specification/draft/. The DRAFT-YYYY-vN convention
is undocumented and previously caused 2025-11-25 to ship with
LATEST_PROTOCOL_VERSION = "DRAFT-2025-v3" (corrected a week later in
35fa160). With the RC date fixed, pinning now avoids repeating that
and brings the constant in line with the @deprecated tag wording this
PR already uses.

- schema/draft/schema.ts: LATEST_PROTOCOL_VERSION = "2026-07-28"
- 19 example JSON files (_meta.protocolVersion, supported[] arrays)
- 5 spec mdx files (HTTP header samples, JSON snippets)
- schema.mdx regenerated

:house: Remote-Dev: homespace
@localden

Copy link
Copy Markdown
Contributor

Protocol version pinned to 2026-07-28 (commit a11b155)

@dsp-ant — this PR replaces the DRAFT-2026-v1 placeholder with 2026-07-28 across schema/draft/ and docs/specification/draft/. We're using the real version to simplify the future merge, since we already know what the version is expected to be (RC locked May 21). It also avoids repeating the 2025-11-25 cut where the released schema shipped with LATEST_PROTOCOL_VERSION = "DRAFT-2025-v3" for a week (35fa160).

If you'd rather keep a draft-placeholder convention, here are all the locations to flip back:

Schema source

  • schema/draft/schema.ts:37LATEST_PROTOCOL_VERSION

Example JSON (_meta."io.modelcontextprotocol/protocolVersion", supportedVersions[], supported[])

  • schema/draft/examples/CallToolRequest/call-tool-request.json
  • schema/draft/examples/CallToolRequestParams/get-weather-tool-call-params.json
  • schema/draft/examples/CallToolRequestParams/tool-call-params-with-progress-token.json
  • schema/draft/examples/CompleteRequest/completion-request.json
  • schema/draft/examples/CompleteRequestParams/prompt-argument-completion.json
  • schema/draft/examples/CompleteRequestParams/prompt-argument-completion-with-context.json
  • schema/draft/examples/DiscoverRequest/server-discover-request.json
  • schema/draft/examples/DiscoverResult/server-capabilities-discovery.json
  • schema/draft/examples/DiscoverResultResponse/discover-result-response.json
  • schema/draft/examples/GetPromptRequest/get-prompt-request.json
  • schema/draft/examples/GetPromptRequestParams/get-code-review-prompt.json
  • schema/draft/examples/ListPromptsRequest/list-prompts-request.json
  • schema/draft/examples/ListResourceTemplatesRequest/list-resource-templates-request.json
  • schema/draft/examples/ListResourcesRequest/list-resources-request.json
  • schema/draft/examples/ListToolsRequest/list-tools-request.json
  • schema/draft/examples/PaginatedRequestParams/list-with-cursor.json
  • schema/draft/examples/ReadResourceRequest/read-resource-request.json
  • schema/draft/examples/SubscriptionsListenRequest/listen-for-list-changes.json
  • schema/draft/examples/UnsupportedProtocolVersionError/unsupported-version.json

Spec prose (MCP-Protocol-Version: headers and inline JSON)

  • docs/specification/draft/basic/index.mdx
  • docs/specification/draft/basic/lifecycle.mdx
  • docs/specification/draft/basic/transports.mdx
  • docs/specification/draft/basic/utilities/subscriptions.mdx
  • docs/specification/draft/server/discover.mdx

Generated (follows schema.ts + examples)

  • docs/specification/draft/schema.mdx

The 20 @deprecated JSDoc tags this PR adds also say as of protocol version 2026-07-28 — so if a placeholder is preferred those should match it.

localden
localden previously approved these changes May 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants