docs: reflect the stateless protocol, server/discover, and session removal by claude[bot] · Pull Request #3069 · modelcontextprotocol/modelcontextprotocol

claude · 2026-07-10T08:29:14Z

Requested by Den Delimarsky · Slack thread

The architecture, versioning, debugging, security, and extensions pages still walked readers through an initialize handshake and protocol-level sessions with Mcp-Session-Id headers. A reader now sees the stateless per-request model, with the protocol version and capabilities carried in _meta on each request. Discovery happens through server/discover, and notifications are opted into with subscriptions/listen.

Motivation and Context

Part of preparing the documentation for the 2026-07-28 release. The draft specification removed the initialize handshake and protocol-level sessions, but these guides still taught both. The mandatory server/discover request 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 --check passes on the edited files and scripts/check-mdx-comments.ts passes (281 files OK). mint broken-links reports no broken links.

Breaking Changes

None.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

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/setLevel replacement) 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

…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

localden

Second pass for spec alignment and prose cleanup. Just leftover em dashes in the changed prose, suggestions inline.

localden

Third pass, one item. The acknowledgment ordering paragraph overstates the guarantee, and #3068 rewrites this exact paragraph too, so the two need to land on the same wording or they'll conflict at merge.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhtN33k4CMKjzsQL2jd6Z9

pja-ant · 2026-07-22T16:14:26Z

 for session in app.mcp_server_sessions():
    tools_response = await session.list_tools()
    available_tools.extend(tools_response.tools)


Suggested change

for client in app.mcp_clients():

tools_response = await cient.list_tools()

available_tools.extend(tools_response.tools)

pja-ant · 2026-07-22T16:15:11Z

    async with ClientSession(read, write) as session:
-        init_response = await session.initialize()
-        if init_response.capabilities.tools:
+        discover_response = await session.discover()
+        if discover_response.capabilities.tools:
            app.register_mcp_server(session, supports_tools=True)
        app.set_server_ready(session)


Since there are no more sessions, using a hypothetical client SDK API with sessions is giving the wrong impression. I'd just replace ClientSession with Client and session with client.

(for some reason github won't let me suggest code edit here)

pja-ant · 2026-07-22T16:16:08Z

 for session in app.mcp_server_sessions():
    tools_response = await session.list_tools()
    available_tools.extend(tools_response.tools)
 conversation.register_available_tools(available_tools)


could maybe link to our guidance around using things like tool search: https://modelcontextprotocol.io/docs/develop/clients/client-best-practices#progressive-tool-discovery

claude added 6 commits July 10, 2026 07:37

github-actions Bot added the documentation Improvements or additions to documentation label Jul 10, 2026

docs: leave debugging logging sections to the client concepts PR

fb10578

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhtN33k4CMKjzsQL2jd6Z9

localden marked this pull request as ready for review July 14, 2026 06:39

localden requested review from a team as code owners July 14, 2026 06:39

localden added the rc-high-priority Related to an upcoming specification release and needs to be addressed with a high priority. label Jul 14, 2026

localden self-assigned this Jul 14, 2026

localden reviewed Jul 18, 2026

View reviewed changes

Comment thread docs/docs/draft/learn/architecture.mdx Outdated

Comment thread docs/docs/draft/learn/architecture.mdx Outdated

Comment thread docs/docs/draft/learn/architecture.mdx Outdated

Comment thread docs/docs/draft/tools/debugging.mdx Outdated

docs: align identity exchange with the per-request _meta fields

aa582cb

localden reviewed Jul 20, 2026

View reviewed changes

Comment thread docs/docs/draft/learn/architecture.mdx Outdated

Comment thread docs/docs/draft/learn/architecture.mdx Outdated

Comment thread docs/docs/draft/learn/architecture.mdx Outdated

Comment thread docs/extensions/client-matrix.mdx Outdated

docs: tidy phrasing in changed prose

e1f93af

localden reviewed Jul 20, 2026

View reviewed changes

Comment thread docs/docs/draft/learn/architecture.mdx Outdated

docs: scope the subscription acknowledgment ordering guarantee

4da6fb3

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DhtN33k4CMKjzsQL2jd6Z9

dsp-ant requested changes Jul 21, 2026

View reviewed changes

Comment thread docs/docs/draft/learn/versioning.mdx Outdated

Comment thread docs/docs/draft/tutorials/security/security_best_practices.mdx Outdated

Comment thread docs/docs/draft/tutorials/security/security_best_practices.mdx Outdated

claude added 2 commits July 21, 2026 03:36

docs: keep versioned tutorial pages scoped to the current protocol

966e2f4

docs: state the per-request version declaration directly

c7b6fc0

localden requested a review from dsp-ant July 22, 2026 16:12

pja-ant reviewed Jul 22, 2026

View reviewed changes

pcarleton reviewed Jul 22, 2026

View reviewed changes

Comment thread docs/docs/draft/develop/clients/client-best-practices.mdx Outdated

claude added 2 commits July 22, 2026 16:22

docs: use client naming in the architecture examples

85a0128

docs: drop the session close step from the client example

4ec29e0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: reflect the stateless protocol, server/discover, and session removal#3069

docs: reflect the stateless protocol, server/discover, and session removal#3069
claude[bot] wants to merge 14 commits into
docs/2026-07-28-releasefrom
claude/rc-stateless-lifecycle

claude Bot commented Jul 10, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

localden left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

localden left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pja-ant Jul 22, 2026

Uh oh!

pja-ant Jul 22, 2026

Uh oh!

pja-ant Jul 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

+for client in app.mcp_clients():
+tools_response = await cient.list_tools()
+available_tools.extend(tools_response.tools)

Uh oh!

Conversation

claude Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

localden left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

localden left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pja-ant Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

pja-ant Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

pja-ant Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

claude Bot commented Jul 10, 2026 •

edited

Loading