Address review findings on the 2026-07-28 interaction coverage

Split the unknown-resource-URI requirement by era: the handshake-era entry
returns to the 2025 spec's -32002 wording with the SDK's era-agnostic -32602
recorded as a divergence and pinned on the 2025 cells, and a 2026 successor
carries the SEP-2164 -32602 rule. Narrow six behaviour or note sentences to
what their tests prove (the x-mcp-header type allow-list, -32022 fallback
when the supported list names a handshake version, body-derived headers, the
listen close stamp, iss comparison against the parsed issuer, X-Accel-Buffering
on the handshake transports, the directionality rule with notifications).
Bound the rounds-cap test with fail_after, pass an unannotated argument so the
Mcp-Param exclusion is actually exercised, seed the no-token-reuse test with an
expired token so it guards the discard ordering, qualify the lazy-SSE docstring
to the deferral window, and type three request-header handlers for the newer
starlette Request generic.

No-Verification-Needed: test-only change

Author: maxisbey

tests/interaction/_requirements.py

@@ -435,7 +435,9 @@ def __post_init__(self) -> None:
         source=f"{SPEC_2026_BASE_URL}/basic/versioning#protocol-version-negotiation",
         behavior=(
             "When server/discover returns -32022 UnsupportedProtocolVersion, the client retries once with "
-            "the intersection of error.data.supported and its own modern versions; an empty intersection raises."
+            "the intersection of error.data.supported and its own modern versions; an empty intersection raises "
+            "when error.data.supported names no handshake-era version; a list that names one falls back to the "
+            "initialize handshake."
         ),
         added_in="2026-07-28",
         supersedes=("lifecycle:version:downgrade", "lifecycle:version:reject-unsupported"),
@@ -529,8 +531,9 @@ def __post_init__(self) -> None:
     "lifecycle:discover:fallback-method-not-found": Requirement(
         source=f"{SPEC_2026_BASE_URL}/basic/transports/stdio#backward-compatibility",
         behavior=(
-            "When server/discover is rejected with a JSON-RPC error other than -32022 (see "
-            "lifecycle:discover:retry-on-32022), or with a bare HTTP 4xx, an auto-negotiating client falls back to "
+            "When server/discover is rejected with a JSON-RPC error other than -32022 (which retries, raises, or "
+            "falls back to the handshake according to the supported list; see lifecycle:discover:retry-on-32022), "
+            "or with a bare HTTP 4xx, an auto-negotiating client falls back to "
             "the legacy initialize handshake and connects at a handshake-era version; the fallback is not keyed to "
             "specific codes because legacy servers reject the probe with various codes."
         ),
@@ -622,11 +625,9 @@ def __post_init__(self) -> None:
     "protocol:directionality:no-client-responses": Requirement(
         source=f"{SPEC_2026_BASE_URL}/basic/patterns",
         behavior=(
-            "A 2026-07-28 wire trace contains no server-initiated JSON-RPC requests and no "
-            "client-sent JSON-RPC responses: every client-to-server frame is a request and every "
-            "server-to-client frame is a response or a request-scoped notification, never a request, even "
-            "across a multi-round-trip exchange that at 2025-11-25 was a server-initiated request answered "
-            "by the client."
+            "A 2026-07-28 wire trace contains no server-initiated JSON-RPC requests and no client-sent "
+            "JSON-RPC responses; notifications flow in both directions. This holds even across a "
+            "multi-round-trip exchange that at 2025-11-25 was a server-initiated request answered by the client."
         ),
         added_in="2026-07-28",
         note=(
@@ -1337,8 +1338,8 @@ def __post_init__(self) -> None:
     "client:x-mcp-header:invalid-definition-rejected:non-primitive": Requirement(
         source=f"{SPEC_2026_BASE_URL}/basic/transports/streamable-http#schema-extension",
         behavior=(
-            "An x-mcp-header annotation on a non-primitive property (e.g. type number, which "
-            "the spec explicitly forbids) makes the tool definition invalid and the modern "
+            "An x-mcp-header annotation is permitted only on integer, string or boolean properties; a tool "
+            "that annotates any other type (for example number) has an invalid definition and the modern "
             "client excludes it from tools/list."
         ),
         added_in="2026-07-28",
@@ -1646,11 +1647,26 @@ def __post_init__(self) -> None:
         behavior="resources/read returns text contents carrying uri, mimeType, and the text.",
     ),
     "resources:read:unknown-uri": Requirement(
+        source=f"{SPEC_BASE_URL}/server/resources#error-handling",
+        behavior="resources/read for an unknown URI returns JSON-RPC error -32002 (resource not found).",
+        divergence=Divergence(
+            note=(
+                "The server answers -32602 (invalid params, URI in error.data) on handshake-era connections too; "
+                "when a 2025-era -32002 arm lands, re-pin the 2025 cells to -32002 and delete this divergence."
+            ),
+        ),
+        note="replaced at 2026-07-28 (SEP-2164): unknown URIs are Invalid params (-32602).",
+        removed_in="2026-07-28",
+        superseded_by="resources:read:unknown-uri-invalid-params",
+    ),
+    "resources:read:unknown-uri-invalid-params": Requirement(
         source=f"{SPEC_2026_BASE_URL}/server/resources#error-handling",
         behavior=(
             "resources/read for a URI matching no registered resource returns JSON-RPC error -32602 "
             "(invalid params) with the requested URI in error.data, per SEP-2164."
         ),
+        added_in="2026-07-28",
+        supersedes=("resources:read:unknown-uri",),
     ),
     "resources:subscribe": Requirement(
         source=f"{SPEC_BASE_URL}/server/resources#subscriptions",
@@ -1719,14 +1735,14 @@ def __post_init__(self) -> None:
         source=f"{SPEC_2026_BASE_URL}/basic/patterns/subscriptions#graceful-closure",
         behavior=(
             "A server ending a subscription on its own initiative answers the original "
-            "subscriptions/listen request with an empty result (stamped with the subscriptionId) before "
-            "closing the stream, so the client can distinguish a graceful close from a transport drop."
+            "subscriptions/listen request with an empty result before closing the stream, so the "
+            "client can distinguish a graceful close from a transport drop."
         ),
         added_in="2026-07-28",
         note=(
             "The deliberate close is a lowlevel-Server surface: ListenHandler.close() ends every open "
-            "stream with the stamped empty result; MCPServer registers its ListenHandler by default "
-            "and exposes no teardown handle."
+            "stream with the empty result, which carries the subscriptionId stamp the bound test does not "
+            "observe. MCPServer registers its ListenHandler by default and exposes no teardown handle."
         ),
     ),
     "subscriptions:listen:notification-stamped": Requirement(
@@ -4658,8 +4674,9 @@ def __post_init__(self) -> None:
         added_in="2026-07-28",
         transports=("streamable-http",),
         note=(
-            "Only observable over streamable HTTP. Scoped to the 2026-07-28 entry, where the SHOULD is new; the "
-            "legacy SSE and streamable-HTTP transports send no such header and are not bound by this entry."
+            "Only observable over streamable HTTP. Scoped to the 2026-07-28 entry, where the SHOULD is stated; "
+            "the handshake-era transports also emit the header through their SSE response class but are not "
+            "bound by this entry."
         ),
     ),
     "hosting:http:modern:header-name-case-insensitive": Requirement(
@@ -4954,12 +4971,16 @@ def __post_init__(self) -> None:
     "client-transport:http:body-derived-headers": Requirement(
         source=f"{SPEC_2026_BASE_URL}/basic/transports/streamable-http#standard-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."
+            "An envelope-bearing request body yields MCP-Protocol-Version, Mcp-Method and (for tools/call) "
+            "Mcp-Name headers on the outgoing HTTP request, derived from the body at the transport seam."
         ),
         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.",
+        note=(
+            "Only observable over streamable HTTP. Handshake-era requests carry no envelope; their "
+            "MCP-Protocol-Version header is stamped from the negotiated session instead "
+            "(client-transport:http:protocol-version-header)."
+        ),
     ),
     "client-transport:http:mcp-name-base64-sentinel": Requirement(
         source=f"{SPEC_2026_BASE_URL}/basic/transports/streamable-http#standard-request-headers",
@@ -5450,16 +5471,15 @@ def __post_init__(self) -> None:
     "client-auth:iss:no-normalize": Requirement(
         source=f"{SPEC_2026_BASE_URL}/basic/authorization#authorization-response-validation",
         behavior=(
-            "The iss comparison is simple string comparison (RFC 3986 section 6.2.1): a value "
-            "differing from the recorded issuer only by a trailing slash is rejected as a "
-            "mismatch -- no scheme or host case folding, default-port elision, trailing-slash, "
-            "or percent-encoding normalization is applied before comparison."
+            "The iss comparison is a plain string comparison against the recorded issuer (RFC 3986 "
+            "section 6.2.1): a callback iss differing only by a trailing slash is rejected as a mismatch."
         ),
         added_in="2026-07-28",
         transports=("streamable-http",),
         note=(
-            "OAuth is HTTP-only. The comparison is a single string inequality; the test pins the "
-            "trailing-slash arm as the representative normalization class."
+            "OAuth is HTTP-only. The recorded issuer is the parsed metadata URL, so scheme and host case "
+            "and default ports are already normalized when the metadata is read; trailing-slash and "
+            "percent-encoding differences are not, and the test pins the trailing-slash arm."
         ),
     ),
     "client-auth:iss:supported-missing-reject": Requirement(

tests/interaction/auth/test_lifecycle.py

@@ -268,7 +268,7 @@ async def test_tokens_from_the_previous_authorization_server_are_never_replayed_
     storage.tokens = OAuthToken(
         access_token="stale-access-token",
         token_type="Bearer",
-        expires_in=3600,
+        expires_in=-3600,
         scope="mcp",
         refresh_token="stale-refresh-token",
     )

tests/interaction/lowlevel/test_mrtr.py

@@ -227,8 +227,9 @@ async def answer_again(context: ClientRequestContext, params: types.ElicitReques
     async with Client(
         server, mode=LATEST_MODERN_VERSION, elicitation_callback=answer_again, input_required_max_rounds=2
     ) as client:
-        # Raised inside the block: Client.__aexit__ would wrap the error in an ExceptionGroup.
-        with pytest.raises(InputRequiredRoundsExceededError) as exc_info:
+        # Raised inside the block: Client.__aexit__ would wrap the error in an ExceptionGroup. The
+        # fail_after is the only guard against an unbounded retry loop if the cap stops being enforced.
+        with anyio.fail_after(5), pytest.raises(InputRequiredRoundsExceededError) as exc_info:
             await client.call_tool("never-done", {})
 
     assert exc_info.value.max_rounds == 2

tests/interaction/mcpserver/test_resources.py

@@ -113,17 +113,37 @@ def user_profile(user_id: str) -> str:
     )
 
 
-@requirement("resources:read:unknown-uri")
-async def test_read_unknown_uri_is_error(connect: Connect) -> None:
-    """Reading a URI that matches no registered resource fails with -32602 and the URI in data (SEP-2164)."""
+def _library_with_one_resource() -> MCPServer:
+    """A server with one registered resource at config://app; the unknown-URI tests read a different URI."""
     mcp = MCPServer("library")
 
     @mcp.resource("config://app")
     def app_config() -> str:
-        """A registered resource; the test reads a different URI."""
         raise NotImplementedError
 
-    async with connect(mcp) as client:
+    return mcp
+
+
+@requirement("resources:read:unknown-uri-invalid-params")
+async def test_read_unknown_uri_is_invalid_params(connect: Connect) -> None:
+    """Reading a URI that matches no registered resource fails with -32602 and the URI in data (SEP-2164)."""
+    async with connect(_library_with_one_resource()) as client:
+        with pytest.raises(MCPError) as exc_info:
+            await client.read_resource("config://missing")
+
+    assert exc_info.value.error == snapshot(
+        ErrorData(code=-32602, message="Unknown resource: config://missing", data={"uri": "config://missing"})
+    )
+
+
+@requirement("resources:read:unknown-uri")
+async def test_read_unknown_uri_on_handshake_era_is_invalid_params_too(connect: Connect) -> None:
+    """Reading a URI that matches no registered resource fails with -32602 on handshake-era connections as well.
+
+    On 2025-11-25 cells this pins the divergence recorded on resources:read:unknown-uri: the spec's
+    code there is -32002. When a 2025-era -32002 arm lands, re-pin this assertion to -32002.
+    """
+    async with connect(_library_with_one_resource()) as client:
         with pytest.raises(MCPError) as exc_info:
             await client.read_resource("config://missing")
 

tests/interaction/transports/test_hosting_http_modern.py

@@ -134,7 +134,8 @@ async def test_modern_tools_call_returns_result_type_complete_without_initialize
     result), and the server identifies itself via the result `_meta` serverInfo stamp. Asserted at
     the wire because the SDK client never surfaces `resultType` and because the absence of any
     prior request on the connection is the assertion. The `application/json` Content-Type also
-    pins the lazy-upgrade JSON arm: a silent handler never commits SSE.
+    pins the lazy-upgrade JSON arm: a silent handler that completes within the deferral window
+    never commits SSE.
     """
     body = {
         "jsonrpc": "2.0",
@@ -503,7 +504,9 @@ def _custom_header_server(*, on_call: Callable[[tuple[Headers, dict[str, Any] |
     async def list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
         return ListToolsResult(tools=[_CUSTOM_HEADER_TOOL], ttl_ms=0, cache_scope="public")
 
-    async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
+    async def call_tool(
+        ctx: ServerRequestContext[Any, StarletteRequest], params: CallToolRequestParams
+    ) -> CallToolResult:
         if on_call is not None:
             assert isinstance(ctx.request, StarletteRequest)
             on_call((ctx.request.headers, params.arguments))
@@ -533,9 +536,12 @@ async def on_request(request: httpx2.Request) -> None:
             client_via_http(http, mode=LATEST_MODERN_VERSION) as client,
         ):
             await client.list_tools()
-            await client.call_tool("run", {"region": "us-west1", "priority": 42, "verbose": False, "note": "héllo"})
+            await client.call_tool(
+                "run", {"region": "us-west1", "priority": 42, "verbose": False, "note": "héllo", "query": "status"}
+            )
 
     call = next(r for r in requests if json.loads(r.content)["method"] == "tools/call")
+    # Exact set: the unannotated `query` is passed but yields no header.
     assert {k: v for k, v in call.headers.items() if k.startswith("mcp-param-")} == snapshot(
         {
             "mcp-param-region": "us-west1",
@@ -546,7 +552,7 @@ async def on_request(request: httpx2.Request) -> None:
     )
     # Mirroring is additive: the arguments are unchanged in the body.
     assert json.loads(call.content)["params"]["arguments"] == snapshot(
-        {"region": "us-west1", "priority": 42, "verbose": False, "note": "héllo"}
+        {"region": "us-west1", "priority": 42, "verbose": False, "note": "héllo", "query": "status"}
     )
 
 
@@ -681,7 +687,9 @@ async def test_non_header_safe_tool_name_is_carried_as_base64_sentinel_mcp_name(
     """
     seen: list[str] = []
 
-    async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult:
+    async def call_tool(
+        ctx: ServerRequestContext[Any, StarletteRequest], params: CallToolRequestParams
+    ) -> CallToolResult:
         assert params.name == "hëllo"
         assert isinstance(ctx.request, StarletteRequest)
         seen.append(ctx.request.headers["mcp-name"])
@@ -1088,7 +1096,9 @@ async def test_modern_client_non_ascii_prompt_name_round_trips_via_sentinel_enco
     """
     seen: list[str] = []
 
-    async def get_prompt(ctx: ServerRequestContext, params: GetPromptRequestParams) -> GetPromptResult:
+    async def get_prompt(
+        ctx: ServerRequestContext[Any, StarletteRequest], params: GetPromptRequestParams
+    ) -> GetPromptResult:
         assert params.name == "héllo"
         assert isinstance(ctx.request, StarletteRequest)
         seen.append(ctx.request.headers["mcp-name"])