Address review feedback and consolidate 2026-07-28 interaction tests

Review-response changes:
- Merge the duplicate _pinned_version guard in ClientSession.send_request
- Use is_version_at_least() instead of a raw string compare for the
  per-message-headers gate
- Base64-wrap Mcp-Name values with leading/trailing spaces (RFC 7230
  forbids them; h11 rejects on real transports)
- Add a TODO at the Mcp-Name gate naming prompts/get and resources/read
- Type the protocol_version pin as Literal["2026-07-28"] via
  StatelessProtocolVersion so 2025-era values are a type error
- Reword the _related_request_id TODO in ServerSession to point at the
  per-request Outbound shape (not at widening the Protocol)

Interaction-suite consolidation:
- Drop test_lifecycle_stateless.py and test_client_transport_http_modern.py;
  their assertions are now proven by the capstone in
  test_hosting_http_modern.py (envelope, headers, no-initialize) or moved
  to tests/client/ (initialize-raises, session-id-ignore against a
  misbehaving peer)
- Extend the capstone to capture ctx.meta server-side and assert the
  caller-supplied _meta key survives the envelope merge
- Reconcile _requirements.py: stack request-envelope and
  caller-meta-preserved on the capstone; defer no-initialize and
  stateless-ignores-session-id to tests/client/; drop the duplicate
  unpinned-legacy-wire and body-derived-headers entries

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
+from mcp.shared.version import SUPPORTED_PROTOCOL_VERSIONS, StatelessProtocolVersion
 from mcp.types import (
     CLIENT_CAPABILITIES_META_KEY,
     CLIENT_INFO_META_KEY,
@@ -149,7 +149,7 @@ def __init__(
         message_handler: MessageHandlerFnT | None = None,
         client_info: types.Implementation | None = None,
         *,
-        protocol_version: str | None = None,
+        protocol_version: StatelessProtocolVersion | None = None,
         sampling_capabilities: types.SamplingCapability | None = None,
         dispatcher: Dispatcher[Any] | None = None,
     ) -> None:
@@ -228,6 +228,7 @@ async def send_request(
         """
         data = request.model_dump(by_alias=True, mode="json", exclude_none=True)
         method: str = data["method"]
+        opts: CallOptions = {}
         if self._pinned_version is not None:
             params = data.setdefault("params", {})
             envelope_meta = params.setdefault("_meta", {})
@@ -238,8 +239,6 @@ async def send_request(
             envelope_meta[CLIENT_CAPABILITIES_META_KEY] = self._build_capabilities().model_dump(
                 by_alias=True, mode="json", exclude_none=True
             )
-        opts: CallOptions = {}
-        if self._pinned_version is not None:
             # Stateless pinned mode: disconnect-as-cancel is the spec mechanism, so the
             # dispatcher must not emit notifications/cancelled when the caller abandons.
             opts["cancel_on_abandon"] = False

src/mcp/client/streamable_http.py

@@ -21,6 +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 StatelessProtocolVersion, is_version_at_least
 from mcp.types import (
     INTERNAL_ERROR,
     INVALID_REQUEST,
@@ -60,7 +61,7 @@
 
 
 def _encode_header_value(value: str) -> str:
-    if _HEADER_SAFE.fullmatch(value) and not _B64_SENTINEL.fullmatch(value):
+    if _HEADER_SAFE.fullmatch(value) and value == value.strip(" ") and not _B64_SENTINEL.fullmatch(value):
         return value
     return f"=?base64?{base64.b64encode(value.encode('utf-8')).decode('ascii')}?="
 
@@ -107,11 +108,13 @@ def _per_message_headers(self, message: JSONRPCMessage) -> dict[str, str]:
         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 self.protocol_version < "2026-07-28":
+        if self.protocol_version is None or not is_version_at_least(self.protocol_version, "2026-07-28"):
             return {}
         if not isinstance(message, JSONRPCRequest | JSONRPCNotification):
             return {}
         headers: dict[str, str] = {MCP_METHOD: message.method}
+        # TODO: Mcp-Name is also REQUIRED for prompts/get (params.name) and resources/read
+        # (params.uri); a method->param-key map replaces this gate when those land.
         if (
             isinstance(message, JSONRPCRequest)
             and message.method == "tools/call"
@@ -564,7 +567,7 @@ async def streamable_http_client(
     *,
     http_client: httpx.AsyncClient | None = None,
     terminate_on_close: bool = True,
-    protocol_version: str | None = None,
+    protocol_version: StatelessProtocolVersion | None = None,
 ) -> AsyncGenerator[TransportStreams, None]:
     """Client transport for StreamableHTTP.
 

src/mcp/server/session.py

@@ -91,8 +91,11 @@ async def send_request(
             # Fail fast instead of parking forever on a response that cannot
             # arrive; matches `Connection.send_raw_request`.
             raise NoBackChannelError(data["method"])
-        # TODO: _related_request_id is not on the Dispatcher Protocol; either
-        # add it there or refactor ServerSession once the legacy path is compat-only.
+        # TODO: _related_request_id is not on the Dispatcher Protocol (and must not
+        # be — it's transport-specific). The fix is to give `ctx.session` a per-request
+        # Outbound (the DispatchContext, which threads its own request_id) alongside
+        # the connection-level one, with `related_request_id` as the selector; that
+        # belongs with the ServerSession/Context rework, not here.
         result = cast(
             "dict[str, Any]",
             await self._dispatcher.send_raw_request(

src/mcp/shared/version.py

@@ -7,10 +7,13 @@
 ordering questions go through KNOWN_PROTOCOL_VERSIONS.
 """
 
-from typing import Final
+from typing import Final, Literal
 
 from mcp.types import LATEST_PROTOCOL_VERSION
 
+StatelessProtocolVersion = Literal["2026-07-28"]
+"""Protocol revisions that use the stateless per-request envelope (no `initialize`)."""
+
 KNOWN_PROTOCOL_VERSIONS: Final[tuple[str, ...]] = (
     "2024-11-05",
     "2025-03-26",

tests/client/test_session.py

@@ -1400,6 +1400,19 @@ async def notify(self, method: str, params: Mapping[str, Any] | None) -> None:
     assert session._task_group is None
 
 
+@pytest.mark.anyio
+async def test_initialize_on_a_pinned_session_raises_before_any_frame_is_sent():
+    """A session pinned to the 2026-07-28 stateless protocol rejects ``initialize()`` locally.
+
+    The 2026-07-28 lifecycle replaces the initialize handshake with a per-request ``_meta``
+    envelope, so calling ``initialize()`` on a pinned session is a programmer error and raises
+    immediately rather than reaching the wire.
+    """
+    async with raw_client_session(protocol_version="2026-07-28") as (session, _send, _recv):
+        with pytest.raises(RuntimeError, match="pinned to a stateless"):
+            await session.initialize()
+
+
 @pytest.mark.anyio
 async def test_send_notification_after_close_is_dropped_silently():
     """Post-close `send_notification` is fire-and-forget: the notification is dropped,

tests/client/test_streamable_http.py

@@ -7,11 +7,15 @@
 """
 
 import base64
+import json
 
+import anyio
+import httpx
 import pytest
 from inline_snapshot import snapshot
 
-from mcp.client.streamable_http import StreamableHTTPTransport, _encode_header_value
+from mcp.client import ClientSession
+from mcp.client.streamable_http import StreamableHTTPTransport, _encode_header_value, streamable_http_client
 from mcp.types import JSONRPCMessage, JSONRPCNotification, JSONRPCRequest, JSONRPCResponse
 
 
@@ -61,7 +65,10 @@ def test_per_message_headers_are_empty_for_legacy_or_unpinned_transport(protocol
     ("raw", "expected", "wrapped"),
     [
         ("add", snapshot("add"), False),
+        ("", snapshot(""), False),
         ("tool with spaces", snapshot("tool with spaces"), False),
+        (" add", snapshot("=?base64?IGFkZA==?="), True),
+        ("add ", snapshot("=?base64?YWRkIA==?="), True),
         ("résumé", snapshot("=?base64?csOpc3Vtw6k=?="), True),
         ("a\r\nb", snapshot("=?base64?YQ0KYg==?="), True),
         ("=?base64?Zm9v?=", snapshot("=?base64?PT9iYXNlNjQ/Wm05dj89?="), True),
@@ -70,10 +77,12 @@ def test_per_message_headers_are_empty_for_legacy_or_unpinned_transport(protocol
 def test_mcp_name_header_values_are_base64_wrapped_when_unsafe_for_an_http_field(
     raw: str, expected: str, wrapped: bool
 ) -> None:
-    """Printable-ASCII names pass verbatim; CR/LF, non-ASCII, and sentinel-shaped names are wrapped.
+    """Printable-ASCII names pass verbatim; CR/LF, non-ASCII, edge-whitespace, and sentinel-shaped names are wrapped.
 
     The ``=?base64?...?=`` sentinel is the spec's RFC 7230 safety gate for the ``Mcp-Name`` header.
-    Wrapped values round-trip through base64 so the server can recover the original name.
+    Wrapped values round-trip through base64 so the server can recover the original name. A leading
+    or trailing space is wrapped because RFC 7230 forbids it in field-values (h11 rejects on real
+    transports); an empty value is allowed and passes verbatim.
     """
     encoded = _encode_header_value(raw)
     assert encoded == expected
@@ -84,6 +93,48 @@ def test_mcp_name_header_values_are_base64_wrapped_when_unsafe_for_an_http_field
         assert encoded == raw
 
 
+@pytest.mark.anyio
+async def test_pinned_transport_ignores_returned_session_id_and_never_opens_get_or_delete() -> None:
+    """A server-issued ``Mcp-Session-Id`` never reaches a pinned client's wire: only POSTs are sent.
+
+    The session-id capture, the standalone GET listening stream, and the DELETE-on-close are all
+    gated implicitly: a pinned ``ClientSession`` never sends ``initialize`` (no InitializeResult to
+    capture an id from) and never sends ``notifications/initialized`` (which is what triggers the
+    standalone GET), so even when a misbehaving peer volunteers a session id on every response the
+    recorded log stays POST-only and no request echoes the id back. The successful ``tools/call``
+    triggers the client's implicit ``tools/list`` output-schema fetch so there is a second POST
+    after the id was offered.
+    """
+    recorded: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        recorded.append(request)
+        body = json.loads(request.content)
+        if body["method"] == "tools/list":
+            result: dict[str, object] = {
+                "tools": [{"name": "add", "inputSchema": {"type": "object"}}],
+                "resultType": "complete",
+                "ttlMs": 0,
+                "cacheScope": "public",
+            }
+        else:
+            result = {"content": [{"type": "text", "text": "5"}], "isError": False, "resultType": "complete"}
+        return httpx.Response(
+            200, json={"jsonrpc": "2.0", "id": body["id"], "result": result}, headers={"mcp-session-id": "srv-123"}
+        )
+
+    with anyio.fail_after(5):
+        async with (
+            httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http,
+            streamable_http_client("http://test/mcp", http_client=http, protocol_version="2026-07-28") as (read, write),
+            ClientSession(read, write, protocol_version="2026-07-28") as session,
+        ):
+            await session.call_tool("add", {"a": 2, "b": 3})
+
+    assert [r.method for r in recorded] == snapshot(["POST", "POST"])
+    assert all("mcp-session-id" not in r.headers for r in recorded)
+
+
 def test_constructor_pin_is_not_overwritten_by_an_initialize_result() -> None:
     """A protocol_version passed at construction wins over the InitializeResult snoop."""
     transport = StreamableHTTPTransport("http://test/mcp", protocol_version="2026-07-28")

tests/interaction/_requirements.py

@@ -331,6 +331,7 @@ def __post_init__(self) -> None:
         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.",
         added_in="2026-07-28",
+        deferred="covered by a tests/client/ unit test; not observable as an interaction",
     ),
     "lifecycle:stateless:caller-meta-preserved": Requirement(
         source=f"{SPEC_2026_BASE_URL}/basic/lifecycle#stateless-operation",
@@ -340,13 +341,6 @@ def __post_init__(self) -> None:
         ),
         added_in="2026-07-28",
     ),
-    "lifecycle:stateless:unpinned-legacy-wire": Requirement(
-        source=f"{SPEC_2026_BASE_URL}/basic/versioning",
-        behavior=(
-            "An unpinned session that negotiates an earlier protocol version emits no 2026-07-28 "
-            "vocabulary on any JSON-RPC frame in either direction."
-        ),
-    ),
     # ═══════════════════════════════════════════════════════════════════════════
     # Protocol primitives: cancellation, timeout, progress, errors, _meta
     # ═══════════════════════════════════════════════════════════════════════════
@@ -3137,16 +3131,6 @@ def __post_init__(self) -> None:
         removed_in="2026-07-28",
         note="removed in 2026-07-28 (SEP-2567); session DELETE removed with Mcp-Session-Id, no replacement.",
     ),
-    "client-transport:http:body-derived-headers": Requirement(
-        source=f"{SPEC_2026_BASE_URL}/basic/transports#stateless-request-headers",
-        behavior=(
-            "An envelope-bearing request body yields MCP-Protocol-Version, Mcp-Method, and (for tools/call) "
-            "Mcp-Name headers on the outgoing HTTP request; a body without the envelope yields none."
-        ),
-        added_in="2026-07-28",
-        transports=("streamable-http",),
-        note="Only observable over streamable HTTP: headers are derived from the body envelope at the transport seam.",
-    ),
     "client-transport:http:stateless-ignores-session-id": Requirement(
         source=f"{SPEC_2026_BASE_URL}/basic/transports#stateless-request-headers",
         behavior=(
@@ -3156,6 +3140,7 @@ def __post_init__(self) -> None:
         added_in="2026-07-28",
         transports=("streamable-http",),
         note="Only observable over streamable HTTP: session-id, GET stream and DELETE are streamable-HTTP mechanics.",
+        deferred="defensive against a misbehaving peer; covered by a tests/client/ unit test",
     ),
     # ═══════════════════════════════════════════════════════════════════════════
     # Client auth