Address review feedback on claim construction and notification ordering

ResultClaim now rejects models that do not subclass Result at runtime
(the typing bound only constrains checked callers) and models whose
fields alias requestState or inputRequests, which the core result
surface types and would reject before the claim adapter runs. The
notification ordering contract is stated honestly: per-binding serial
delivery in dispatch order, with near-simultaneous notifications on
stream transports possibly dispatched out of wire order. The receipts
tutorial server now gates substitution on the client declaring the
extension, the stale custom-methods README caveat points at
NotificationBinding, and the capability-ad docstring no longer
overstates which identifiers drop.

Author: maxisbey

docs/advanced/extensions.md

@@ -151,7 +151,7 @@ A **client extension** is the same contract from the consuming side: a bundle of
 client-side behaviour behind one identifier. Pass instances to
 `Client(extensions=[...])` and call tools normally:
 
-```python title="client.py" hl_lines="66-68"
+```python title="client.py" hl_lines="67-69"
 --8<-- "docs_src/extensions/tutorial006.py"
 ```
 
@@ -161,8 +161,9 @@ shape** instead of a final result, and `Receipts` finishes it (here by redeeming
 receipt with a follow-up call) before `call_tool` returns. Nothing about the call
 site moves.
 
-Drop the extension and none of this exists: a `receipt` shape arriving at a client
-that didn't declare it fails validation, exactly as the spec requires for an
+Drop the extension and none of this exists: the server's gate refuses a client
+that did not declare it (error -32021), and a claimed shape from a server that
+skips the gate fails validation, exactly as the spec requires for an
 unrecognized `resultType`. Off by default, on both ends of the wire.
 
 To advertise an identifier with **no** client-side behaviour (the server gates on
@@ -180,7 +181,7 @@ client = Client(mcp, extensions=[advertise("com.example/search")])
 Subclass `ClientExtension` and override only what you need. Three contribution
 kinds, each with a default: `settings()`, `claims()`, and `notifications()`.
 
-```python title="client.py" hl_lines="18-19 43-44 46-47"
+```python title="client.py" hl_lines="18-19 44-45 47-48"
 --8<-- "docs_src/extensions/tutorial006.py"
 ```
 
@@ -205,7 +206,7 @@ def notifications(self) -> Sequence[NotificationBinding[Any]]:
     return [NotificationBinding(method="notifications/receipts", params_type=ReceiptEvent, handler=self.on_receipt)]
 ```
 
-The handler receives validated params, in arrival order. It observes; it cannot veto
+The handler receives validated params one at a time, in dispatch order. It observes; it cannot veto
 or reply.
 
 Two quiet rules. Claims are active on 2026-07-28 connections only, and the capability

docs_src/extensions/tutorial006.py

@@ -7,7 +7,7 @@
 from mcp.client import ClaimContext, ClientExtension, ResultClaim
 from mcp.server.context import CallNext, HandlerResult, ServerRequestContext
 from mcp.server.extension import Extension
-from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver import MCPServer, require_client_extension
 
 EXTENSION_ID = "com.example/receipts"
 
@@ -32,6 +32,7 @@ async def intercept_tool_call(
     ) -> HandlerResult:
         if params.name != "buy":
             return await call_next(ctx)
+        require_client_extension(ctx, EXTENSION_ID)
         return {"resultType": "receipt", "receiptToken": "r-117"}
 
 

examples/stories/custom_methods/README.md

@@ -34,10 +34,10 @@ uv run python -m stories.custom_methods.client --http
 ## Caveats
 
 - The TypeScript SDK's equivalent example also shows a custom server→client
-  **notification** (`acme/searchProgress`). The Python client currently drops
-  any notification whose method is not in the spec registry
-  (`ClientSession._on_notify` → `KeyError` → silent drop), and there is no
-  `set_notification_handler` analogue. That half is omitted here.
+  **notification** (`acme/searchProgress`). The Python client can observe
+  vendor notifications via `NotificationBinding` (see
+  `docs/advanced/extensions.md`). That half is omitted here because the
+  lowlevel server has no surface for emitting vendor notifications yet.
 
 ## Spec
 

src/mcp/client/extension.py

@@ -32,6 +32,9 @@
 _CLAIM_METHODS: Final[frozenset[str]] = frozenset({"tools/call"})
 """The closed set of verbs a claim may attach to; widen together with the `method` Literal."""
 
+_RESERVED_WIRE_ALIASES: Final[frozenset[str]] = frozenset({"requestState", "inputRequests"})
+"""Typed optional fields of the core result surface that pre-validates every inbound result."""
+
 ClaimedT = TypeVar("ClaimedT", bound=Result)
 NotifyParamsT = TypeVar("NotifyParamsT", bound=BaseModel)
 
@@ -66,8 +69,17 @@ def __post_init__(self) -> None:
             raise ValueError(f"claims attach to {sorted(_CLAIM_METHODS)} only; got method {self.method!r}")
         if self.result_type in CORE_RESULT_TYPES:
             raise ValueError(f"resultType {self.result_type!r} is core protocol vocabulary")
+        if Result not in self.model.__mro__:  # runtime guard; the ClaimedT bound only constrains checked callers
+            raise ValueError(f"{self.model.__name__} must subclass mcp_types.Result")
         if issubclass(self.model, CallToolResult | InputRequiredResult):
             raise ValueError("claim models must not subclass core result types")
+        for name, model_field in self.model.model_fields.items():
+            if (model_field.alias or name) in _RESERVED_WIRE_ALIASES:
+                raise ValueError(
+                    f"{self.model.__name__}.{name} aliases {model_field.alias or name!r}, a typed field "
+                    "of the core result surface; a colliding value would fail core validation before "
+                    "the claim adapter runs"
+                )
         field = self.model.model_fields.get("result_type")
         if field is None or get_args(field.annotation) != (self.result_type,):
             raise ValueError(f"{self.model.__name__}.result_type must be Literal[{self.result_type!r}]")
@@ -101,9 +113,11 @@ def __init__(self, result: Result) -> None:
 class NotificationBinding(Generic[NotifyParamsT]):
     """Deliver server notifications for `method` (the bare wire name) to `handler`.
 
-    Observation-only: validated params arrive in order through a bounded queue,
-    dropping the oldest with a warning on overflow. Methods the negotiated
-    version's core tables handle are never delivered to bindings.
+    Observation-only: validated params arrive one at a time per binding, in
+    dispatch order, through a bounded queue that drops the oldest with a warning
+    on overflow. Stream transports dispatch each notification independently, so
+    near-simultaneous notifications may be dispatched out of wire order. Methods
+    the negotiated version's core tables handle are never delivered to bindings.
     """
 
     method: str

src/mcp/client/session.py

@@ -505,7 +505,9 @@ async def send_notification(self, notification: types.ClientNotification) -> Non
     def _build_capabilities(self, version: str) -> types.ClientCapabilities:
         """Build the capability ad for a wire speaking `version`.
 
-        Identifiers with no active claim drop, so the client never advertises result shapes it would reject.
+        Claim-bearing identifiers whose claims are all inactive at `version` drop, so
+        the client never advertises result shapes it would reject; claim-less
+        identifiers always advertise.
         """
         extensions = self._extensions
         if extensions is not None and self._result_claims:

tests/client/test_extension.py

@@ -120,6 +120,34 @@ def test_claim_rejects_mismatched_result_type_literal() -> None:
     assert str(exc_info.value) == snapshot("_OtherTagResult.result_type must be Literal['task']")
 
 
+class _NotAResult(BaseModel):
+    result_type: Literal["plain"] = "plain"
+
+
+class _ReservedAliasResult(Result):
+    result_type: Literal["clash"] = "clash"
+    request_state: dict[str, Any] = {}
+
+
+def test_claim_rejects_model_not_subclassing_result() -> None:
+    """SDK-defined: a plain BaseModel cannot be a claim model; the session returns `Result` values."""
+    with pytest.raises(ValueError) as exc_info:
+        ResultClaim(result_type="plain", model=cast("type[Result]", _NotAResult), resolve=_resolve)
+
+    assert str(exc_info.value) == snapshot("_NotAResult must subclass mcp_types.Result")
+
+
+def test_claim_rejects_model_aliasing_core_surface_fields() -> None:
+    """SDK-defined: a field aliasing requestState or inputRequests would fail core pre-validation."""
+    with pytest.raises(ValueError) as exc_info:
+        ResultClaim(result_type="clash", model=_ReservedAliasResult, resolve=_resolve)
+
+    assert str(exc_info.value) == snapshot(
+        "_ReservedAliasResult.request_state aliases 'requestState', a typed field of the core "
+        "result surface; a colliding value would fail core validation before the claim adapter runs"
+    )
+
+
 def test_claim_rejects_method_outside_the_closed_verb_set() -> None:
     """SDK-defined: claims attach to `tools/call` only, even for values that dodge the static Literal gate."""
     with pytest.raises(ValueError) as exc_info:

tests/docs_src/test_extensions.py

@@ -5,7 +5,6 @@
 import pytest
 from inline_snapshot import snapshot
 from mcp_types import METHOD_NOT_FOUND, MISSING_REQUIRED_CLIENT_CAPABILITY, TextContent
-from pydantic import ValidationError
 
 from docs_src.extensions import (
     tutorial001,
@@ -111,11 +110,12 @@ async def test_the_receipts_client_program_runs_as_shown(capsys: pytest.CaptureF
     assert "goods for r-117" in capsys.readouterr().out
 
 
-async def test_a_claimed_shape_fails_validation_without_the_extension() -> None:
-    """The page's off-by-default claim: a client without `Receipts` rejects the `receipt` shape as invalid."""
+async def test_a_client_without_the_extension_is_refused_by_the_gate() -> None:
+    """The page's off-by-default claim: the server's capability gate refuses a non-declaring client."""
     async with Client(tutorial006.mcp) as client:
-        with pytest.raises(ValidationError):
+        with pytest.raises(MCPError) as exc_info:
             await client.call_tool("buy", {"item": "lamp"})
+    assert exc_info.value.code == MISSING_REQUIRED_CLIENT_CAPABILITY
 
 
 async def test_session_tier_allow_claimed_returns_the_raw_shape() -> None:

tests/interaction/_requirements.py

@@ -2403,6 +2403,11 @@ def __post_init__(self) -> None:
             "declared claims, never more)."
         ),
         added_in="2026-07-28",
+        note=(
+            "Known leniency: the monolith result surface still accepts an unknown tag when the payload "
+            "also parses as a complete core result (open result_type, extras ignored). Rejecting tags "
+            "outside core plus active claims is a tracked follow-up ruling."
+        ),
     ),
     "extensions:client:capability-ad:gates-server-behaviour": Requirement(
         source=f"{SPEC_2026_BASE_URL}/basic#resulttype",
@@ -2432,7 +2437,7 @@ def __post_init__(self) -> None:
         source=f"{SPEC_2026_BASE_URL}/basic#resulttype",
         behavior=(
             "A vendor server notification bound by a ClientExtension's NotificationBinding is validated "
-            "against the binding's params type and delivered to its handler in arrival order."
+            "against the binding's params type and delivered to its handler serially, in dispatch order."
         ),
         added_in="2026-07-28",
         deferred=(