First end-to-end 2026-07-28 stateless tools/call (experimental entry + ClientSession pin) (#2917)

tests/client/test_client.py

@@ -316,7 +316,7 @@ async def test_complete_with_prompt_reference(simple_server: Server):
 def test_client_with_url_initializes_streamable_http_transport():
     with patch("mcp.client.client.streamable_http_client") as mock:
         _ = Client("http://localhost:8000/mcp")
-    mock.assert_called_once_with("http://localhost:8000/mcp")
+    mock.assert_called_once_with("http://localhost:8000/mcp", protocol_version=None)
 
 
 async def test_client_uses_transport_directly(app: MCPServer):

tests/client/test_session.py

@@ -1400,6 +1400,66 @@ async def test_aenter_cancelled_while_dispatcher_starts_unwinds_cleanly():
     assert session._task_group is None
 
 
+@pytest.mark.anyio
+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 ``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):
+        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(do_initialize)
+            out = await from_client.receive()
+            assert isinstance(out.message, JSONRPCRequest)
+            assert out.message.params is not None
+            assert out.message.params["protocolVersion"] == "2025-06-18"
+            assert session.protocol_version == "2025-06-18"
+            # Server negotiates a different (older) supported version than the pin requested.
+            result = InitializeResult(
+                protocol_version="2025-03-26",
+                capabilities=ServerCapabilities(),
+                server_info=Implementation(name="mock-server", version="0.1.0"),
+            )
+            await to_client.send(
+                SessionMessage(
+                    JSONRPCResponse(
+                        jsonrpc="2.0",
+                        id=out.message.id,
+                        result=result.model_dump(by_alias=True, mode="json", exclude_none=True),
+                    )
+                )
+            )
+        # 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)
+        # The property reports the negotiated version, not the pin, once the handshake is done.
+        assert session.protocol_version == "2025-03-26"
+        # 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
 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

@@ -0,0 +1,151 @@
+"""Unit tests for the streamable-HTTP client transport.
+
+The full client<->server round trip is pinned by the interaction suite under
+tests/interaction/transports/; these tests cover the transport's per-message header
+derivation directly because the headers are an HTTP-seam observation the public client
+never exposes.
+"""
+
+import base64
+import json
+
+import anyio
+import httpx
+import pytest
+from inline_snapshot import snapshot
+
+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
+
+
+@pytest.mark.parametrize(
+    ("message", "expected"),
+    [
+        (
+            JSONRPCRequest(jsonrpc="2.0", id=1, method="tools/call", params={"name": "add", "arguments": {}}),
+            snapshot({"mcp-method": "tools/call", "mcp-name": "add"}),
+        ),
+        (
+            JSONRPCRequest(jsonrpc="2.0", id=2, method="tools/list", params={}),
+            snapshot({"mcp-method": "tools/list"}),
+        ),
+        (
+            JSONRPCNotification(jsonrpc="2.0", method="notifications/cancelled"),
+            snapshot({"mcp-method": "notifications/cancelled"}),
+        ),
+        (
+            JSONRPCResponse(jsonrpc="2.0", id=3, result={}),
+            snapshot({}),
+        ),
+    ],
+)
+def test_per_message_headers_for_pinned_transport_carry_method_and_name(
+    message: JSONRPCMessage, expected: dict[str, str]
+) -> None:
+    """A 2026-07-28-pinned transport derives ``Mcp-Method`` (and ``Mcp-Name`` for tools/call) from the body.
+
+    ``MCP-Protocol-Version`` is not in the per-message set: ``_prepare_headers()`` adds it from the
+    pin for every request, so only the method/name advisory headers vary per POST. Responses yield
+    nothing because the spec only defines the headers for requests and notifications.
+    """
+    transport = StreamableHTTPTransport("http://test/mcp", protocol_version="2026-07-28")
+    assert transport._per_message_headers(message) == expected  # pyright: ignore[reportPrivateUsage]
+
+
+@pytest.mark.parametrize("protocol_version", [None, "2025-11-25"])
+def test_per_message_headers_are_empty_for_legacy_or_unpinned_transport(protocol_version: str | None) -> None:
+    """An unpinned or 2025-era transport emits no per-message headers, keeping the wire byte-identical to v1."""
+    transport = StreamableHTTPTransport("http://test/mcp", protocol_version=protocol_version)
+    message = JSONRPCRequest(jsonrpc="2.0", id=1, method="tools/call", params={"name": "add", "arguments": {}})
+    assert transport._per_message_headers(message) == {}  # pyright: ignore[reportPrivateUsage]
+
+
+@pytest.mark.parametrize(
+    ("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),
+    ],
+)
+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, 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. 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
+    if wrapped:
+        assert encoded.startswith("=?base64?") and encoded.endswith("?=")
+        assert base64.b64decode(encoded.removeprefix("=?base64?").removesuffix("?=")).decode() == raw
+    else:
+        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")
+    init = JSONRPCResponse(
+        jsonrpc="2.0",
+        id=1,
+        result={
+            "protocolVersion": "2025-11-25",
+            "capabilities": {},
+            "serverInfo": {"name": "s", "version": "0"},
+        },
+    )
+    transport._maybe_extract_protocol_version_from_message(init)  # pyright: ignore[reportPrivateUsage]
+    assert transport.protocol_version == "2026-07-28"