Thread protocol_version through Client and default CacheableResult to immediately-stale private

- Client gains protocol_version: str | None; threads to ClientSession and
  streamable_http_client. The interaction-suite connect factories forward
  the parameter they already accepted.
- CacheableResult defaults to ttl_ms=0, cache_scope="private" so list/read
  results constructed without explicit hints validate against the 2026-07-28
  surface and never accidentally enable shared caching.
- TRANSPORT_SPEC_VERSIONS era-locks in-memory and streamable-http-stateless
  to 2025-11-25 (the former pending a modern in-memory entry; the latter
  collapses into stateful at the newer revision).

Author: maxisbey

docs/migration.md

@@ -1241,7 +1241,7 @@ If you relied on extra fields round-tripping through MCP types, move that data i
 
 ### 2025-11-25 and 2026-07-28 protocol fields modeled
 
-`mcp.types` models the 2025-11-25 and 2026-07-28 protocol fields (e.g. `resultType`, `ttlMs`/`cacheScope` on cacheable results, `inputResponses`/`requestState` on retried requests), so inbound payloads carrying these keys parse into typed fields and round-trip. `ttlMs`/`cacheScope` default to `None`; `resultType` defaults to `"complete"` on concrete results (`None` on `EmptyResult`); the server strips all of them from the wire at pre-2026 versions.
+`mcp.types` models the 2025-11-25 and 2026-07-28 protocol fields (e.g. `resultType`, `ttlMs`/`cacheScope` on cacheable results, `inputResponses`/`requestState` on retried requests), so inbound payloads carrying these keys parse into typed fields and round-trip. `ttlMs`/`cacheScope` default to `0`/`"private"` (immediately stale, not shared-cacheable); `resultType` defaults to `"complete"` on concrete results (`None` on `EmptyResult`); the server strips all of them from the wire at pre-2026 versions.
 
 ### `streamable_http_app()` available on lowlevel Server
 

src/mcp/client/client.py

@@ -92,6 +92,15 @@ async def main():
     client_info: Implementation | None = None
     """Client implementation info to send to server."""
 
+    protocol_version: str | None = None
+    """Pin the protocol version instead of negotiating it.
+
+    Pinning to ``2026-07-28`` or later selects the stateless transport era: no initialize
+    handshake is sent on the wire (the session synthesizes its `InitializeResult` locally),
+    and for HTTP the ``MCP-Protocol-Version`` header is set from the first request.
+    Leave as ``None`` to negotiate the version via the initialize handshake.
+    """
+
     elicitation_callback: ElicitationFnT | None = None
     """Callback for handling elicitation requests."""
 
@@ -103,7 +112,7 @@ def __post_init__(self) -> None:
         if isinstance(self.server, Server | MCPServer):
             self._transport = InMemoryTransport(self.server, raise_exceptions=self.raise_exceptions)
         elif isinstance(self.server, str):
-            self._transport = streamable_http_client(self.server)
+            self._transport = streamable_http_client(self.server, protocol_version=self.protocol_version)
         else:
             self._transport = self.server
 
@@ -126,6 +135,7 @@ async def __aenter__(self) -> Client:
                     message_handler=self.message_handler,
                     client_info=self.client_info,
                     elicitation_callback=self.elicitation_callback,
+                    protocol_version=self.protocol_version,
                 )
             )
 

src/mcp/types/_types.py

@@ -185,15 +185,17 @@ class PaginatedResult(Result):
 class CacheableResult(Result):
     """Base class for results that carry client-side caching directives (2026-07-28).
 
-    Both fields are required on the 2026-07-28 wire; the SDK declares no
-    default, so a handler answering at 2026-07-28 must set them explicitly.
+    Both fields are required on the 2026-07-28 wire. The SDK defaults to
+    `ttl_ms=0` (immediately stale) and `cache_scope="private"` so a handler
+    that doesn't set them still produces a valid 2026-07-28 result without
+    accidentally enabling shared caching.
     """
 
-    ttl_ms: Annotated[int, Field(ge=0)] | None = None
+    ttl_ms: Annotated[int, Field(ge=0)] = 0
     """How long (ms) the client MAY cache this response, analogous to HTTP
     `Cache-Control: max-age`. 0 means immediately stale."""
 
-    cache_scope: Literal["public", "private"] | None = None
+    cache_scope: Literal["public", "private"] = "private"
     """Analogous to HTTP `Cache-Control: public` vs `private`: "public" allows
     shared caches to serve the response to any user; "private" forbids that."""
 

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/interaction/_connect.py

@@ -97,6 +97,7 @@ async def connect_in_memory(
         message_handler=message_handler,
         client_info=client_info,
         elicitation_callback=elicitation_callback,
+        protocol_version=protocol_version,
     ) as client:
         yield client
 
@@ -137,14 +138,15 @@ async def connect_over_streamable_http(
         server.session_manager.run(),
         httpx.AsyncClient(transport=StreamingASGITransport(app), base_url=BASE_URL) as http_client,
         Client(
-            streamable_http_client(f"{BASE_URL}/mcp", http_client=http_client),
+            streamable_http_client(f"{BASE_URL}/mcp", http_client=http_client, protocol_version=protocol_version),
             read_timeout_seconds=read_timeout_seconds,
             sampling_callback=sampling_callback,
             list_roots_callback=list_roots_callback,
             logging_callback=logging_callback,
             message_handler=message_handler,
             client_info=client_info,
             elicitation_callback=elicitation_callback,
+            protocol_version=protocol_version,
         ) as client,
     ):
         yield client

tests/interaction/_requirements.py

@@ -63,6 +63,13 @@
 
 TRANSPORT_SPEC_VERSIONS: dict[Transport, tuple[SpecVersion, ...]] = {
     "sse": ("2025-11-25",),
+    # Temporary lock: the in-memory transport has no modern entry point yet, so it cannot
+    # negotiate the newer revision. Remove once an in-memory factory for the modern path lands.
+    "in-memory": ("2025-11-25",),
+    # At the newer revision the protocol-version header check runs before the stateless branch is
+    # taken, so a stateless connection at that revision behaves identically to the stateful one.
+    # Locked to avoid a redundant matrix column; revisit if the header/stateless ordering changes.
+    "streamable-http-stateless": ("2025-11-25",),
 }
 """Transports that only serve a subset of SPEC_VERSIONS. Absent => serves all. Consulted by compute_cells()."""
 

tests/interaction/test_coverage.py

@@ -301,9 +301,7 @@ def test_compute_cells_drops_era_locked_transport_outside_its_versions() -> None
         "sse-2025-11-25",
         "streamable-http-2025-11-25",
         "streamable-http-stateless-2025-11-25",
-        "in-memory-2026-07-28",
         "streamable-http-2026-07-28",
-        "streamable-http-stateless-2026-07-28",
     ]
 
 

tests/test_types.py

@@ -401,9 +401,10 @@ def test_concrete_wire_results_always_dump_result_type_complete():
         assert _wire_dump(result)["resultType"] == "complete", type(result).__name__
 
 
-def test_cacheable_results_omit_unset_caching_directives():
-    """`ttl_ms`/`cache_scope` default to None: the SDK declares no caching policy
-    so a 2026-07-28 handler must set them explicitly."""
+def test_cacheable_results_default_to_immediately_stale_private():
+    """`ttl_ms`/`cache_scope` default to 0/"private" so list-results validate at
+    2026-07-28 without the handler setting them, and never accidentally enable
+    shared caching."""
     cacheable: list[Result] = [
         ReadResourceResult(contents=[]),
         ListPromptsResult(prompts=[]),
@@ -418,8 +419,8 @@ def test_cacheable_results_omit_unset_caching_directives():
     ]
     for result in cacheable:
         dumped = _wire_dump(result)
-        assert "ttlMs" not in dumped, type(result).__name__
-        assert "cacheScope" not in dumped, type(result).__name__
+        assert dumped["ttlMs"] == 0, type(result).__name__
+        assert dumped["cacheScope"] == "private", type(result).__name__
     explicit = _wire_dump(ListToolsResult(tools=[], ttl_ms=5, cache_scope="public"))
     assert explicit["ttlMs"] == 5
     assert explicit["cacheScope"] == "public"

tests/types/test_wire_frames.py

@@ -61,12 +61,13 @@ def test_non_empty_result_dump_carries_result_type_complete_before_the_sieve():
     )
 
 
-def test_cacheable_list_result_dump_omits_unset_caching_directives():
-    """`ttl_ms`/`cache_scope` default to None so the raw dump omits them; 2026 handlers set them explicitly."""
+def test_cacheable_list_result_dump_carries_default_caching_directives():
+    """`ttl_ms`/`cache_scope` default to 0/"private" so the raw dump carries them; the
+    runner's per-version sieve drops them for pre-2026 peers."""
     result = ListToolsResult(tools=[Tool(name="echo", input_schema={"type": "object"})])
     frame = JSONRPCResponse(jsonrpc="2.0", id=2, result=_body(result))
     assert _frame(frame) == snapshot(
-        '{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"echo","inputSchema":{"type":"object"}}],"resultType":"complete"}}'
+        '{"jsonrpc":"2.0","id":2,"result":{"ttlMs":0,"cacheScope":"private","tools":[{"name":"echo","inputSchema":{"type":"object"}}],"resultType":"complete"}}'
     )