docs: reflect the stateless protocol, server/discover, and session removal#3069
Draft
claude[bot] wants to merge 7 commits into
Draft
docs: reflect the stateless protocol, server/discover, and session removal#3069claude[bot] wants to merge 7 commits into
claude[bot] wants to merge 7 commits into
Conversation
…scover Replace the initialize-based lifecycle walkthrough in the architecture guide with per-request _meta identity, server/discover, and subscriptions/listen, and update the JSON examples to the 2026-07-28 draft shapes (resultType, ttlMs, cacheScope). Rewrite the versioning page's Negotiation section around per-request version declaration and retarget its lifecycle link, which would break once the draft ships. Update the dynamic server management diagram in client best practices to open with server/discover instead of an initialize handshake. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru
Drop the Mcp-Session-Id inspection advice in favor of the request metadata headers, point the logging guidance at the per-request io.modelcontextprotocol/logLevel field, and retarget the connection-problems checklist to server/discover, the per-request _meta fields, and the new versioning page. Retarget spec links whose lifecycle anchors are gone from the draft. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru
Protocol revision 2026-07-28 removes protocol-level sessions and the Mcp-Session-Id header, so scope the session hijacking attacks to protocol versions 2025-11-25 and earlier and add guidance for securing the explicit state handles that replace sessions. Pin the resumability link to the 2025-11-25 spec where the anchor still exists. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru
Extensions are declared in the extensions field of the per-request clientCapabilities carried in _meta and in the server capabilities returned by server/discover, so replace the initialize-time phrasing in the client matrix and the auth and tasks overviews. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru
- Note that tools/list also accepts an optional cursor for pagination - Add the Logging deprecation warning to the debugging guide - Show the mandatory subscriptions/listen acknowledgment in the architecture walkthrough - Retitle the new session hijacking subsections to Title Case to match the file's heading convention Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru
cacheScope controls who may cache a response, while ttlMs controls how long the result stays fresh. The previous wording attributed reuse duration to both fields. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016WBaED7Rta4YsYVz66Qoru
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhtN33k4CMKjzsQL2jd6Z9
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Requested by Den Delimarsky · Slack thread
The architecture, versioning, debugging, security, and extensions pages still walked readers through an
initializehandshake and protocol-level sessions withMcp-Session-Idheaders. A reader now sees the stateless per-request model, with the protocol version and capabilities carried in_metaon each request. Discovery happens throughserver/discover, and notifications are opted into withsubscriptions/listen.Motivation and Context
Part of preparing the documentation for the 2026-07-28 release. The draft specification removed the
initializehandshake and protocol-level sessions, but these guides still taught both. The mandatoryserver/discoverrequest was not documented outside the spec, and the extensions pages still described capability negotiation as happening during initialization.Closes #3031
Closes #3039
Closes #3040
Closes #3043
The authorization tutorial portion of #3031 (the session-keyed example server) lands in the separate authorization tutorial PR from this effort.
How Has This Been Tested?
Documentation-only change.
prettier --checkpasses on the edited files andscripts/check-mdx-comments.tspasses (281 files OK).mint broken-linksreports no broken links.Breaking Changes
None.
Types of changes
Checklist
Additional context
This bundle edits the architecture and debugging pages, which other rc-high-priority bundle PRs also touch, so merge order may need care. The debugging page's logging sections (the SEP-2577 deprecation warning and the
logging/setLevelreplacement) were left to PR #3067, so this PR no longer overlaps #3067 on that file.AI assistance disclosure: this PR, including the documentation changes and this description, was written primarily by an AI coding assistant. A human reviews the full diff before merge.
Generated by Claude Code