Extend the interaction suite to the 2026-07-28 spec

Take tests/interaction/ from its 2025-11-25 baseline to the 2026-07-28
revision, keeping the suite's rule that every manifest entry is backed by a
high-level, public-API scenario test.

Manifest groundwork on the existing entries: dead 2026 source URLs repointed
at live sections, ids aligned with the typescript-sdk e2e vocabulary,
over-claiming behaviour strings narrowed to what their tests prove, and the
era pass: behaviours the new revision retired carry removed_in, their
replacements carry added_in, and the pairs are linked supersedes /
superseded_by (enforced bidirectionally by the coverage gate at import), so
no test body branches on a version literal.

New coverage, all driven through Client against a server declared inside the
test and run across the transport x spec-version matrix where the behaviour
allows: multi round-trip requests end to end (the input_required round trip,
requestState echo, omission, opacity and the default sealing that rejects a
tampered or replayed token, parallel-call isolation, multi-round completion
and bounds, all three origin methods, and the MCPServer authoring surface:
Resolve with Elicit, Sample and ListRoots dependencies plus input_required
pass-through for resources and prompts); the 2026 message-direction rules;
server/discover, version modes and the -32022 retry; the per-request
envelope; the modern streamable-HTTP entry (response modes, lazy SSE
upgrade, the header-validation ladder, cacheable stamping); the x-mcp-header
pipeline in both directions; response caching hints; subscriptions/listen
(typed events per kind, acknowledgment stamping, per-stream filtering,
concurrent demultiplexing, the capacity guard, MCPServer change
notifications); stdio serving both eras from the same server; OAuth
negotiating the modern era after authenticating, RFC 9207 iss validation,
step-up bounds and refresh rotation; resultType handling; JSON Schema
2020-12 output validation; and the era method gate.

Where the SDK's current behaviour differs from the spec the test pins today's
behaviour and the entry records the divergence with the re-pin instruction
in the test docstring. Deferred entries are limited to behaviour the SDK
cannot express through its public API, each with a one-line reason.

No-Verification-Needed: test-only change

Author: maxisbey

tests/_stamp.py

@@ -6,10 +6,13 @@
 and the strip is strict, so a modern result that lost its stamp fails the
 test instead of passing silently.
 
-The interaction matrix does not use this function directly: its `unstamped`
-fixture (tests/interaction/conftest.py) resolves per cell to this strict
+Era-parametrized interaction tests go through the `unstamped` fixture
+(tests/interaction/conftest.py), which resolves per cell to this strict
 strip on modern cells and to a must-not-be-stamped assertion on
-handshake-era cells, so one comparison line enforces both eras.
+handshake-era cells, so one comparison line enforces both eras. Interaction
+tests pinned to a single modern connection call this function directly
+(imported as `strip_stamp` where a file also uses the fixture, so the two
+never share a name).
 """
 
 from typing import Any, Protocol, TypeVar
@@ -29,8 +32,8 @@ def unstamped(result: R) -> R:
     """Assert the result carries a well-formed serverInfo stamp, then remove it.
 
     Returns the result for inline use in comparisons. Use only where a stamp
-    is required (a 2026-era result); the interaction matrix's `unstamped`
-    fixture handles the era split.
+    is required (a 2026-era result); tests that also run on handshake-era
+    cells use the `unstamped` fixture instead, which handles the era split.
     """
     meta = result.meta
     assert meta is not None and SERVER_INFO_META_KEY in meta, "expected a serverInfo stamp on this result"

tests/interaction/README.md

@@ -40,7 +40,7 @@ flows — with a single subprocess test for stdio.
 ```text
 tests/interaction/
   _requirements.py      the requirements manifest (see below)
-  _helpers.py           the wire-recording transport
+  _helpers.py           the wire-recording transport and the tool_listing handler helper
   _connect.py           the transport-parametrized connection factories
   conftest.py           the connect fixture (the transport matrix)
   test_coverage.py      enforces the manifest ↔ test contract
@@ -64,6 +64,12 @@ stateless configurations), and over the legacy SSE transport the same way. A tes
 `async with connect(server, ...) as client:` and asserts the same output on every leg, because the
 transport is not supposed to change observable behaviour. Requirements that need a server-to-client
 back-channel or persisted session state are carved out of the stateless arm via `arm_exclusions`.
+
+The 2026 cells run the client's response cache in its default-on configuration. Servers stamp
+`ttlMs: 0` by default, so nothing is served from cache unless a test opts in server-side by
+authoring a positive `ttl_ms` — a test that does so and then repeats a call must expect the
+repeat to be served from cache instead of reaching the handler.
+
 Tests that are tied to one transport do not use the fixture: the wire-recording tests
 (their seam is the in-memory stream pair), the bare-`ClientSession` lifecycle tests, the
 real-clock timeout tests (the timeout machinery is transport-independent and must not race
@@ -166,20 +172,19 @@ What admits or excludes a cell:
   closes, grep for the reason string to find every cell to re-admit.
 - **`known_failures`** keep a cell in the grid but mark it as a strict xfail — the test runs and
   must fail; an unexpected pass fails the suite.
-- **`TRANSPORT_SPEC_VERSIONS`** era-locks a transport to a subset of spec versions (currently only
-  `sse` is locked to `2025-11-25`). A `(transport, version)` cell is dropped if the version is not
-  in the transport's entry; transports absent from the map serve every spec version. This is the
-  mechanism for cutting an entire transport off from a new revision (or admitting it).
+- **`TRANSPORT_SPEC_VERSIONS`** era-locks a transport to a subset of spec versions (currently
+  `sse` and `streamable-http-stateless` are locked to `2025-11-25`). A `(transport, version)`
+  cell is dropped if the version is not in the transport's entry; transports absent from the
+  map serve every spec version. This is the mechanism for cutting an entire transport off from
+  a new revision (or admitting it).
 - **`transports`** is descriptive metadata for the non-`connect` transport-specific suites under
   `transports/` and does **not** drive cell generation. Only `arm_exclusions`, `added_in`,
   `removed_in`, and `TRANSPORT_SPEC_VERSIONS` filter the grid.
 - **`supersedes` / `superseded_by`** link a retired entry to its replacement. `test_coverage.py`
   enforces that links are bidirectional and versioned: the retired entry carries `removed_in`, the
   replacement carries `added_in`.
 
-Node IDs stay `[transport]` while `len(SPEC_VERSIONS) == 1`, so today's test IDs are
-byte-identical to before the era axis existed. They become `[transport-version]` the moment a
-second version is appended to `SPEC_VERSIONS`.
+Node IDs are `[transport-version]`; with a single-member `SPEC_VERSIONS` they collapse to `[transport]`.
 
 When a new spec revision lands:
 

tests/interaction/_connect.py

@@ -30,7 +30,7 @@
 from starlette.responses import Response
 from starlette.routing import Mount, Route
 
-from mcp.client.client import Client
+from mcp.client.client import Client, ConnectMode
 from mcp.client.extension import ClientExtension
 from mcp.client.session import ElicitationFnT, ListRootsFnT, LoggingFnT, MessageHandlerFnT, SamplingFnT
 from mcp.client.sse import sse_client
@@ -237,6 +237,9 @@ async def mounted_app(
 async def client_via_http(
     http_client: httpx2.AsyncClient,
     *,
+    mode: ConnectMode = "legacy",
+    sampling_callback: SamplingFnT | None = None,
+    list_roots_callback: ListRootsFnT | None = None,
     logging_callback: LoggingFnT | None = None,
     log_level: LoggingLevel | None = None,
     message_handler: MessageHandlerFnT | None = None,
@@ -247,13 +250,17 @@ async def client_via_http(
     Use with `mounted_app(...)` so several `Client`s share the one session manager, or so a
     client-driven assertion can sit alongside raw-httpx2 assertions in the same test. The
     underlying `httpx2.AsyncClient` is left open when the `Client` exits.
+
+    `mode` defaults to "legacy" because most callers assert the handshake-era HTTP shape
+    (session id, standalone GET, closing DELETE); pass a modern version to pin the 2026-07-28
+    per-request flow instead (no probe, no `prior_discover` needed: the client synthesizes one).
     """
     transport = streamable_http_client(f"{BASE_URL}/mcp", http_client=http_client)
     async with Client(
         transport,
-        # Callers assert the legacy HTTP wire shape (session-id header, standalone GET stream,
-        # closing DELETE); the modern flow is sessionless and would silently change the subject.
-        mode="legacy",
+        mode=mode,
+        sampling_callback=sampling_callback,
+        list_roots_callback=list_roots_callback,
         logging_callback=logging_callback,
         log_level=log_level,
         message_handler=message_handler,
@@ -397,7 +404,9 @@ def httpx_client_factory(
     transport = sse_client(f"{BASE_URL}/sse", httpx_client_factory=httpx_client_factory)
     async with Client(
         transport,
-        # SSE is a legacy-only transport; the modern path has no SSE story.
+        # A policy lock, not a capability one: the dual-era server loop behind build_sse_app
+        # would negotiate 2026 if probed, but SSE is the deprecated legacy transport and its
+        # clients run the handshake era by design.
         mode="legacy",
         read_timeout_seconds=read_timeout_seconds,
         sampling_callback=sampling_callback,

tests/interaction/_helpers.py

@@ -1,18 +1,38 @@
 """Shared helpers for the interaction suite.
 
-Keep this module small: it exists only for the recording transport used by the wire-level
-tests. Server fixtures and assertion helpers belong in the test that uses them.
+Keep this module small: it holds the recording transport used by the wire-level tests and the
+`tool_listing` handler factory. Servers and assertion helpers belong in the test that uses them.
 """
 
+from collections.abc import Awaitable, Callable
 from types import TracebackType
+from typing import Any
 
 import anyio
+from mcp_types import ListToolsResult, PaginatedRequestParams, Tool
 from typing_extensions import Self
 
 from mcp.client._transport import ReadStream, Transport, TransportStreams, WriteStream
+from mcp.server import ServerRequestContext
 from mcp.shared.message import SessionMessage
 
 
+def tool_listing(
+    *tools: Tool | str,
+) -> Callable[[ServerRequestContext[Any, Any], PaginatedRequestParams | None], Awaitable[ListToolsResult]]:
+    """An `on_list_tools` handler advertising `tools`; a bare name becomes an argument-less tool.
+
+    `Client.call_tool` lists tools once per connection to learn their output schemas, so a server
+    whose tools are called needs a tools/list handler even when the test never lists.
+    """
+    listed = [Tool(name=t, input_schema={"type": "object"}) if isinstance(t, str) else t for t in tools]
+
+    async def list_tools(ctx: ServerRequestContext[Any, Any], params: PaginatedRequestParams | None) -> ListToolsResult:
+        return ListToolsResult(tools=listed)
+
+    return list_tools
+
+
 class _RecordingReadStream:
     """Delegates to a read stream, appending every received message to a log."""