Add a client extension API (#3034)

tests/client/test_client_extensions.py

@@ -0,0 +1,573 @@
+"""`Client` + `ClientExtension` integration: extension declarations fold into the session at
+construction, and `call_tool` drives claim resolvers transparently against real `MCPServer`s.
+"""
+
+import logging
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any, Literal, cast
+
+import anyio
+import mcp_types as types
+import pytest
+from inline_snapshot import snapshot
+from mcp_types import CallToolResult, Result, TextContent
+from mcp_types.version import LATEST_MODERN_VERSION
+from pydantic import BaseModel
+from typing_extensions import assert_type
+
+from mcp.client import ClaimContext, ClientExtension, NotificationBinding, ResultClaim, advertise
+from mcp.client.client import Client
+from mcp.client.session import ClientRequestContext, _CallToolResultAdapter
+from mcp.server import Server, ServerRequestContext
+from mcp.server.context import CallNext, HandlerResult
+from mcp.server.extension import Extension
+from mcp.server.mcpserver import Context, MCPServer
+
+pytestmark = pytest.mark.anyio
+
+_VOUCHER_EXT = "com.example/voucher"
+_RIVAL_EXT = "com.example/rival"
+
+_NAME_SCHEMA = {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}
+
+
+def _name_elicitation() -> types.ElicitRequest:
+    return types.ElicitRequest(
+        params=types.ElicitRequestFormParams(message="What is your name?", requested_schema=_NAME_SCHEMA)
+    )
+
+
+class VoucherResult(Result):
+    """The claimed `tools/call` shape, tagged `voucher`, carrying a vendor top-level field."""
+
+    result_type: Literal["voucher"] = "voucher"
+    voucher_code: str | None = None
+
+
+_Resolver = Callable[[VoucherResult, ClaimContext], Awaitable[CallToolResult]]
+
+
+class _VoucherExtension(ClientExtension):
+    """Client half: claims the `voucher` tag with the supplied resolver."""
+
+    identifier = _VOUCHER_EXT
+
+    def __init__(self, resolve: _Resolver) -> None:
+        self._resolve = resolve
+
+    def claims(self) -> Sequence[ResultClaim[Any]]:
+        return [ResultClaim(result_type="voucher", model=VoucherResult, resolve=self._resolve)]
+
+
+class _VoucherIssuer(Extension):
+    """Server half: rewrites every `tools/call` result into the vendor-claimed shape."""
+
+    identifier = _VOUCHER_EXT
+
+    async def intercept_tool_call(
+        self, params: types.CallToolRequestParams, ctx: ServerRequestContext[Any, Any], call_next: CallNext
+    ) -> HandlerResult:
+        return {"resultType": "voucher", "voucherCode": "v-42"}
+
+
+class _TwoRoundVoucherIssuer(Extension):
+    """Server half: demands input on the first round, then issues the claimed shape."""
+
+    identifier = _VOUCHER_EXT
+
+    async def intercept_tool_call(
+        self, params: types.CallToolRequestParams, ctx: ServerRequestContext[Any, Any], call_next: CallNext
+    ) -> HandlerResult:
+        if params.input_responses is None:
+            return types.InputRequiredResult(input_requests={"user_name": _name_elicitation()})
+        return {"resultType": "voucher", "voucherCode": "after-input"}
+
+
+def _voucher_server(issuer: Extension | None = None) -> MCPServer:
+    """An `MCPServer` whose `issue` tool the server extension rewrites into the claimed shape."""
+    server = MCPServer("vouchers", extensions=[issuer if issuer is not None else _VoucherIssuer()])
+
+    @server.tool()
+    def issue() -> CallToolResult:
+        """Issue a voucher."""
+        raise NotImplementedError  # the server extension short-circuits before the tool runs
+
+    return server
+
+
+def _structured_voucher_server() -> MCPServer:
+    """Like `_voucher_server`, but `issue` declares an output schema (`-> str`)."""
+    server = MCPServer("vouchers", extensions=[_VoucherIssuer()])
+
+    @server.tool()
+    def issue() -> str:
+        """Issue a voucher."""
+        raise NotImplementedError  # the server extension short-circuits before the tool runs
+
+    return server
+
+
+def _add_server() -> MCPServer:
+    """A plain claim-less server with one ordinary tool."""
+    server = MCPServer("plain")
+
+    @server.tool()
+    def add(a: int, b: int) -> int:
+        """Add two integers."""
+        return a + b
+
+    return server
+
+
+# Construction-time validation
+
+
+class _CouponResult(Result):
+    result_type: Literal["coupon"] = "coupon"
+
+
+async def _unreachable_coupon_resolve(claimed: _CouponResult, ctx: ClaimContext) -> CallToolResult:
+    raise NotImplementedError  # the wrong resolver for a voucher; must never run
+
+
+class _CouponExtension(ClientExtension):
+    identifier = "com.example/coupons"
+
+    def claims(self) -> Sequence[ResultClaim[Any]]:
+        return [ResultClaim(result_type="coupon", model=_CouponResult, resolve=_unreachable_coupon_resolve)]
+
+
+class _SelfConflictingClaims(ClientExtension):
+    identifier = "com.example/twice"
+
+    def claims(self) -> Sequence[ResultClaim[Any]]:
+        return [
+            ResultClaim(result_type="twice", model=_TwiceResult, resolve=_unreachable_twice_resolve),
+            ResultClaim(result_type="twice", model=_TwiceResult, resolve=_unreachable_twice_resolve),
+        ]
+
+
+class _TwiceResult(Result):
+    result_type: Literal["twice"] = "twice"
+
+
+async def _unreachable_twice_resolve(claimed: _TwiceResult, ctx: ClaimContext) -> CallToolResult:
+    raise NotImplementedError
+
+
+def test_mapping_extensions_get_the_migration_error() -> None:
+    """SDK-defined: the replaced dict form fails with a message naming the new shape."""
+    with pytest.raises(TypeError) as exc_info:
+        Client(_add_server(), extensions=cast("Sequence[ClientExtension]", {"com.example/ui": {}}))
+
+    assert str(exc_info.value) == snapshot(
+        "extensions= takes a sequence of ClientExtension instances. The mapping form was "
+        "replaced: use advertise(identifier, settings) for advertise-only entries"
+    )
+
+
+def test_one_extension_claiming_a_tag_twice_reads_as_one_owner() -> None:
+    """SDK-defined: a self-conflict names the one extension once, not as a pair."""
+    with pytest.raises(ValueError) as exc_info:
+        Client(_add_server(), extensions=[_SelfConflictingClaims()])
+
+    assert str(exc_info.value) == snapshot(
+        "extension 'com.example/twice' claims resultType 'twice'; a wire tag can have only one resolver"
+    )
+
+
+def test_bare_extension_instance_is_rejected_with_the_fix_named() -> None:
+    """SDK-defined: an instance whose class never set `identifier` fails construction naming the type and the fix."""
+    with pytest.raises(ValueError) as exc_info:
+        Client(_add_server(), extensions=[ClientExtension()])
+
+    assert str(exc_info.value) == snapshot(
+        "ClientExtension has no `identifier`; a ClientExtension must set the `identifier` "
+        "class attribute (or assign one in `__init__`) before it can be used"
+    )
+
+
+class _SelfAssignedBadId(ClientExtension):
+    """Assigns a malformed identifier in `__init__`, invisible at class definition."""
+
+    def __init__(self) -> None:
+        self.identifier = "not-prefixed"
+
+
+def test_invalid_per_instance_identifier_raises_the_validators_error() -> None:
+    """SDK-defined: per-instance identifiers are validated when the Client consumes the extension."""
+    with pytest.raises(TypeError) as exc_info:
+        Client(_add_server(), extensions=[_SelfAssignedBadId()])
+
+    assert str(exc_info.value) == snapshot(
+        "_SelfAssignedBadId.identifier must be a `vendor-prefix/name` string "
+        "(reverse-DNS prefix required), got 'not-prefixed'"
+    )
+
+
+def test_duplicate_extension_identifiers_are_rejected_naming_the_identifier() -> None:
+    """SDK-defined: one identifier cannot appear twice across the extensions sequence."""
+    with pytest.raises(ValueError) as exc_info:
+        Client(_add_server(), extensions=[advertise(_VOUCHER_EXT), advertise(_VOUCHER_EXT, {"a": 1})])
+
+    assert str(exc_info.value) == snapshot("extension identifier 'com.example/voucher' is passed more than once")
+
+
+async def _unreachable_resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
+    raise NotImplementedError
+
+
+class _RivalVoucherExtension(ClientExtension):
+    identifier = _RIVAL_EXT
+
+    def claims(self) -> Sequence[ResultClaim[Any]]:
+        return [ResultClaim(result_type="voucher", model=VoucherResult, resolve=_unreachable_resolve)]
+
+
+def test_conflicting_claims_across_extensions_name_both_owners() -> None:
+    """SDK-defined: two extensions claiming the same tag fail at construction with both owners named."""
+    with pytest.raises(ValueError) as exc_info:
+        Client(_add_server(), extensions=[_VoucherExtension(_unreachable_resolve), _RivalVoucherExtension()])
+
+    assert str(exc_info.value) == snapshot(
+        "extensions 'com.example/voucher' and 'com.example/rival' both claim resultType "
+        "'voucher'; a wire tag can have only one resolver"
+    )
+
+
+class _EventParams(BaseModel):
+    seq: int
+
+
+async def _unreachable_handler(params: _EventParams) -> None:
+    raise NotImplementedError
+
+
+class _ObserverA(ClientExtension):
+    identifier = "com.example/observer-a"
+
+    def notifications(self) -> Sequence[NotificationBinding[Any]]:
+        return [
+            NotificationBinding(
+                method="notifications/vendor/event", params_type=_EventParams, handler=_unreachable_handler
+            )
+        ]
+
+
+class _ObserverB(ClientExtension):
+    identifier = "com.example/observer-b"
+
+    def notifications(self) -> Sequence[NotificationBinding[Any]]:
+        return [
+            NotificationBinding(
+                method="notifications/vendor/event", params_type=_EventParams, handler=_unreachable_handler
+            )
+        ]
+
+
+def test_conflicting_notification_bindings_name_both_owners() -> None:
+    """SDK-defined: two extensions binding the same notification method fail with both owners named."""
+    with pytest.raises(ValueError) as exc_info:
+        Client(_add_server(), extensions=[_ObserverA(), _ObserverB()])
+
+    assert str(exc_info.value) == snapshot(
+        "extensions 'com.example/observer-a' and 'com.example/observer-b' both bind "
+        "notification method 'notifications/vendor/event'; a method can have only one observer"
+    )
+
+
+# settings() consumption
+
+
+class _CountedResult(Result):
+    result_type: Literal["counted"] = "counted"
+
+
+async def _unreachable_counted_resolve(claimed: _CountedResult, ctx: ClaimContext) -> CallToolResult:
+    raise NotImplementedError
+
+
+class _CountingSettings(ClientExtension):
+    identifier = "com.example/counted"
+
+    def __init__(self) -> None:
+        self.reads = 0
+        self.claims_reads = 0
+        self.notifications_reads = 0
+
+    def settings(self) -> dict[str, Any]:
+        self.reads += 1
+        return {"read": self.reads}
+
+    def claims(self) -> Sequence[ResultClaim[Any]]:
+        self.claims_reads += 1
+        return [ResultClaim(result_type="counted", model=_CountedResult, resolve=_unreachable_counted_resolve)]
+
+    def notifications(self) -> Sequence[NotificationBinding[Any]]:
+        self.notifications_reads += 1
+        return [
+            NotificationBinding(method="notifications/counted", params_type=_EventParams, handler=_unreachable_handler)
+        ]
+
+
+async def test_declarations_are_read_exactly_once_at_construction() -> None:
+    """SDK-defined: each declaration method is read exactly once, at Client construction, never again."""
+    extension = _CountingSettings()
+    client = Client(_add_server(), extensions=[extension])
+    assert (extension.reads, extension.claims_reads, extension.notifications_reads) == (1, 1, 1)
+
+    with anyio.fail_after(5):
+        async with client:
+            await client.call_tool("add", {"a": 1, "b": 2})
+            await client.call_tool("add", {"a": 3, "b": 4})
+
+    assert (extension.reads, extension.claims_reads, extension.notifications_reads) == (1, 1, 1)
+
+
+async def test_settings_dict_is_held_by_reference_not_copied() -> None:
+    """SDK-defined: the settings dict is held by reference, so mutating it before connect changes the ad."""
+    observed: list[dict[str, dict[str, Any]] | None] = []
+
+    async def call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> CallToolResult:
+        assert params.name == "probe"
+        assert ctx.session.client_params is not None
+        observed.append(ctx.session.client_params.capabilities.extensions)
+        return CallToolResult(content=[])
+
+    async def list_tools(
+        ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
+    ) -> types.ListToolsResult:
+        return types.ListToolsResult(tools=[types.Tool(name="probe", input_schema={"type": "object"})])
+
+    server = Server("probe", on_call_tool=call_tool, on_list_tools=list_tools)
+    settings = {"tier": "bronze"}
+    client = Client(server, extensions=[advertise("com.example/loyalty", settings)])
+    settings["tier"] = "gold"
+
+    with anyio.fail_after(5):
+        async with client:
+            await client.call_tool("probe", {})
+
+    assert observed == [{"com.example/loyalty": {"tier": "gold"}}]
+
+
+# extensions=None stays byte-identical
+
+
+@pytest.mark.parametrize("extensions", [None, ()], ids=["none", "empty"])
+async def test_no_extensions_keeps_tools_call_parsing_byte_identical(
+    extensions: Sequence[ClientExtension] | None,
+) -> None:
+    """SDK-defined: `extensions=None` and an empty sequence leave the session exactly as a claim-less client's."""
+    with anyio.fail_after(5):
+        async with Client(_add_server(), extensions=extensions) as client:
+            assert client.session._call_tool_adapter is _CallToolResultAdapter
+            result = await client.call_tool("add", {"a": 1, "b": 2})
+
+    assert result.structured_content == {"result": 3}
+
+
+# The transparent claim path
+
+
+async def test_claimed_result_resolves_transparently_to_the_resolvers_result() -> None:
+    """A claimed shape never surfaces: the resolver gets the parsed model and `call_tool` returns its product."""
+    received: list[VoucherResult] = []
+    produced: list[CallToolResult] = []
+
+    async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
+        received.append(claimed)
+        product = CallToolResult(content=[TextContent(text=f"honored {claimed.voucher_code}")])
+        produced.append(product)
+        return product
+
+    with anyio.fail_after(5):
+        async with Client(_voucher_server(), extensions=[_VoucherExtension(resolve)]) as client:
+            result = await client.call_tool("issue", {})
+            assert_type(result, CallToolResult)
+
+    assert [claimed.voucher_code for claimed in received] == ["v-42"]
+    assert result is produced[0]
+    assert result.content == [TextContent(text="honored v-42")]
+
+
+async def test_claimed_shape_routes_to_its_owning_extensions_resolver() -> None:
+    """With two claim-bearing extensions registered, the parsed shape runs its owner's resolver only."""
+    received: list[VoucherResult] = []
+
+    async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
+        received.append(claimed)
+        return CallToolResult(content=[TextContent(text="routed")])
+
+    extensions = [_CouponExtension(), _VoucherExtension(resolve)]
+    with anyio.fail_after(5):
+        async with Client(_voucher_server(), extensions=extensions) as client:
+            result = await client.call_tool("issue", {})
+
+    assert [claimed.voucher_code for claimed in received] == ["v-42"]
+    assert result.content == [TextContent(text="routed")]
+
+
+async def test_resolver_product_gets_the_direct_paths_output_schema_revalidation() -> None:
+    """The resolver's product is revalidated against the tool's output schema exactly like a direct result."""
+
+    async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
+        return CallToolResult(content=[TextContent(text="unstructured")])
+
+    async with Client(_structured_voucher_server(), extensions=[_VoucherExtension(resolve)]) as client:
+        with anyio.fail_after(5), pytest.raises(RuntimeError) as exc_info:
+            await client.call_tool("issue", {})
+
+    assert str(exc_info.value) == snapshot("Tool issue has an output schema but did not return structured content")
+
+
+async def test_resolver_error_result_is_returned_not_raised() -> None:
+    """An `isError` resolver product skips output-schema revalidation and comes back as-is."""
+
+    async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
+        return CallToolResult(content=[TextContent(text="voucher printer on fire")], is_error=True)
+
+    with anyio.fail_after(5):
+        async with Client(_structured_voucher_server(), extensions=[_VoucherExtension(resolve)]) as client:
+            result = await client.call_tool("issue", {})
+
+    assert result.is_error
+    assert result.content == [TextContent(text="voucher printer on fire")]
+
+
+async def test_resolver_receives_the_calls_claim_context() -> None:
+    """`ClaimContext` carries the client's own session object, the tool name, and the per-call read timeout."""
+    contexts: list[ClaimContext] = []
+
+    async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
+        contexts.append(ctx)
+        return CallToolResult(content=[])
+
+    with anyio.fail_after(5):
+        async with Client(_voucher_server(), extensions=[_VoucherExtension(resolve)]) as client:
+            await client.call_tool("issue", {}, read_timeout_seconds=7.0)
+            [ctx] = contexts
+            assert ctx.session is client.session
+
+    assert ctx.tool_name == "issue"
+    assert ctx.read_timeout_seconds == 7.0
+
+
+class _VoucherRefused(Exception):
+    """Extension-owned error vocabulary."""
+
+
+async def test_resolver_exception_propagates_untouched() -> None:
+    """A resolver exception reaches the `call_tool` caller as the very object raised, unwrapped."""
+    refusal = _VoucherRefused("the voucher is refused")
+
+    async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
+        raise refusal
+
+    async with Client(_voucher_server(), extensions=[_VoucherExtension(resolve)]) as client:
+        with anyio.fail_after(5), pytest.raises(_VoucherRefused) as exc_info:
+            await client.call_tool("issue", {})
+
+    assert exc_info.value is refusal
+
+
+# Unclaimed results with extensions present
+
+
+async def test_unclaimed_result_flows_through_unchanged_with_extensions_present() -> None:
+    """An ordinary `CallToolResult` is untouched by the claim machinery; the resolver never runs."""
+
+    async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
+        raise NotImplementedError  # this server never produces a claimed shape
+
+    with anyio.fail_after(5):
+        async with Client(_add_server(), extensions=[_VoucherExtension(resolve)]) as client:
+            result = await client.call_tool("add", {"a": 1, "b": 2})
+
+    assert result.structured_content == {"result": 3}
+
+
+async def test_input_required_then_plain_result_keeps_the_auto_loop_working() -> None:
+    """With a claim-bearing extension present, the input_required auto loop on an unclaimed tool is unchanged."""
+    server = MCPServer("mrtr")
+
+    @server.tool()
+    async def greet(ctx: Context) -> str | types.InputRequiredResult:
+        responses = ctx.input_responses
+        if responses and "user_name" in responses:
+            answer = responses["user_name"]
+            assert isinstance(answer, types.ElicitResult)
+            assert answer.content is not None
+            return f"Hello, {answer.content['name']}!"
+        return types.InputRequiredResult(input_requests={"user_name": _name_elicitation()})
+
+    async def elicitation_callback(
+        context: ClientRequestContext, params: types.ElicitRequestParams
+    ) -> types.ElicitResult | types.ErrorData:
+        return types.ElicitResult(action="accept", content={"name": "Ada"})
+
+    async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
+        raise NotImplementedError  # this server never produces a claimed shape
+
+    with anyio.fail_after(5):
+        async with Client(
+            server, elicitation_callback=elicitation_callback, extensions=[_VoucherExtension(resolve)]
+        ) as client:
+            result = await client.call_tool("greet")
+
+    assert result.content == [TextContent(text="Hello, Ada!")]
+
+
+# The multi-round-trip + claimed interplay
+
+
+async def test_input_required_then_claimed_result_on_retry_resolves_transparently() -> None:
+    """A call that demands input first and returns a claimed shape on the retry still resolves transparently."""
+    prompted: list[str] = []
+    received: list[VoucherResult] = []
+
+    async def elicitation_callback(
+        context: ClientRequestContext, params: types.ElicitRequestParams
+    ) -> types.ElicitResult | types.ErrorData:
+        assert isinstance(params, types.ElicitRequestFormParams)
+        prompted.append(params.message)
+        return types.ElicitResult(action="accept", content={"name": "Ada"})
+
+    async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
+        received.append(claimed)
+        return CallToolResult(content=[TextContent(text=f"honored {claimed.voucher_code}")])
+
+    server = _voucher_server(issuer=_TwoRoundVoucherIssuer())
+    with anyio.fail_after(5):
+        async with Client(
+            server, elicitation_callback=elicitation_callback, extensions=[_VoucherExtension(resolve)]
+        ) as client:
+            result = await client.call_tool("issue", {})
+
+    assert prompted == ["What is your name?"]
+    assert [claimed.voucher_code for claimed in received] == ["after-input"]
+    assert result.content == [TextContent(text="honored after-input")]
+
+
+# Notification bindings fold into the session
+
+
+class _CoreMethodObserver(ClientExtension):
+    """Binds a method the modern core tables already define."""
+
+    identifier = "com.example/observer"
+
+    def notifications(self) -> Sequence[NotificationBinding[Any]]:
+        return [
+            NotificationBinding(method="notifications/message", params_type=_EventParams, handler=_unreachable_handler)
+        ]
+
+
+async def test_notification_bindings_fold_into_the_session(caplog: pytest.LogCaptureFixture) -> None:
+    """The Client threads extension bindings into its session; a core-known binding draws the one-time warning."""
+    with caplog.at_level(logging.WARNING, logger="client"):
+        async with Client(_add_server(), extensions=[_CoreMethodObserver()]):
+            pass
+
+    expected = f"notification binding for 'notifications/message' will never fire at {LATEST_MODERN_VERSION}"
+    assert caplog.text.count(expected) == 1

tests/client/test_extension.py

@@ -0,0 +1,379 @@
+"""Construction-time tests for `mcp.client.extension`; no session is ever opened."""
+
+from dataclasses import FrozenInstanceError
+from typing import Any, Literal, cast
+
+import pytest
+from inline_snapshot import snapshot
+from mcp_types import CallToolResult, InputRequiredResult, Result
+from mcp_types.version import MODERN_PROTOCOL_VERSIONS
+from pydantic import AliasChoices, AliasPath, BaseModel, Field
+from pydantic.fields import FieldInfo
+
+from mcp.client.extension import (
+    ClaimContext,
+    ClientExtension,
+    NotificationBinding,
+    ResultClaim,
+    _wire_keys,
+    advertise,
+)
+
+
+class _TaskResult(Result):
+    result_type: Literal["task"] = "task"
+    task_id: str = "t-1"
+
+
+class _UntaggedResult(Result):
+    """No `result_type` field at all."""
+
+
+class _PlainStringTagResult(Result):
+    result_type: str = "task"
+
+
+class _OtherTagResult(Result):
+    result_type: Literal["other"] = "other"
+
+
+class _ClaimedCallToolResult(CallToolResult):
+    """A core-result subclass; rejected as a claim model regardless of its tag."""
+
+
+class _ClaimedInputRequiredResult(InputRequiredResult):
+    """A core-result subclass; rejected as a claim model regardless of its tag."""
+
+
+async def _resolve(result: Result, ctx: ClaimContext) -> CallToolResult:
+    raise NotImplementedError
+
+
+def _claim(model: type[Result] = _TaskResult, **kwargs: Any) -> ResultClaim[Result]:
+    return ResultClaim(result_type="task", model=model, resolve=_resolve, **kwargs)
+
+
+def test_claim_with_literal_discriminated_model_constructs() -> None:
+    """SDK-defined: a model tagged with the claimed Literal constructs, defaulting to `tools/call` everywhere."""
+    claim = ResultClaim(result_type="task", model=_TaskResult, resolve=_resolve)
+
+    assert claim.result_type == "task"
+    assert claim.model is _TaskResult
+    assert claim.resolve is _resolve
+    assert claim.method == "tools/call"
+    assert claim.protocol_versions is None
+
+
+def test_claim_accepts_modern_protocol_versions() -> None:
+    """SDK-defined: a non-None `protocol_versions` subset of the modern revisions is accepted."""
+    versions = frozenset(MODERN_PROTOCOL_VERSIONS)
+
+    claim = _claim(protocol_versions=versions)
+
+    assert claim.protocol_versions == versions
+
+
+def test_claim_rejects_core_result_type_vocabulary() -> None:
+    """SDK-defined: a claim cannot re-key the core tags 'complete' and 'input_required'."""
+    messages: dict[str, str] = {}
+    for result_type in ("complete", "input_required"):
+        with pytest.raises(ValueError) as exc_info:
+            ResultClaim(result_type=result_type, model=_TaskResult, resolve=_resolve)
+        messages[result_type] = str(exc_info.value)
+
+    assert messages == snapshot(
+        {
+            "complete": "resultType 'complete' is core protocol vocabulary",
+            "input_required": "resultType 'input_required' is core protocol vocabulary",
+        }
+    )
+
+
+@pytest.mark.parametrize("model", [_ClaimedCallToolResult, _ClaimedInputRequiredResult])
+def test_claim_rejects_model_subclassing_core_result_types(model: type[Result]) -> None:
+    """SDK-defined: a claim model subclassing a core result type is rejected; it would bypass claim routing."""
+    with pytest.raises(ValueError) as exc_info:
+        _claim(model=model)
+
+    assert str(exc_info.value) == snapshot("claim models must not subclass core result types")
+
+
+def test_claim_rejects_model_without_result_type_field() -> None:
+    """SDK-defined: the claim model must declare the discriminating `result_type` field."""
+    with pytest.raises(ValueError) as exc_info:
+        _claim(model=_UntaggedResult)
+
+    assert str(exc_info.value) == snapshot("_UntaggedResult.result_type must be Literal['task']")
+
+
+def test_claim_rejects_plain_str_result_type_field() -> None:
+    """SDK-defined: the model's `result_type` must be a Literal of the claimed tag, not a plain `str`."""
+    with pytest.raises(ValueError) as exc_info:
+        _claim(model=_PlainStringTagResult)
+
+    assert str(exc_info.value) == snapshot("_PlainStringTagResult.result_type must be Literal['task']")
+
+
+def test_claim_rejects_mismatched_result_type_literal() -> None:
+    """SDK-defined: the model's Literal tag must equal the claim's `result_type`."""
+    with pytest.raises(ValueError) as exc_info:
+        _claim(model=_OtherTagResult)
+
+    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"
+    )
+
+
+class _ValidationAliasResult(Result):
+    result_type: Literal["va"] = "va"
+    vendor_state: dict[str, Any] | None = Field(default=None, validation_alias="requestState")
+
+
+class _SerializationAliasResult(Result):
+    result_type: Literal["sa"] = "sa"
+    vendor_state: dict[str, Any] | None = Field(default=None, serialization_alias="inputRequests")
+
+
+class _AliasChoicesResult(Result):
+    result_type: Literal["ac"] = "ac"
+    vendor_state: dict[str, Any] | None = Field(
+        default=None, validation_alias=AliasChoices("vendorKey", "requestState")
+    )
+
+
+class _AliasPathResult(Result):
+    result_type: Literal["ap"] = "ap"
+    vendor_state: dict[str, Any] | None = Field(
+        default=None, validation_alias=AliasChoices(AliasPath("requestState", "nested"))
+    )
+
+
+def test_wire_keys_for_a_bare_field_is_just_its_name() -> None:
+    """SDK-defined: a field with no aliases reads and writes only its own name."""
+    assert _wire_keys("plain", FieldInfo(annotation=str)) == frozenset({"plain"})
+
+
+def test_claim_rejects_reserved_aliases_in_every_alias_form() -> None:
+    """SDK-defined: validation_alias, serialization_alias, and AliasChoices routes to a reserved key are all caught."""
+    messages: dict[str, str] = {}
+    for model in (_ValidationAliasResult, _SerializationAliasResult, _AliasChoicesResult, _AliasPathResult):
+        with pytest.raises(ValueError) as exc_info:
+            ResultClaim(result_type=model.model_fields["result_type"].default, model=model, resolve=_resolve)
+        messages[model.__name__] = str(exc_info.value)
+
+    assert messages == snapshot(
+        {
+            "_ValidationAliasResult": "_ValidationAliasResult.vendor_state aliases "
+            "'requestState', a typed field of the core result surface; a colliding value would fail "
+            "core validation before the claim adapter runs",
+            "_SerializationAliasResult": "_SerializationAliasResult.vendor_state aliases "
+            "'inputRequests', a typed field of the core result surface; a colliding value would fail "
+            "core validation before the claim adapter runs",
+            "_AliasChoicesResult": "_AliasChoicesResult.vendor_state aliases 'requestState', a typed field of the core "
+            "result surface; a colliding value would fail core validation before the claim adapter runs",
+            "_AliasPathResult": "_AliasPathResult.vendor_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:
+        _claim(method=cast("Literal['tools/call']", "prompts/get"))
+
+    assert str(exc_info.value) == snapshot("claims attach to ['tools/call'] only; got method 'prompts/get'")
+
+
+def test_claim_rejects_empty_protocol_versions() -> None:
+    """SDK-defined: an empty version set is rejected; `None` is the spelling for every modern version."""
+    with pytest.raises(ValueError) as exc_info:
+        _claim(protocol_versions=frozenset())
+
+    assert str(exc_info.value) == snapshot("empty protocol_versions could never activate; use None for all")
+
+
+def test_claim_rejects_non_modern_protocol_versions() -> None:
+    """SDK-defined: a non-None version set must be a subset of the modern protocol revisions."""
+    messages: list[str] = []
+    for versions in (
+        frozenset({"2025-11-25"}),
+        frozenset({"2026-07-28", "2025-11-25"}),
+        frozenset({"never-a-version"}),
+    ):
+        with pytest.raises(ValueError) as exc_info:
+            _claim(protocol_versions=versions)
+        messages.append(str(exc_info.value))
+
+    assert messages == snapshot(
+        [
+            "protocol_versions ['2025-11-25'] are not modern protocol revisions; claimed shapes "
+            "cannot be delivered on a legacy wire (None means every modern version)",
+            "protocol_versions ['2025-11-25'] are not modern protocol revisions; claimed shapes "
+            "cannot be delivered on a legacy wire (None means every modern version)",
+            "protocol_versions ['never-a-version'] are not modern protocol revisions; claimed shapes "
+            "cannot be delivered on a legacy wire (None means every modern version)",
+        ]
+    )
+
+
+def test_result_claim_is_frozen() -> None:
+    """SDK-defined: claims are immutable; mutating one after construction raises."""
+    claim = _claim()
+
+    with pytest.raises(FrozenInstanceError):
+        setattr(claim, "result_type", "other")  # direct assignment is also a type error
+
+
+class _TaskNotificationParams(BaseModel):
+    task_id: str
+
+
+async def _on_task(params: _TaskNotificationParams) -> None:
+    raise NotImplementedError
+
+
+def test_notification_binding_constructs() -> None:
+    """SDK-defined: a binding is a bare declaration with no construction-time validation."""
+    binding = NotificationBinding(method="notifications/tasks", params_type=_TaskNotificationParams, handler=_on_task)
+
+    assert binding.method == "notifications/tasks"
+    assert binding.params_type is _TaskNotificationParams
+    assert binding.handler is _on_task
+
+
+def test_notification_binding_accepts_core_known_method() -> None:
+    """SDK-defined: deliberately no spec-table check at construction, so packages survive core adopting a method."""
+    binding = NotificationBinding(
+        method="notifications/progress", params_type=_TaskNotificationParams, handler=_on_task
+    )
+
+    assert binding.method == "notifications/progress"
+
+
+def test_notification_binding_is_frozen() -> None:
+    """SDK-defined: bindings are immutable; mutating one after construction raises."""
+    binding = NotificationBinding(method="notifications/tasks", params_type=_TaskNotificationParams, handler=_on_task)
+
+    with pytest.raises(FrozenInstanceError):
+        setattr(binding, "method", "notifications/other")  # direct assignment is also a type error
+
+
+def test_extension_defaults_advertise_nothing() -> None:
+    """SDK-defined: a minimal subclass advertises empty settings, no claims, and no bindings."""
+
+    class _MinimalExt(ClientExtension):
+        identifier = "com.example/minimal"
+
+    ext = _MinimalExt()
+
+    assert ext.settings() == {}
+    assert ext.claims() == ()
+    assert ext.notifications() == ()
+
+
+@pytest.mark.parametrize(
+    "identifier",
+    [
+        "io.modelcontextprotocol/ui",
+        "com.example/my_ext",
+        "com.x-y.z2/n.a-b_c",
+        "example/x",
+        "a/b",
+        "com.example/9start",
+    ],
+)
+def test_grammar_conformant_identifiers_accepted_at_class_definition(identifier: str) -> None:
+    """Spec `_meta` key grammar: conformant `vendor-prefix/name` identifiers are accepted."""
+    cls = type("_GoodExt", (ClientExtension,), {"identifier": identifier})
+
+    assert cls.identifier == identifier
+
+
+@pytest.mark.parametrize(
+    "identifier",
+    [
+        "noprefix",
+        "-foo/bar",
+        ".leading/x",
+        "a..b/x",
+        "foo-/x",
+        "9foo/x",
+        "foo/-bar",
+        "foo/bar-",
+        "foo/",
+        "/bar",
+        "foo/ba r",
+        "io.modelcontextprotocol/ui\n",
+        "",
+        42,
+    ],
+)
+def test_malformed_identifier_rejected_at_class_definition(identifier: Any) -> None:
+    """SDK-defined: the SEP-2133 `vendor-prefix/name` grammar is enforced the moment the subclass is defined."""
+    with pytest.raises(TypeError):
+        type("_BadExt", (ClientExtension,), {"identifier": identifier})
+
+
+def test_subclass_without_identifier_allowed_at_definition() -> None:
+    """SDK-defined: a subclass with no class-level `identifier` is allowed; validation waits for consumption."""
+
+    class _AbstractishExt(ClientExtension):
+        """Intermediate base; concrete subclasses supply the identifier."""
+
+    class _ConcreteExt(_AbstractishExt):
+        identifier = "com.example/concrete"
+
+    assert _ConcreteExt.identifier == "com.example/concrete"
+
+
+def test_advertise_serves_captured_settings() -> None:
+    """SDK-defined: `advertise()` returns an ad-only extension serving the captured settings."""
+    ext = advertise("com.example/flags", {"enabled": True})
+
+    assert isinstance(ext, ClientExtension)
+    assert ext.identifier == "com.example/flags"
+    assert ext.settings() == {"enabled": True}
+    assert ext.claims() == ()
+    assert ext.notifications() == ()
+
+
+def test_advertise_defaults_to_empty_settings() -> None:
+    """SDK-defined: omitting settings advertises the extension with an empty map."""
+    ext = advertise("com.example/flags")
+
+    assert ext.settings() == {}
+
+
+@pytest.mark.parametrize("identifier", ["noprefix", "foo/", ""])
+def test_advertise_validates_identifier_eagerly(identifier: str) -> None:
+    """SDK-defined: `advertise()` validates the identifier eagerly, at the call site."""
+    with pytest.raises(TypeError):
+        advertise(identifier)

tests/client/test_send_request_mcp_name.py

@@ -0,0 +1,251 @@
+"""`ClientSession.send_request` mirrors `Request.name_param` into the `Mcp-Name`
+header on send paths the core `NAME_BEARING_METHODS` table does not cover. The
+vendor sends also pin the widened `send_request` typing (no cast needed)."""
+
+from collections.abc import Mapping
+from typing import Any, Literal
+
+import anyio
+import anyio.abc
+import mcp_types as types
+import pytest
+from inline_snapshot import snapshot
+from mcp_types import (
+    CallToolResult,
+    Implementation,
+    ListToolsResult,
+    Request,
+    ServerCapabilities,
+    TextContent,
+    Tool,
+)
+from mcp_types.version import LATEST_HANDSHAKE_VERSION, LATEST_MODERN_VERSION
+
+from mcp.client.session import ClientSession
+from mcp.shared.dispatcher import CallOptions, OnNotify, OnRequest
+from mcp.shared.inbound import MCP_NAME_HEADER, MCP_PROTOCOL_VERSION_HEADER, encode_header_value
+
+
+class _RecordingDispatcher:
+    """Records `send_raw_request` opts and answers with canned per-method results."""
+
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, CallOptions]] = []
+
+    async def run(
+        self,
+        on_request: OnRequest,
+        on_notify: OnNotify,
+        *,
+        task_status: anyio.abc.TaskStatus[None] = anyio.TASK_STATUS_IGNORED,
+    ) -> None:
+        task_status.started()
+        await anyio.sleep_forever()
+
+    async def send_raw_request(
+        self, method: str, params: Mapping[str, Any] | None, opts: CallOptions | None = None
+    ) -> dict[str, Any]:
+        self.calls.append((method, opts or {}))
+        if method == "tools/call":
+            return CallToolResult(content=[TextContent(type="text", text="ok")]).model_dump(
+                by_alias=True, mode="json", exclude_none=True
+            )
+        if method == "tools/list":
+            return ListToolsResult(tools=[Tool(name="my-tool", input_schema={"type": "object"})]).model_dump(
+                by_alias=True, mode="json", exclude_none=True
+            )
+        return {}
+
+    async def notify(self, method: str, params: Mapping[str, Any] | None, opts: CallOptions | None = None) -> None:
+        raise NotImplementedError
+
+
+class _GetWidgetParams(types.RequestParams):
+    widget_id: str
+
+
+class _GetWidgetRequest(Request[_GetWidgetParams, Literal["vendor/widgets/get"]]):
+    method: Literal["vendor/widgets/get"] = "vendor/widgets/get"
+    name_param = "widgetId"
+
+
+class _RawWidgetRequest(Request[dict[str, Any], Literal["vendor/widgets/get"]]):
+    """Same wire shape with untyped params, so tests can omit or mistype the name value."""
+
+    method: Literal["vendor/widgets/get"] = "vendor/widgets/get"
+    name_param = "widgetId"
+
+
+class _ShadowCallToolRequest(Request[dict[str, Any], Literal["tools/call"]]):
+    """A vendor type declaring `name_param` for a method the core table already covers."""
+
+    method: Literal["tools/call"] = "tools/call"
+    name_param = "customKey"
+
+
+class _PlainVendorRequest(Request[dict[str, Any], Literal["vendor/widgets/list"]]):
+    method: Literal["vendor/widgets/list"] = "vendor/widgets/list"
+
+
+class _OptionalParamsWidgetRequest(Request[dict[str, Any] | None, Literal["vendor/widgets/get"]]):
+    """Optional params, so a send can carry no params key at all."""
+
+    method: Literal["vendor/widgets/get"] = "vendor/widgets/get"
+    params: dict[str, Any] | None = None
+    name_param = "widgetId"
+
+
+def _adopt_modern(session: ClientSession) -> None:
+    session.adopt(
+        types.DiscoverResult(
+            supported_versions=[LATEST_MODERN_VERSION],
+            capabilities=ServerCapabilities(),
+            server_info=Implementation(name="stub", version="0"),
+        )
+    )
+
+
+def _adopt_handshake(session: ClientSession) -> None:
+    session.adopt(
+        types.InitializeResult(
+            protocol_version=LATEST_HANDSHAKE_VERSION,
+            capabilities=ServerCapabilities(),
+            server_info=Implementation(name="stub", version="0"),
+        )
+    )
+
+
+def _headers(opts: CallOptions) -> dict[str, str]:
+    return opts.get("headers") or {}
+
+
+@pytest.mark.anyio
+async def test_vendor_name_param_emits_mcp_name_on_the_modern_path() -> None:
+    """A vendor `name_param` emits `Mcp-Name` on a modern wire even outside `NAME_BEARING_METHODS`."""
+    dispatcher = _RecordingDispatcher()
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            _adopt_modern(session)
+            await session.send_request(_GetWidgetRequest(params=_GetWidgetParams(widget_id="w-1")), types.EmptyResult)
+    [(_, opts)] = dispatcher.calls
+    assert _headers(opts)[MCP_NAME_HEADER] == "w-1"
+
+
+@pytest.mark.anyio
+async def test_vendor_name_param_emits_mcp_name_on_the_handshake_path() -> None:
+    """The handshake stamp sets no `Mcp-Name`, so on a legacy wire the delta is the emitter."""
+    dispatcher = _RecordingDispatcher()
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            _adopt_handshake(session)
+            await session.send_request(_GetWidgetRequest(params=_GetWidgetParams(widget_id="w-1")), types.EmptyResult)
+    [(_, opts)] = dispatcher.calls
+    assert _headers(opts)[MCP_NAME_HEADER] == "w-1"
+    # The stamp's own headers survive the delta.
+    assert _headers(opts)[MCP_PROTOCOL_VERSION_HEADER] == LATEST_HANDSHAKE_VERSION
+
+
+@pytest.mark.anyio
+async def test_name_value_passes_through_encode_header_value() -> None:
+    """A non-ASCII name is base64-sentinel encoded, a spec MUST for `Mcp-Name`."""
+    name = "wídget ✨"
+    dispatcher = _RecordingDispatcher()
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            _adopt_handshake(session)
+            await session.send_request(_GetWidgetRequest(params=_GetWidgetParams(widget_id=name)), types.EmptyResult)
+    [(_, opts)] = dispatcher.calls
+    assert _headers(opts)[MCP_NAME_HEADER] == encode_header_value(name)
+    assert _headers(opts)[MCP_NAME_HEADER].startswith("=?base64?")
+
+
+@pytest.mark.anyio
+async def test_core_tools_call_header_comes_from_the_stamp_alone() -> None:
+    """Core `tools/call` is unchanged: the modern stamp emits the header; legacy stays headerless."""
+    dispatcher = _RecordingDispatcher()
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            _adopt_modern(session)
+            await session.call_tool("my-tool", {})
+            _adopt_handshake(session)
+            await session.call_tool("my-tool", {})
+    (_, modern_opts), (_, legacy_opts) = (call for call in dispatcher.calls if call[0] == "tools/call")
+    assert _headers(modern_opts)[MCP_NAME_HEADER] == "my-tool"
+    assert MCP_NAME_HEADER not in _headers(legacy_opts)
+
+
+@pytest.mark.anyio
+async def test_stamp_table_rows_win_over_name_param_by_ordering() -> None:
+    """A stamp-emitted `Mcp-Name` wins; `name_param` never overwrites an existing header."""
+    dispatcher = _RecordingDispatcher()
+    request = _ShadowCallToolRequest(params={"name": "real-tool", "customKey": "other-value"})
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            _adopt_modern(session)
+            await session.send_request(request, types.CallToolResult)
+    [(_, opts)] = dispatcher.calls
+    assert _headers(opts)[MCP_NAME_HEADER] == "real-tool"
+
+
+@pytest.mark.anyio
+async def test_vendor_name_param_emits_mcp_name_on_the_preconnect_path() -> None:
+    """Emission is era-unconditional: a session that never adopts still emits `Mcp-Name`."""
+    dispatcher = _RecordingDispatcher()
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            await session.send_request(_GetWidgetRequest(params=_GetWidgetParams(widget_id="w-1")), types.EmptyResult)
+    [(_, opts)] = dispatcher.calls
+    assert _headers(opts) == {MCP_NAME_HEADER: "w-1"}  # and no era headers: nothing adopted
+
+
+@pytest.mark.anyio
+async def test_missing_name_value_fails_loud_naming_method_and_key() -> None:
+    """A missing name value raises ValueError naming the method and key, before the wire."""
+    dispatcher = _RecordingDispatcher()
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            _adopt_handshake(session)
+            with pytest.raises(ValueError) as exc_info:
+                await session.send_request(_RawWidgetRequest(params={}), types.EmptyResult)
+            assert dispatcher.calls == []  # raised before reaching the wire
+    assert str(exc_info.value) == snapshot("vendor/widgets/get requires params['widgetId'] for Mcp-Name")
+
+
+@pytest.mark.anyio
+async def test_non_string_name_value_fails_loud() -> None:
+    """A non-string name value raises the same ValueError as a missing one."""
+    dispatcher = _RecordingDispatcher()
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            _adopt_handshake(session)
+            with pytest.raises(ValueError) as exc_info:
+                await session.send_request(_RawWidgetRequest(params={"widgetId": 7}), types.EmptyResult)
+            assert dispatcher.calls == []
+    assert str(exc_info.value) == snapshot("vendor/widgets/get requires params['widgetId'] for Mcp-Name")
+
+
+@pytest.mark.anyio
+async def test_absent_params_fails_loud_not_attribute_error() -> None:
+    """Absent params still raise the documented ValueError, not an AttributeError."""
+    dispatcher = _RecordingDispatcher()
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            _adopt_handshake(session)
+            with pytest.raises(ValueError) as exc_info:
+                await session.send_request(_OptionalParamsWidgetRequest(), types.EmptyResult)
+            assert dispatcher.calls == []
+    assert str(exc_info.value) == snapshot("vendor/widgets/get requires params['widgetId'] for Mcp-Name")
+
+
+@pytest.mark.anyio
+async def test_request_without_name_param_sends_no_mcp_name() -> None:
+    """No `name_param` and a method outside the core table emits no `Mcp-Name` on either era."""
+    dispatcher = _RecordingDispatcher()
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            _adopt_modern(session)
+            await session.send_request(_PlainVendorRequest(params={}), types.EmptyResult)
+            _adopt_handshake(session)
+            await session.send_ping()
+    for _, opts in dispatcher.calls:
+        assert MCP_NAME_HEADER not in _headers(opts)

tests/client/test_session_claims.py

@@ -0,0 +1,468 @@
+"""`ClientSession` result claims: construction validation, activation at modern
+adopts only, claimed-result routing, the version-aware capability ad, and the
+`allow_claimed` escape hatch."""
+
+from collections.abc import Mapping
+from typing import Any, Literal
+
+import anyio
+import anyio.abc
+import mcp_types as types
+import pytest
+from inline_snapshot import snapshot
+from mcp_types import (
+    CLIENT_CAPABILITIES_META_KEY,
+    CallToolResult,
+    Implementation,
+    InputRequiredResult,
+    ListToolsResult,
+    Result,
+    ServerCapabilities,
+    TextContent,
+    Tool,
+)
+from mcp_types.methods import validate_server_result
+from mcp_types.version import LATEST_HANDSHAKE_VERSION, LATEST_MODERN_VERSION
+from pydantic import ValidationError
+from typing_extensions import assert_type
+
+from mcp.client.extension import ClaimContext, ResultClaim, UnexpectedClaimedResult
+from mcp.client.session import ClientSession, _CallToolResultAdapter
+from mcp.shared.dispatcher import CallOptions, OnNotify, OnRequest
+
+_TASKS_EXT = "com.example/tasks"
+_AD_ONLY_EXT = "com.example/flags"
+
+
+class _TaskResult(Result):
+    """A claimed result shape, tagged `task`."""
+
+    result_type: Literal["task"] = "task"
+    task_id: str
+
+
+async def _resolve_task(result: _TaskResult, ctx: ClaimContext) -> CallToolResult:
+    raise NotImplementedError  # session-tier tests never drive a resolver; that is the Client's job
+
+
+def _task_claim(**kwargs: Any) -> ResultClaim[_TaskResult]:
+    return ResultClaim(result_type="task", model=_TaskResult, resolve=_resolve_task, **kwargs)
+
+
+_COMPLETE_TOOL_RESULT = CallToolResult(content=[TextContent(type="text", text="ok")]).model_dump(
+    by_alias=True, mode="json", exclude_none=True
+)
+_CLAIMED_TASK_RESULT = {"resultType": "task", "taskId": "t-1"}
+_TOOL_LISTING = ListToolsResult(tools=[Tool(name="t", input_schema={"type": "object"})]).model_dump(
+    by_alias=True, mode="json", exclude_none=True
+)
+_INITIALIZE_RESULT = types.InitializeResult(
+    protocol_version=LATEST_HANDSHAKE_VERSION,
+    capabilities=ServerCapabilities(),
+    server_info=Implementation(name="stub", version="0"),
+).model_dump(by_alias=True, mode="json", exclude_none=True)
+
+
+class _RecordingDispatcher:
+    """Records every send and answers each method with a canned result."""
+
+    def __init__(self, tool_result: dict[str, Any] | None = None) -> None:
+        self.calls: list[tuple[str, Mapping[str, Any] | None, CallOptions]] = []
+        self.notifications: list[str] = []
+        self._tool_result = tool_result if tool_result is not None else _COMPLETE_TOOL_RESULT
+
+    async def run(
+        self,
+        on_request: OnRequest,
+        on_notify: OnNotify,
+        *,
+        task_status: anyio.abc.TaskStatus[None] = anyio.TASK_STATUS_IGNORED,
+    ) -> None:
+        task_status.started()
+        await anyio.sleep_forever()
+
+    async def send_raw_request(
+        self, method: str, params: Mapping[str, Any] | None, opts: CallOptions | None = None
+    ) -> dict[str, Any]:
+        self.calls.append((method, params, opts or {}))
+        if method == "tools/call":
+            return self._tool_result
+        if method == "tools/list":
+            return _TOOL_LISTING
+        if method == "initialize":
+            return _INITIALIZE_RESULT
+        return {}
+
+    async def notify(self, method: str, params: Mapping[str, Any] | None, opts: CallOptions | None = None) -> None:
+        self.notifications.append(method)
+
+
+def _claims_session(dispatcher: _RecordingDispatcher, *claims: ResultClaim[Any]) -> ClientSession:
+    return ClientSession(dispatcher=dispatcher, extensions={_TASKS_EXT: {}}, result_claims={_TASKS_EXT: list(claims)})
+
+
+def _adopt_modern(session: ClientSession) -> None:
+    session.adopt(
+        types.DiscoverResult(
+            supported_versions=[LATEST_MODERN_VERSION],
+            capabilities=ServerCapabilities(),
+            server_info=Implementation(name="stub", version="0"),
+        )
+    )
+
+
+def _adopt_handshake(session: ClientSession) -> None:
+    session.adopt(
+        types.InitializeResult(
+            protocol_version=LATEST_HANDSHAKE_VERSION,
+            capabilities=ServerCapabilities(),
+            server_info=Implementation(name="stub", version="0"),
+        )
+    )
+
+
+def test_duplicate_claim_tag_across_extensions_rejected() -> None:
+    """SDK-defined: two claims on the same resultType cannot be routed apart, so construction fails."""
+    with pytest.raises(ValueError) as exc_info:
+        ClientSession(
+            dispatcher=_RecordingDispatcher(),
+            extensions={_TASKS_EXT: {}, _AD_ONLY_EXT: {}},
+            result_claims={_TASKS_EXT: [_task_claim()], _AD_ONLY_EXT: [_task_claim()]},
+        )
+
+    assert str(exc_info.value) == snapshot("duplicate result claim for resultType 'task'")
+
+
+def test_claims_keyed_to_unadvertised_extension_rejected() -> None:
+    """SDK-defined: a `result_claims` key with no `extensions` entry advertises nothing, so construction fails."""
+    messages: list[str] = []
+    for extensions in (None, {_AD_ONLY_EXT: {"flag": True}}):
+        with pytest.raises(ValueError) as exc_info:
+            ClientSession(
+                dispatcher=_RecordingDispatcher(),
+                extensions=extensions,
+                result_claims={_TASKS_EXT: [_task_claim()]},
+            )
+        messages.append(str(exc_info.value))
+
+    assert messages == snapshot(
+        [
+            "result_claims key 'com.example/tasks' has no extensions entry; a claim is only "
+            "advertised through its extension's capability ad",
+            "result_claims key 'com.example/tasks' has no extensions entry; a claim is only "
+            "advertised through its extension's capability ad",
+        ]
+    )
+
+
+def test_empty_claim_sequence_rejected() -> None:
+    """SDK-defined: an empty claim list is rejected at construction; a claim-less extension omits the key."""
+    with pytest.raises(ValueError) as exc_info:
+        ClientSession(dispatcher=_RecordingDispatcher(), extensions={_TASKS_EXT: {}}, result_claims={_TASKS_EXT: []})
+
+    assert str(exc_info.value) == snapshot(
+        "result_claims['com.example/tasks'] is empty and would drop the extension from "
+        "the capability ad at every version. Omit the key instead"
+    )
+
+
+def test_empty_settings_count_as_an_advertised_extension() -> None:
+    """SDK-defined: empty settings ({}) still count as an ad, so claims keyed to the extension construct."""
+    session = _claims_session(_RecordingDispatcher(), _task_claim())
+
+    assert isinstance(session, ClientSession)
+
+
+def test_without_claims_the_call_tool_adapter_is_the_module_constant() -> None:
+    """SDK-defined: with zero active claims the session holds the module-level adapter by identity."""
+    session = ClientSession(dispatcher=_RecordingDispatcher())
+
+    assert session._call_tool_adapter is _CallToolResultAdapter
+    _adopt_modern(session)
+    assert session._call_tool_adapter is _CallToolResultAdapter
+    _adopt_handshake(session)
+    assert session._call_tool_adapter is _CallToolResultAdapter
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("protocol_versions", [None, frozenset({LATEST_MODERN_VERSION})])
+async def test_modern_adopt_activates_claims_and_routes_claimed_results(
+    protocol_versions: frozenset[str] | None,
+) -> None:
+    """SDK-defined: at a modern adopt, a claim active at the negotiated version routes
+    the claimed raw to the claim model."""
+    dispatcher = _RecordingDispatcher(tool_result=_CLAIMED_TASK_RESULT)
+    session = _claims_session(dispatcher, _task_claim(protocol_versions=protocol_versions))
+    with anyio.fail_after(5):
+        async with session:
+            _adopt_modern(session)
+            result = await session.call_tool("t", {}, allow_claimed=True)
+
+    assert isinstance(result, _TaskResult)
+    assert result.task_id == "t-1"
+
+
+@pytest.mark.anyio
+async def test_legacy_adopt_clears_active_claims() -> None:
+    """SDK-defined: a legacy adopt clears active claims and restores the module-level adapter."""
+    dispatcher = _RecordingDispatcher(tool_result=_CLAIMED_TASK_RESULT)
+    session = _claims_session(dispatcher, _task_claim())
+    with anyio.fail_after(5):
+        async with session:
+            _adopt_modern(session)
+            assert isinstance(await session.call_tool("t", {}, allow_claimed=True), _TaskResult)
+
+            _adopt_handshake(session)
+            assert session._call_tool_adapter is _CallToolResultAdapter
+            with pytest.raises(ValidationError):
+                await session.call_tool("t", {}, allow_claimed=True)
+            # Rejected at response parsing; the request did reach the wire.
+            assert dispatcher.calls[-1][0] == "tools/call"
+
+
+@pytest.mark.anyio
+async def test_modern_readopt_after_legacy_reactivates_claims() -> None:
+    """SDK-defined: a modern re-adopt after legacy reactivates the claims."""
+    dispatcher = _RecordingDispatcher(tool_result=_CLAIMED_TASK_RESULT)
+    session = _claims_session(dispatcher, _task_claim())
+    with anyio.fail_after(5):
+        async with session:
+            _adopt_modern(session)
+            _adopt_handshake(session)
+            assert session._call_tool_adapter is _CallToolResultAdapter
+
+            _adopt_modern(session)
+            result = await session.call_tool("t", {}, allow_claimed=True)
+
+    assert isinstance(result, _TaskResult)
+    assert session._call_tool_adapter is not _CallToolResultAdapter
+
+
+@pytest.mark.anyio
+async def test_legacy_initialize_ad_drops_claim_bearing_identifiers() -> None:
+    """SDK-defined: the legacy initialize ad drops claim-bearing identifiers; ad-only ones ride along."""
+    dispatcher = _RecordingDispatcher()
+    session = ClientSession(
+        dispatcher=dispatcher,
+        extensions={_TASKS_EXT: {}, _AD_ONLY_EXT: {"flag": True}},
+        result_claims={_TASKS_EXT: [_task_claim()]},
+    )
+    with anyio.fail_after(5):
+        async with session:
+            await session.initialize()
+
+    [(_, params, _)] = [call for call in dispatcher.calls if call[0] == "initialize"]
+    assert params is not None
+    assert params["capabilities"]["extensions"] == {_AD_ONLY_EXT: {"flag": True}}
+
+
+@pytest.mark.anyio
+async def test_legacy_ad_omits_extensions_entirely_when_every_identifier_drops() -> None:
+    """SDK-defined: when every identifier drops, the ad omits the `extensions` key entirely."""
+    dispatcher = _RecordingDispatcher()
+    session = _claims_session(dispatcher, _task_claim())
+    with anyio.fail_after(5):
+        async with session:
+            await session.initialize()
+
+    [(_, params, _)] = [call for call in dispatcher.calls if call[0] == "initialize"]
+    assert params is not None
+    assert "extensions" not in params["capabilities"]
+
+
+@pytest.mark.anyio
+async def test_modern_adopt_ad_includes_active_claim_identifiers() -> None:
+    """SDK-defined: the modern per-request `_meta` ad includes identifiers whose claims are active."""
+    dispatcher = _RecordingDispatcher()
+    session = ClientSession(
+        dispatcher=dispatcher,
+        extensions={_TASKS_EXT: {}, _AD_ONLY_EXT: {"flag": True}},
+        result_claims={_TASKS_EXT: [_task_claim()]},
+    )
+    with anyio.fail_after(5):
+        async with session:
+            _adopt_modern(session)
+            await session.send_ping()
+
+    [(_, params, _)] = dispatcher.calls
+    assert params is not None
+    capabilities = params["_meta"][CLIENT_CAPABILITIES_META_KEY]
+    assert capabilities["extensions"] == {_TASKS_EXT: {}, _AD_ONLY_EXT: {"flag": True}}
+
+
+@pytest.mark.anyio
+async def test_discover_probe_ad_includes_claim_identifiers_at_the_probe_version() -> None:
+    """SDK-defined: `send_discover` builds its `_meta` ad at the probe version, where claims are active."""
+    dispatcher = _RecordingDispatcher()
+    session = _claims_session(dispatcher, _task_claim())
+    with anyio.fail_after(5):
+        async with session:
+            await session.send_discover(LATEST_MODERN_VERSION)
+
+    [(_, params, _)] = dispatcher.calls
+    assert params is not None
+    capabilities = params["_meta"][CLIENT_CAPABILITIES_META_KEY]
+    assert capabilities["extensions"] == {_TASKS_EXT: {}}
+
+
+@pytest.mark.anyio
+async def test_discover_probe_ad_drops_claim_identifiers_at_a_legacy_probe_version() -> None:
+    """SDK-defined: at a legacy probe version no claim can be active, so the identifier drops."""
+    dispatcher = _RecordingDispatcher()
+    session = _claims_session(dispatcher, _task_claim())
+    with anyio.fail_after(5):
+        async with session:
+            await session.send_discover(LATEST_HANDSHAKE_VERSION)
+
+    [(_, params, _)] = dispatcher.calls
+    assert params is not None
+    capabilities = params["_meta"][CLIENT_CAPABILITIES_META_KEY]
+    assert "extensions" not in capabilities
+
+
+class _CoreTaggedResult(Result):
+    """A claim whose wire tag collides with the adapter's internal routing sentinel."""
+
+    result_type: Literal["core"] = "core"
+    payload: str = ""
+
+
+async def _resolve_core_tagged(result: _CoreTaggedResult, ctx: ClaimContext) -> CallToolResult:
+    raise NotImplementedError
+
+
+@pytest.mark.anyio
+async def test_claim_tagged_core_cannot_hijack_core_parsing() -> None:
+    """SDK-defined: a claim may use "core" as its wire tag without colliding with core parsing."""
+    claim = ResultClaim(result_type="core", model=_CoreTaggedResult, resolve=_resolve_core_tagged)
+    dispatcher = _RecordingDispatcher(tool_result={"resultType": "core", "payload": "p-1"})
+    session = ClientSession(dispatcher=dispatcher, extensions={_TASKS_EXT: {}}, result_claims={_TASKS_EXT: [claim]})
+    with anyio.fail_after(5):
+        async with session:
+            _adopt_modern(session)
+            ordinary = session._call_tool_adapter.validate_python(_COMPLETE_TOOL_RESULT)
+            claimed = await session.call_tool("t", {}, allow_claimed=True)
+
+    assert isinstance(ordinary, CallToolResult)
+    assert isinstance(claimed, _CoreTaggedResult)
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("with_claims", [True, False])
+async def test_unknown_result_type_fails_validation_with_and_without_claims(with_claims: bool) -> None:
+    """SDK-defined: a resultType outside the active claim set fails core validation, claims or not."""
+    raw = {"resultType": "weird", "taskId": "t-1"}
+    dispatcher = _RecordingDispatcher(tool_result=raw)
+    session = _claims_session(dispatcher, _task_claim()) if with_claims else ClientSession(dispatcher=dispatcher)
+    with anyio.fail_after(5):
+        async with session:
+            _adopt_modern(session)
+            with pytest.raises(ValidationError):
+                await session.call_tool("t", {}, allow_claimed=True)
+            # Rejected at response parsing; the request did reach the wire.
+            assert dispatcher.calls[-1][0] == "tools/call"
+
+
+@pytest.mark.anyio
+async def test_non_string_result_type_fails_core_validation_not_discrimination() -> None:
+    """SDK-defined: a non-string resultType stays on the core arm and fails as ValidationError, not TypeError."""
+    raw: dict[str, Any] = {"resultType": {"nested": True}}
+    dispatcher = _RecordingDispatcher(tool_result=raw)
+    session = _claims_session(dispatcher, _task_claim())
+    with anyio.fail_after(5):
+        async with session:
+            _adopt_modern(session)
+            with pytest.raises(ValidationError):
+                await session.call_tool("t", {}, allow_claimed=True)
+            # Rejected at response parsing; the request did reach the wire.
+            assert dispatcher.calls[-1][0] == "tools/call"
+
+
+def test_adopt_built_adapter_revalidates_model_instances() -> None:
+    """SDK-defined: the adopt-built adapter routes already-built model instances as well as raw dicts."""
+    session = _claims_session(_RecordingDispatcher(), _task_claim())
+    _adopt_modern(session)
+    adapter = session._call_tool_adapter
+
+    claimed = adapter.validate_python(_TaskResult(task_id="t-2"))
+    assert isinstance(claimed, _TaskResult)
+    core = adapter.validate_python(CallToolResult(content=[]))
+    assert isinstance(core, CallToolResult)
+
+
+@pytest.mark.anyio
+async def test_input_required_routes_to_core_arm_with_claims_active() -> None:
+    """Spec-mandated: `input_required` is core vocabulary; active claims leave that arm untouched."""
+    raw = {"resultType": "input_required", "requestState": "s-1"}
+    session = _claims_session(_RecordingDispatcher(tool_result=raw), _task_claim())
+    with anyio.fail_after(5):
+        async with session:
+            _adopt_modern(session)
+            result = await session.call_tool("t", {}, allow_input_required=True, allow_claimed=True)
+
+    assert isinstance(result, InputRequiredResult)
+    assert result.request_state == "s-1"
+
+
+@pytest.mark.anyio
+async def test_claimed_result_raises_unexpected_claimed_result_by_default() -> None:
+    """SDK-defined: without `allow_claimed` a claimed shape raises, carrying the parsed
+    result so the caller can clean up any server-side state it references."""
+    dispatcher = _RecordingDispatcher(tool_result=_CLAIMED_TASK_RESULT)
+    session = _claims_session(dispatcher, _task_claim())
+    with anyio.fail_after(5):
+        async with session:
+            _adopt_modern(session)
+            with pytest.raises(UnexpectedClaimedResult) as exc_info:
+                await session.call_tool("t", {})
+            # The shape parsed and then raised; the request did reach the wire.
+            assert dispatcher.calls[-1][0] == "tools/call"
+
+    assert isinstance(exc_info.value.result, _TaskResult)
+    assert exc_info.value.result.task_id == "t-1"
+    assert str(exc_info.value) == snapshot(
+        "Server returned a claimed result (_TaskResult); pass the owning extension to "
+        "Client(extensions=[...]) for transparent resolution, or call with allow_claimed=True "
+        "and handle the shape. The carried result may reference server-side state needing cleanup."
+    )
+
+
+@pytest.mark.anyio
+async def test_call_tool_result_path_identical_under_both_allow_claimed_values() -> None:
+    """SDK-defined: `allow_claimed` only affects claimed shapes; ordinary results come back identical."""
+    dispatcher = _RecordingDispatcher()
+    session = _claims_session(dispatcher, _task_claim())
+    with anyio.fail_after(5):
+        async with session:
+            _adopt_modern(session)
+            r_default = await session.call_tool("t", {})
+            r_opted = await session.call_tool("t", {}, allow_claimed=True)
+
+    assert isinstance(r_opted, CallToolResult)
+    assert r_opted == r_default
+
+
+@pytest.mark.anyio
+async def test_call_tool_overload_matrix_narrows_statically() -> None:
+    """SDK-defined: each flag combination narrows `call_tool` to its documented return union under pyright."""
+    dispatcher = _RecordingDispatcher()
+    session = _claims_session(dispatcher, _task_claim())
+    with anyio.fail_after(5):
+        async with session:
+            _adopt_modern(session)
+            r1 = await session.call_tool("t", {})
+            assert_type(r1, CallToolResult)
+            r2 = await session.call_tool("t", {}, allow_input_required=True)
+            assert_type(r2, CallToolResult | InputRequiredResult)
+            r3 = await session.call_tool("t", {}, allow_claimed=True)
+            assert_type(r3, CallToolResult | Result)
+            r4 = await session.call_tool("t", {}, allow_input_required=True, allow_claimed=True)
+            assert_type(r4, CallToolResult | InputRequiredResult | Result)
+
+    assert [type(r) for r in (r1, r2, r3, r4)] == [CallToolResult] * 4
+
+
+def test_claimed_raw_passes_v2026_tools_call_surface_validation() -> None:
+    """Pins the claim path's dependency: an unknown resultType passes `validate_server_result`
+    at 2026-07-28; this failing is the signal that mcp-types tightened the surface."""
+    validate_server_result("tools/call", LATEST_MODERN_VERSION, {"resultType": "task", "taskId": "t-1"})

tests/client/test_session_notification_bindings.py

@@ -0,0 +1,287 @@
+"""`ClientSession` notification bindings: serialized per-binding delivery through a
+bounded FIFO, consulted only for methods the negotiated version's core tables do
+not know."""
+
+import logging
+
+import anyio
+import mcp_types as types
+import pytest
+from mcp_types import EmptyResult, Implementation, ServerCapabilities
+from mcp_types.version import LATEST_MODERN_VERSION
+from pydantic import BaseModel
+
+from mcp.client.extension import NotificationBinding
+from mcp.client.session import _NOTIFICATION_QUEUE_SIZE, ClientSession
+from mcp.shared.direct_dispatcher import create_direct_dispatcher_pair
+from mcp.shared.dispatcher import DispatchContext
+from mcp.shared.transport_context import TransportContext
+
+_VENDOR_METHOD = "notifications/vendor/task_done"
+
+
+class _EventParams(BaseModel):
+    seq: int
+
+
+async def _server_on_request(
+    ctx: DispatchContext[TransportContext], method: str, params: dict[str, object] | None
+) -> dict[str, object]:
+    assert method == "ping"
+    return {}
+
+
+async def _server_on_notify(
+    ctx: DispatchContext[TransportContext], method: str, params: dict[str, object] | None
+) -> None:
+    raise NotImplementedError
+
+
+def _adopt_modern(session: ClientSession) -> None:
+    session.adopt(
+        types.DiscoverResult(
+            supported_versions=[LATEST_MODERN_VERSION],
+            capabilities=ServerCapabilities(),
+            server_info=Implementation(name="stub", version="0"),
+        )
+    )
+
+
+async def _noop_handler(params: _EventParams) -> None:
+    raise NotImplementedError  # construction-only tests never deliver
+
+
+def test_duplicate_binding_method_rejected() -> None:
+    """SDK-defined: two bindings on one wire method cannot be routed apart, so construction fails."""
+    client_side, _ = create_direct_dispatcher_pair()
+    binding = NotificationBinding(method=_VENDOR_METHOD, params_type=_EventParams, handler=_noop_handler)
+
+    with pytest.raises(ValueError) as exc_info:
+        ClientSession(dispatcher=client_side, notification_bindings=[binding, binding])
+
+    assert str(exc_info.value) == "duplicate notification binding for method 'notifications/vendor/task_done'"
+
+
+@pytest.mark.anyio
+async def test_bound_vendor_notifications_are_delivered_in_order() -> None:
+    """SDK-defined: one consumer per binding delivers events in the order the server sent them."""
+    delivered: list[int] = []
+    done = anyio.Event()
+
+    async def on_event(params: _EventParams) -> None:
+        delivered.append(params.seq)
+        if params.seq == 3:
+            done.set()
+
+    client_side, server_side = create_direct_dispatcher_pair()
+    binding = NotificationBinding(method=_VENDOR_METHOD, params_type=_EventParams, handler=on_event)
+    session = ClientSession(dispatcher=client_side, notification_bindings=[binding])
+    with anyio.fail_after(5):
+        async with anyio.create_task_group() as tg:
+            await tg.start(server_side.run, _server_on_request, _server_on_notify)
+            async with session:
+                _adopt_modern(session)
+                for seq in (1, 2, 3):
+                    await server_side.notify(_VENDOR_METHOD, {"seq": seq})
+                await done.wait()
+            server_side.close()
+
+    assert delivered == [1, 2, 3]
+
+
+@pytest.mark.anyio
+async def test_binding_handler_may_do_session_io_without_deadlock() -> None:
+    """SDK-defined: delivery is spawn-decoupled, so a handler may await session I/O without deadlock."""
+    pongs: list[EmptyResult] = []
+    done = anyio.Event()
+
+    client_side, server_side = create_direct_dispatcher_pair()
+
+    async def on_event(params: _EventParams) -> None:
+        pongs.append(await session.send_ping())
+        done.set()
+
+    binding = NotificationBinding(method=_VENDOR_METHOD, params_type=_EventParams, handler=on_event)
+    session = ClientSession(dispatcher=client_side, notification_bindings=[binding])
+    with anyio.fail_after(5):
+        async with anyio.create_task_group() as tg:
+            await tg.start(server_side.run, _server_on_request, _server_on_notify)
+            async with session:
+                _adopt_modern(session)
+                await server_side.notify(_VENDOR_METHOD, {"seq": 1})
+                await done.wait()
+            server_side.close()
+
+    assert pongs == [EmptyResult()]
+
+
+@pytest.mark.anyio
+async def test_overflow_drops_oldest_event_with_a_warning(caplog: pytest.LogCaptureFixture) -> None:
+    """SDK-defined: on overflow the bounded FIFO drops the oldest queued event with a
+    warning; everything still queued delivers in order."""
+    delivered: list[int] = []
+    consumer_blocked = anyio.Event()
+    gate = anyio.Event()
+    done = anyio.Event()
+    last_seq = _NOTIFICATION_QUEUE_SIZE + 1
+
+    async def on_event(params: _EventParams) -> None:
+        delivered.append(params.seq)
+        if params.seq == 0:
+            consumer_blocked.set()
+            await gate.wait()
+        if params.seq == last_seq:
+            done.set()
+
+    client_side, server_side = create_direct_dispatcher_pair()
+    binding = NotificationBinding(method=_VENDOR_METHOD, params_type=_EventParams, handler=on_event)
+    session = ClientSession(dispatcher=client_side, notification_bindings=[binding])
+    with anyio.fail_after(5):
+        async with anyio.create_task_group() as tg:
+            await tg.start(server_side.run, _server_on_request, _server_on_notify)
+            async with session:
+                _adopt_modern(session)
+                await server_side.notify(_VENDOR_METHOD, {"seq": 0})
+                await consumer_blocked.wait()
+                for seq in range(1, last_seq + 1):
+                    await server_side.notify(_VENDOR_METHOD, {"seq": seq})
+                gate.set()
+                await done.wait()
+            server_side.close()
+
+    assert delivered == [0, *range(2, last_seq + 1)]
+    assert caplog.text.count(f"notification queue for {_VENDOR_METHOD!r} is full") == 1
+
+
+@pytest.mark.anyio
+async def test_invalid_params_are_warned_and_dropped_without_reaching_handler(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """SDK-defined: params failing the binding's model are warned and dropped; later valid events deliver."""
+    delivered: list[int] = []
+    done = anyio.Event()
+
+    async def on_event(params: _EventParams) -> None:
+        delivered.append(params.seq)
+        done.set()
+
+    client_side, server_side = create_direct_dispatcher_pair()
+    binding = NotificationBinding(method=_VENDOR_METHOD, params_type=_EventParams, handler=on_event)
+    session = ClientSession(dispatcher=client_side, notification_bindings=[binding])
+    with anyio.fail_after(5):
+        async with anyio.create_task_group() as tg:
+            await tg.start(server_side.run, _server_on_request, _server_on_notify)
+            async with session:
+                _adopt_modern(session)
+                await server_side.notify(_VENDOR_METHOD, {"bogus": "no seq"})
+                await server_side.notify(_VENDOR_METHOD, {"seq": 1})
+                await done.wait()
+            server_side.close()
+
+    assert delivered == [1]
+    assert f"Failed to validate notification: {_VENDOR_METHOD}" in caplog.text
+
+
+@pytest.mark.anyio
+async def test_unbound_vendor_notification_keeps_the_debug_drop(caplog: pytest.LogCaptureFixture) -> None:
+    """SDK-defined: a vendor method with no binding keeps the debug-log-and-drop behaviour."""
+    caplog.set_level(logging.DEBUG, logger="client")
+
+    client_side, server_side = create_direct_dispatcher_pair()
+    binding = NotificationBinding(method=_VENDOR_METHOD, params_type=_EventParams, handler=_noop_handler)
+    session = ClientSession(dispatcher=client_side, notification_bindings=[binding])
+    with anyio.fail_after(5):
+        async with anyio.create_task_group() as tg:
+            await tg.start(server_side.run, _server_on_request, _server_on_notify)
+            async with session:
+                _adopt_modern(session)
+                await server_side.notify("notifications/vendor/unbound", {"seq": 1})
+            server_side.close()
+
+    assert f"dropped 'notifications/vendor/unbound': not defined at {LATEST_MODERN_VERSION}" in caplog.text
+
+
+@pytest.mark.anyio
+async def test_core_known_method_never_reaches_binding_and_warns_once_at_adopt(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """SDK-defined: a binding for a core-known method never fires and warns once at
+    adopt(); the typed callback still runs."""
+    logged: list[types.LoggingMessageNotificationParams] = []
+
+    async def logging_callback(params: types.LoggingMessageNotificationParams) -> None:
+        logged.append(params)
+
+    async def on_message(params: BaseModel) -> None:
+        raise NotImplementedError  # structurally unreachable: core parses the method first
+
+    client_side, server_side = create_direct_dispatcher_pair()
+    binding = NotificationBinding(method="notifications/message", params_type=BaseModel, handler=on_message)
+    session = ClientSession(dispatcher=client_side, logging_callback=logging_callback, notification_bindings=[binding])
+    with anyio.fail_after(5):
+        async with anyio.create_task_group() as tg:
+            await tg.start(server_side.run, _server_on_request, _server_on_notify)
+            async with session:
+                _adopt_modern(session)
+                # In-process notify() awaits _on_notify inline, so the typed callback has already run.
+                await server_side.notify("notifications/message", {"level": "info", "data": "hello"})
+            server_side.close()
+
+    assert [params.data for params in logged] == ["hello"]
+    # The bound handler never ran; a delivery would have logged its NotImplementedError.
+    assert "notification binding handler" not in caplog.text
+    expected = f"notification binding for 'notifications/message' will never fire at {LATEST_MODERN_VERSION}"
+    assert caplog.text.count(expected) == 1
+
+
+@pytest.mark.anyio
+async def test_handler_exception_is_contained_and_later_events_deliver(caplog: pytest.LogCaptureFixture) -> None:
+    """SDK-defined: a raising handler costs only that delivery; later events still deliver."""
+    delivered: list[int] = []
+    done = anyio.Event()
+
+    async def on_event(params: _EventParams) -> None:
+        if params.seq == 1:
+            raise ValueError("handler boom")
+        delivered.append(params.seq)
+        done.set()
+
+    client_side, server_side = create_direct_dispatcher_pair()
+    binding = NotificationBinding(method=_VENDOR_METHOD, params_type=_EventParams, handler=on_event)
+    session = ClientSession(dispatcher=client_side, notification_bindings=[binding])
+    with anyio.fail_after(5):
+        async with anyio.create_task_group() as tg:
+            await tg.start(server_side.run, _server_on_request, _server_on_notify)
+            async with session:
+                _adopt_modern(session)
+                await server_side.notify(_VENDOR_METHOD, {"seq": 1})
+                await server_side.notify(_VENDOR_METHOD, {"seq": 2})
+                await done.wait()
+            server_side.close()
+
+    assert delivered == [2]
+    assert f"notification binding handler for {_VENDOR_METHOD!r} raised" in caplog.text
+
+
+@pytest.mark.anyio
+async def test_binding_delivery_works_without_adopt() -> None:
+    """SDK-defined: bindings deliver pre-handshake, under the default version tables."""
+    delivered: list[int] = []
+    done = anyio.Event()
+
+    async def on_event(params: _EventParams) -> None:
+        delivered.append(params.seq)
+        done.set()
+
+    client_side, server_side = create_direct_dispatcher_pair()
+    binding = NotificationBinding(method=_VENDOR_METHOD, params_type=_EventParams, handler=on_event)
+    session = ClientSession(dispatcher=client_side, notification_bindings=[binding])
+    with anyio.fail_after(5):
+        async with anyio.create_task_group() as tg:
+            await tg.start(server_side.run, _server_on_request, _server_on_notify)
+            async with session:
+                await server_side.notify(_VENDOR_METHOD, {"seq": 7})
+                await done.wait()
+            server_side.close()
+
+    assert delivered == [7]

tests/client/test_session_promotions.py

@@ -0,0 +1,66 @@
+"""`dispatch_input_request` and `validate_tool_result` are public `ClientSession` API."""
+
+import mcp_types as types
+import pytest
+from mcp_types import (
+    CallToolResult,
+    ErrorData,
+    ListRootsResult,
+    ListToolsResult,
+    PaginatedRequestParams,
+    Tool,
+)
+
+from mcp.client.client import Client
+from mcp.client.session import ClientRequestContext, ClientSession
+from mcp.server import Server, ServerRequestContext
+from mcp.shared.direct_dispatcher import create_direct_dispatcher_pair
+
+
+@pytest.mark.anyio
+async def test_dispatch_input_request_routes_through_the_callback_table() -> None:
+    expected = ListRootsResult(roots=[])
+
+    async def list_roots(context: ClientRequestContext) -> ListRootsResult:
+        return expected
+
+    client_side, _server_side = create_direct_dispatcher_pair()
+    session = ClientSession(dispatcher=client_side, list_roots_callback=list_roots)
+    ctx = ClientRequestContext(session=session, request_id="r-1")
+    response = await session.dispatch_input_request(ctx, types.ListRootsRequest())
+    assert response is expected
+
+
+@pytest.mark.anyio
+async def test_dispatch_input_request_returns_error_data_on_refusal() -> None:
+    """With no callback registered, refusal comes back as `ErrorData`, not a raise."""
+    client_side, _server_side = create_direct_dispatcher_pair()
+    session = ClientSession(dispatcher=client_side)
+    ctx = ClientRequestContext(session=session, request_id="r-1")
+    response = await session.dispatch_input_request(ctx, types.ListRootsRequest())
+    assert isinstance(response, ErrorData)
+    assert response.code == types.INVALID_REQUEST
+
+
+def _make_server(output_schema: dict[str, object]) -> Server:
+    async def on_list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult:
+        return ListToolsResult(tools=[Tool(name="t", input_schema={"type": "object"}, output_schema=output_schema)])
+
+    return Server("test-server", on_list_tools=on_list_tools)
+
+
+@pytest.mark.anyio
+async def test_validate_tool_result_passes_a_conforming_result() -> None:
+    server = _make_server({"type": "object", "properties": {"x": {"type": "integer"}}, "required": ["x"]})
+    async with Client(server) as client:
+        # The session fetches the listing itself when the tool isn't cached yet.
+        await client.session.validate_tool_result("t", CallToolResult(content=[], structured_content={"x": 1}))
+
+
+@pytest.mark.anyio
+async def test_validate_tool_result_raises_on_schema_mismatch() -> None:
+    server = _make_server({"type": "object", "properties": {"x": {"type": "integer"}}, "required": ["x"]})
+    async with Client(server) as client:
+        # Stable SDK prefix only: the message tail is jsonschema text that shifts with the dependency.
+        with pytest.raises(RuntimeError, match="Invalid structured content returned by tool t"):
+            await client.session.validate_tool_result("t", CallToolResult(content=[], structured_content={"x": "no"}))