Make a pinned ClientSession born-initialized and centralize the modern-version constants

- A 2026-07-28-pinned ClientSession is born initialized: __init__ synthesizes
  an InitializeResult (placeholder server_info until server/discover lands)
  and initialize() returns it idempotently with no wire traffic. A repeat
  initialize() on a stateful session likewise returns the cached result.
  A stateful pin still requests that version on first call.
- Add FIRST_MODERN_VERSION and MODERN_PROTOCOL_VERSIONS to mcp/shared/version
  and import them at the four call sites that previously inlined the literal.
- Move the modern HTTP serving entry from _experimental/ to a private sibling
  module (mcp.server._streamable_http_modern); drop the empty package.

Author: maxisbey

src/mcp/client/session.py

@@ -21,7 +21,7 @@
 from mcp.shared.message import ClientMessageMetadata, SessionMessage
 from mcp.shared.session import RequestResponder
 from mcp.shared.transport_context import TransportContext
-from mcp.shared.version import SUPPORTED_PROTOCOL_VERSIONS, is_version_at_least
+from mcp.shared.version import FIRST_MODERN_VERSION, SUPPORTED_PROTOCOL_VERSIONS, is_version_at_least
 from mcp.types import (
     CLIENT_CAPABILITIES_META_KEY,
     CLIENT_INFO_META_KEY,
@@ -156,15 +156,29 @@ def __init__(
         self._session_read_timeout_seconds = read_timeout_seconds
         self._client_info = client_info or DEFAULT_CLIENT_INFO
         self._pinned_version = protocol_version
-        self._stateless_pinned = protocol_version is not None and is_version_at_least(protocol_version, "2026-07-28")
+        self._stateless_pinned = protocol_version is not None and is_version_at_least(
+            protocol_version, FIRST_MODERN_VERSION
+        )
         self._sampling_callback = sampling_callback or _default_sampling_callback
         self._sampling_capabilities = sampling_capabilities
         self._elicitation_callback = elicitation_callback or _default_elicitation_callback
         self._list_roots_callback = list_roots_callback or _default_list_roots_callback
         self._logging_callback = logging_callback or _default_logging_callback
         self._message_handler = message_handler or _default_message_handler
         self._tool_output_schemas: dict[str, dict[str, Any] | None] = {}
-        self._initialize_result: types.InitializeResult | None = None
+        self._initialize_result: types.InitializeResult | None
+        if self._stateless_pinned:
+            assert protocol_version is not None
+            # A stateless-pinned session is born initialized: there is no handshake
+            # at 2026-07-28+, so we synthesize the result locally. `server_info` is a
+            # placeholder until `server/discover` is implemented to populate it.
+            self._initialize_result = types.InitializeResult(
+                protocol_version=protocol_version,
+                capabilities=types.ServerCapabilities(),
+                server_info=types.Implementation(name="", version=""),
+            )
+        else:
+            self._initialize_result = None
         self._task_group: anyio.abc.TaskGroup | None = None
         if dispatcher is not None:
             if read_stream is not None or write_stream is not None:
@@ -300,8 +314,8 @@ def _build_capabilities(self) -> types.ClientCapabilities:
         return types.ClientCapabilities(sampling=sampling, elicitation=elicitation, experimental=None, roots=roots)
 
     async def initialize(self) -> types.InitializeResult:
-        if self._stateless_pinned:
-            raise RuntimeError("initialize() must not be called on a session pinned to a stateless protocol version")
+        if self._initialize_result is not None:
+            return self._initialize_result
         capabilities = self._build_capabilities()
         result = await self.send_request(
             types.InitializeRequest(
@@ -329,7 +343,11 @@ async def initialize(self) -> types.InitializeResult:
     def initialize_result(self) -> types.InitializeResult | None:
         """The server's InitializeResult. None until initialize() has been called.
 
-        Contains server_info, capabilities, instructions, and the negotiated protocol_version.
+        A stateless-pinned session (protocol_version >= 2026-07-28) is born
+        initialized: this property is populated at construction with a
+        synthesized result and `initialize()` returns it without touching the
+        wire. Contains server_info, capabilities, instructions, and the
+        negotiated protocol_version.
         """
         return self._initialize_result
 

src/mcp/client/streamable_http.py

@@ -21,7 +21,7 @@
 from mcp.shared._context_streams import ContextReceiveStream, ContextSendStream, create_context_streams
 from mcp.shared._httpx_utils import create_mcp_http_client
 from mcp.shared.message import ClientMessageMetadata, SessionMessage
-from mcp.shared.version import is_version_at_least
+from mcp.shared.version import FIRST_MODERN_VERSION, is_version_at_least
 from mcp.types import (
     INTERNAL_ERROR,
     INVALID_REQUEST,
@@ -101,14 +101,13 @@ def __init__(self, url: str, protocol_version: str | None = None) -> None:
         self.session_id: str | None = None
         self.protocol_version: str | None = protocol_version
 
-    # TODO: header derivation from the pin (not body _meta) per spec; body envelope is request-only.
     def _per_message_headers(self, message: JSONRPCMessage) -> dict[str, str]:
         """Per-POST routing headers (Mcp-Method, Mcp-Name) for 2026-07-28+ pinned transports.
 
         MCP-Protocol-Version is not emitted here — `_prepare_headers()` already adds it
         from `self.protocol_version` for every request.
         """
-        if self.protocol_version is None or not is_version_at_least(self.protocol_version, "2026-07-28"):
+        if self.protocol_version is None or not is_version_at_least(self.protocol_version, FIRST_MODERN_VERSION):
             return {}
         if not isinstance(message, JSONRPCRequest | JSONRPCNotification):
             return {}

src/mcp/server/_experimental/__init__.py

@@ -1,8 +1,8 @@
-"""Experimental, unstable. Single-exchange HTTP serving for protocol version 2026-07-28.
+"""Single-exchange HTTP serving for protocol version 2026-07-28.
 
-No public API; everything in this module may change or vanish without
-deprecation. The legacy streamable-HTTP transport is untouched and remains the
-supported entry point.
+Private module — entry is via `StreamableHTTPSessionManager.handle_request`.
+The legacy streamable-HTTP transport is untouched and remains the supported
+path for earlier protocol revisions.
 
 A 2026-07-28 request is a self-contained POST: no `initialize` handshake, no
 `Mcp-Session-Id`, one JSON-RPC request in, one JSON-RPC response out. This
@@ -15,7 +15,7 @@
 import logging
 from collections.abc import Mapping
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Final
+from typing import TYPE_CHECKING, Any
 
 import anyio
 import anyio.abc
@@ -34,6 +34,7 @@
 from mcp.shared.exceptions import MCPError, NoBackChannelError
 from mcp.shared.message import MessageMetadata, ServerMessageMetadata
 from mcp.shared.transport_context import TransportContext
+from mcp.shared.version import FIRST_MODERN_VERSION as MODERN_PROTOCOL_VERSION
 from mcp.types import (
     INTERNAL_ERROR,
     INVALID_PARAMS,
@@ -50,10 +51,6 @@
 
 logger = logging.getLogger(__name__)
 
-MODERN_PROTOCOL_VERSION: Final[str] = "2026-07-28"
-"""The protocol version this module serves. Kept local so it does not leak into
-`SUPPORTED_PROTOCOL_VERSIONS` or the legacy handshake."""
-
 
 @dataclass
 class _SingleExchangeDispatchContext:

…/_experimental/streamable_http_modern.py src/mcp/server/_streamable_http_modern.pysrc/mcp/server/_experimental/streamable_http_modern.py renamed to src/mcp/server/_streamable_http_modern.py src/mcp/server/_experimental/streamable_http_modern.py renamed to src/mcp/server/_streamable_http_modern.py

@@ -14,7 +14,7 @@
 from starlette.responses import Response
 from starlette.types import Receive, Scope, Send
 
-from mcp.server._experimental.streamable_http_modern import handle_modern_request
+from mcp.server._streamable_http_modern import handle_modern_request
 from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser, AuthorizationContext, authorization_context
 from mcp.server.streamable_http import (
     MCP_SESSION_ID_HEADER,
@@ -23,6 +23,7 @@
 )
 from mcp.server.transport_security import TransportSecuritySettings
 from mcp.shared._compat import resync_tracer
+from mcp.shared.version import MODERN_PROTOCOL_VERSIONS
 from mcp.types import INVALID_REQUEST, ErrorData, JSONRPCError
 
 if TYPE_CHECKING:
@@ -154,7 +155,7 @@ async def handle_request(self, scope: Scope, receive: Receive, send: Send) -> No
         # TODO: header-only routing for now; body-primary classification
         # (per SEP-2575) is a follow-up. 2025 paths below remain unchanged.
         pv = next((v.decode("latin-1") for k, v in scope["headers"] if k == b"mcp-protocol-version"), None)
-        if pv == "2026-07-28":
+        if pv in MODERN_PROTOCOL_VERSIONS:
             await handle_modern_request(self.app, self.security_settings, scope, receive, send)
             return
 

src/mcp/server/streamable_http_manager.py

@@ -20,6 +20,12 @@
 )
 """Every released protocol revision, oldest to newest."""
 
+FIRST_MODERN_VERSION: Final[str] = "2026-07-28"
+"""First protocol revision with the stateless per-request envelope (no `initialize`)."""
+
+MODERN_PROTOCOL_VERSIONS: Final[tuple[str, ...]] = ("2026-07-28",)
+"""Protocol revisions that use the stateless per-request envelope."""
+
 SUPPORTED_PROTOCOL_VERSIONS: list[str] = ["2024-11-05", "2025-03-26", "2025-06-18", LATEST_PROTOCOL_VERSION]
 """Protocol revisions this SDK can negotiate."""
 

src/mcp/shared/version.py

@@ -1401,26 +1401,33 @@ async def notify(self, method: str, params: Mapping[str, Any] | None) -> None:
 
 
 @pytest.mark.anyio
-async def test_initialize_on_a_stateless_pinned_session_raises_before_any_frame_is_sent():
-    """A session pinned to the 2026-07-28 stateless protocol rejects ``initialize()`` locally.
+async def test_initialize_on_a_stateless_pinned_session_returns_the_synthesized_result_without_any_frame_sent():
+    """A session pinned to the 2026-07-28 stateless protocol is born initialized.
 
     The 2026-07-28 lifecycle replaces the initialize handshake with a per-request ``_meta``
-    envelope, so calling ``initialize()`` on a stateless-pinned session is a programmer error
-    and raises immediately rather than reaching the wire.
+    envelope, so ``initialize()`` is idempotent and returns a locally-synthesized result
+    without ever touching the wire.
     """
     async with raw_client_session(protocol_version="2026-07-28") as (session, _send, from_client):
-        with pytest.raises(RuntimeError, match="pinned to a stateless"):
-            await session.initialize()
+        result = await session.initialize()
+        assert result.protocol_version == "2026-07-28"
+        assert isinstance(result.capabilities, ServerCapabilities)
         assert from_client.statistics().current_buffer_used == 0
+        assert (await session.initialize()) is result
 
 
 @pytest.mark.anyio
 async def test_initialize_on_a_stateful_pin_requests_the_pinned_version():
     """A session pinned to a pre-2026 stateful version still runs the handshake, but the
     outgoing ``initialize`` frame requests the pinned version rather than ``LATEST``."""
     async with raw_client_session(protocol_version="2025-06-18") as (session, to_client, from_client):
+        first: list[InitializeResult] = []
+
+        async def do_initialize() -> None:
+            first.append(await session.initialize())
+
         async with anyio.create_task_group() as tg:
-            tg.start_soon(session.initialize)
+            tg.start_soon(do_initialize)
             out = await from_client.receive()
             assert isinstance(out.message, JSONRPCRequest)
             assert out.message.params is not None
@@ -1439,6 +1446,14 @@ async def test_initialize_on_a_stateful_pin_requests_the_pinned_version():
                     )
                 )
             )
+        # Drain the notifications/initialized frame so the buffer-used assertion below
+        # measures only what the second initialize() emits.
+        notif = await from_client.receive()
+        assert isinstance(notif.message, JSONRPCNotification)
+        # A second call returns the cached result without a second handshake frame.
+        again = await session.initialize()
+        assert again is first[0]
+        assert from_client.statistics().current_buffer_used == 0
 
 
 @pytest.mark.anyio

tests/client/test_session.py

@@ -329,7 +329,10 @@ def __post_init__(self) -> None:
     ),
     "lifecycle:stateless:no-initialize": Requirement(
         source=f"{SPEC_2026_BASE_URL}/basic/lifecycle#stateless-operation",
-        behavior="A ClientSession pinned to 2026-07-28 rejects initialize() before any frame is sent.",
+        behavior=(
+            "A ClientSession pinned to 2026-07-28 is born initialized: initialize() is idempotent "
+            "and returns the synthesized result without any frame sent."
+        ),
         added_in="2026-07-28",
         deferred="covered by a tests/client/ unit test; not observable as an interaction",
     ),

tests/interaction/_requirements.py

@@ -1,4 +1,4 @@
-"""Unit tests for the experimental 2026-07-28 single-exchange HTTP serving entry.
+"""Unit tests for the 2026-07-28 single-exchange HTTP serving entry.
 
 The interaction suite under ``tests/interaction/transports/test_hosting_http_modern.py`` pins
 the wire contract end to end; these tests cover the module's internal seams directly --
@@ -16,9 +16,9 @@
 from starlette.requests import Request
 from starlette.types import Receive, Scope, Send
 
-import mcp.server._experimental.streamable_http_modern as modern
+import mcp.server._streamable_http_modern as modern
 from mcp.server import Server, ServerRequestContext
-from mcp.server._experimental.streamable_http_modern import (
+from mcp.server._streamable_http_modern import (
     SingleExchangeDispatcher,
     _SingleExchangeDispatchContext,
     handle_modern_request,