Fold ClientExtension instances into Client

Client.extensions becomes Sequence[ClientExtension] | None: instances
are validated and read once at construction (identifier guard and
grammar, duplicate identifiers, cross-extension claim and binding
conflicts named by their owning extensions) and folded into the session
as the capability ad, the claims-by-identifier mapping, and the binding
list. call_tool resolves claimed shapes transparently: the retry
closure allows claimed results through the multi-round-trip driver, the
owning claim's resolver finishes the call, and non-error resolver
products get the same output-schema revalidation as the direct path.
The dict form of extensions= is replaced; advertise() covers ad-only
uses, documented in the migration guide. No extensions means a session
constructed byte-identically to before.

Author: maxisbey

docs/migration.md

@@ -469,11 +469,42 @@ extension handler can call `mcp.server.mcpserver.require_client_extension(ctx, i
 to reject a request with the `-32021` (missing required client capability) error
 when the client did not declare the extension.
 
-Clients advertise extension support with the new `Client(extensions=...)` /
-`ClientSession(extensions=...)` argument, mirrored into `ClientCapabilities.extensions`.
-The extensions capability map is negotiated over `server/discover` (modern path);
-a legacy `initialize` handshake does not carry it. Extensions are off by default
-and never alter behaviour unless registered.
+On the client, `Client(extensions=...)` takes a sequence of
+`mcp.client.ClientExtension` instances. A client extension contributes its
+capability ad (mirrored into `ClientCapabilities.extensions`), its result
+claims (extra `tools/call` result shapes that `Client.call_tool` resolves
+transparently through the claim's resolver), and its notification bindings
+(handlers for vendor server notifications). The capability map rides
+`server/discover` and every modern request's `_meta` envelope; a legacy
+`initialize` handshake carries only the claim-less identifiers, since claimed
+result shapes cannot be delivered on a legacy wire. Extensions are off by
+default and never alter behaviour unless registered. (The low-level
+`ClientSession(extensions=...)` keeps the raw identifier-to-settings dict.)
+
+Changed in the v2 pre-releases: earlier alphas took
+`Client(extensions={identifier: settings})`, an advertisement-only dict.
+Extensions now contribute behaviour — claims and notification handlers — not
+just an ad, and a sequence of declaration objects is the shape that can carry
+that. An ad-only entry becomes an `advertise()` call:
+
+**Before (v2 alphas):**
+
+```python
+client = Client(server, extensions={"com.example/ui": {"mimeTypes": [...]}})
+```
+
+**After:**
+
+```python
+from mcp.client import advertise
+
+client = Client(server, extensions=[advertise("com.example/ui", {"mimeTypes": [...]})])
+```
+
+`advertise()` is only for identifiers with no client-side behaviour.
+For a behavioural extension — e.g. tasks, once its extension ships — construct
+that extension's object instead; advertising an identifier you do not
+implement asserts wire support you don't have.
 
 ### `McpError` renamed to `MCPError`
 

docs_src/apps/tutorial001.py

@@ -1,4 +1,5 @@
 from mcp import Client
+from mcp.client import advertise
 from mcp.server.apps import APP_MIME_TYPE, EXTENSION_ID, Apps, client_supports_apps
 from mcp.server.mcpserver import MCPServer
 from mcp.server.mcpserver.context import Context
@@ -32,7 +33,7 @@ def get_time(ctx: Context) -> str:
 
 
 async def main() -> None:
-    async with Client(mcp, extensions={EXTENSION_ID: {"mimeTypes": [APP_MIME_TYPE]}}) as client:
+    async with Client(mcp, extensions=[advertise(EXTENSION_ID, {"mimeTypes": [APP_MIME_TYPE]})]) as client:
         result = await client.call_tool("get_time", {})
         print(result.content)
         # [TextContent(text='2026-06-26T12:00:00Z')]

docs_src/extensions/tutorial004.py

@@ -5,6 +5,7 @@
 from pydantic import Field
 
 from mcp import Client
+from mcp.client import advertise
 from mcp.server.context import ServerRequestContext
 from mcp.server.extension import Extension, MethodBinding
 from mcp.server.mcpserver import MCPServer, require_client_extension
@@ -51,7 +52,7 @@ def methods(self) -> Sequence[MethodBinding]:
 
 
 async def main() -> None:
-    async with Client(mcp, extensions={EXTENSION_ID: {}}) as client:
+    async with Client(mcp, extensions=[advertise(EXTENSION_ID)]) as client:
         request = SearchRequest(params=SearchParams(query="mcp", limit=3))
         result = await client.session.send_request(request, SearchResult)
         print(result.items)

examples/stories/apps/README.md

@@ -26,7 +26,7 @@ uv run python -m stories.apps.client --http
   `text/html;profile=mcp-app`.
 - `server.py` `client_supports_apps(ctx)` — SEP-2133 graceful degradation: a
   client that did not negotiate Apps gets a text-only result.
-- `client.py` `Client(target, extensions={...})` — the client advertises Apps
+- `client.py` `Client(target, extensions=[advertise(...)])` — the client advertises Apps
   support so the server returns the UI-enabled result, then reads the tool's
   `_meta.ui.resourceUri` and fetches that resource.
 

examples/stories/apps/client.py

@@ -2,15 +2,17 @@
 
 from mcp_types import TextContent, TextResourceContents
 
-from mcp.client import Client
+from mcp.client import Client, advertise
 from mcp.server.apps import APP_MIME_TYPE, EXTENSION_ID
 from stories._harness import Target, run_client
 
 
 async def main(target: Target, *, mode: str = "auto") -> None:
     # Advertise MCP Apps support so the server returns the UI-enabled result; a
     # client that omits this gets the text-only fallback (graceful degradation).
-    async with Client(target, mode=mode, extensions={EXTENSION_ID: {"mimeTypes": [APP_MIME_TYPE]}}) as client:
+    async with Client(
+        target, mode=mode, extensions=[advertise(EXTENSION_ID, {"mimeTypes": [APP_MIME_TYPE]})]
+    ) as client:
         # The extensions capability map rides `server/discover` (modern only). On a
         # legacy connection (today's stdio) it is absent, so assert it only when present.
         if client.server_capabilities.extensions is not None:

examples/stories/extensions/README.md

@@ -24,7 +24,7 @@ uv run python -m stories.extensions.client --http
   rejects clients that did not declare the extension with `-32021` (missing
   required client capability) and a machine-readable `requiredCapabilities`
   payload.
-- `client.py` `Client(target, extensions={EXTENSION_ID: {}})` — the client-side
+- `client.py` `Client(target, extensions=[advertise(EXTENSION_ID)])` — the client-side
   half of the negotiation; on 2026-07-28 it travels in the per-request `_meta`
   envelope.
 - `client.py` `client.session.send_request(...)` — vendor methods have no

examples/stories/extensions/client.py

@@ -5,7 +5,7 @@
 import mcp_types as types
 from mcp_types import TextContent
 
-from mcp.client import Client
+from mcp.client import Client, advertise
 from stories._harness import Target, run_client
 
 EXTENSION_ID = "com.example/catalog"
@@ -28,7 +28,7 @@ class SearchResult(types.Result):
 async def main(target: Target, *, mode: str = "auto") -> None:
     # Declare the extension client-side so the server's `require_client_extension`
     # gate on `com.example/search` passes.
-    async with Client(target, mode=mode, extensions={EXTENSION_ID: {}}) as client:
+    async with Client(target, mode=mode, extensions=[advertise(EXTENSION_ID)]) as client:
         # The extensions capability map rides `server/discover` (modern only). On a
         # legacy connection it is absent, so assert it only when present.
         if client.server_capabilities.extensions is not None:

src/mcp/client/client.py

@@ -5,7 +5,7 @@
 import hashlib
 import logging
 import uuid
-from collections.abc import Awaitable, Callable, Mapping
+from collections.abc import Awaitable, Callable, Mapping, Sequence
 from contextlib import AsyncExitStack
 from dataclasses import KW_ONLY, dataclass, field
 from typing import Any, Literal, TypeVar, cast
@@ -36,6 +36,7 @@
     ReadResourceResult,
     RequestParamsMeta,
     ResourceTemplateReference,
+    Result,
     ServerCapabilities,
 )
 from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS
@@ -46,6 +47,7 @@
 from mcp.client._probe import negotiate_auto
 from mcp.client._transport import Transport
 from mcp.client.caching import CacheConfig, CacheMode, ClientResponseCache, InMemoryResponseCacheStore
+from mcp.client.extension import ClaimContext, ClientExtension, NotificationBinding, ResultClaim
 from mcp.client.session import (
     ClientRequestContext,
     ClientSession,
@@ -62,6 +64,7 @@
 from mcp.shared.direct_dispatcher import create_direct_dispatcher_pair
 from mcp.shared.dispatcher import Dispatcher, ProgressFnT
 from mcp.shared.exceptions import MCPDeprecationWarning, MCPError
+from mcp.shared.extension import validate_extension_identifier
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
 from mcp.shared.session import RequestResponder
 
@@ -188,6 +191,70 @@ async def _no_inbound_client_notifications(_dctx: Any, _method: str, _params: Ma
     """
 
 
+@dataclass(frozen=True)
+class _FoldedExtensions:
+    """`Client.extensions` instances folded into the shapes `ClientSession` consumes."""
+
+    ad: dict[str, dict[str, Any]] | None
+    claims: dict[str, tuple[ResultClaim[Any], ...]] | None
+    bindings: tuple[NotificationBinding[Any], ...] | None
+    by_model: Mapping[type[Result], ResultClaim[Any]]
+
+
+def _fold_extensions(extensions: Sequence[ClientExtension] | None) -> _FoldedExtensions:
+    """Validate extension instances and fold their contributions, once, at `Client` construction.
+
+    Mirrors the server's consumption-time posture (`MCPServer._apply_extension`): a
+    per-instance identifier is validated here because no class attribute existed to
+    validate at definition time. `settings()` is read exactly once per extension and
+    the returned dict is held by reference. Duplicate `(method, resultType)` claims
+    and duplicate notification methods are rejected here, where both owning extensions
+    can be named — the session's own duplicate checks know only methods and tags.
+    """
+    if not extensions:
+        return _FoldedExtensions(ad=None, claims=None, bindings=None, by_model={})
+    ad: dict[str, dict[str, Any]] = {}
+    claims: dict[str, tuple[ResultClaim[Any], ...]] = {}
+    bindings: list[NotificationBinding[Any]] = []
+    by_model: dict[type[Result], ResultClaim[Any]] = {}
+    claim_owners: dict[tuple[str, str], str] = {}
+    binding_owners: dict[str, str] = {}
+    for extension in extensions:
+        identifier = getattr(extension, "identifier", None)
+        if identifier is None:
+            raise ValueError(
+                f"{type(extension).__name__} has no `identifier`; a ClientExtension must set the "
+                "`identifier` class attribute (or assign one in `__init__`) before it can be used"
+            )
+        validate_extension_identifier(identifier, owner=type(extension).__name__)
+        if identifier in ad:
+            raise ValueError(f"extension identifier {identifier!r} is passed more than once")
+        ad[identifier] = extension.settings()
+        extension_claims = tuple(extension.claims())
+        for claim in extension_claims:
+            key = (claim.method, claim.result_type)
+            if key in claim_owners:
+                raise ValueError(
+                    f"extensions {claim_owners[key]!r} and {identifier!r} both claim {claim.method!r} "
+                    f"resultType {claim.result_type!r}; a wire tag can have only one resolver"
+                )
+            claim_owners[key] = identifier
+            # Collision-free by construction: a model's `result_type` Literal pins it to
+            # exactly one tag, and each (method, tag) pair has exactly one owner.
+            by_model[claim.model] = claim
+        if extension_claims:
+            claims[identifier] = extension_claims
+        for binding in extension.notifications():
+            if binding.method in binding_owners:
+                raise ValueError(
+                    f"extensions {binding_owners[binding.method]!r} and {identifier!r} both bind "
+                    f"notification method {binding.method!r}; a method can have only one observer"
+                )
+            binding_owners[binding.method] = identifier
+            bindings.append(binding)
+    return _FoldedExtensions(ad=ad, claims=claims or None, bindings=tuple(bindings) or None, by_model=by_model)
+
+
 @dataclass
 class Client:
     """A high-level MCP client for connecting to MCP servers.
@@ -268,9 +335,16 @@ async def main():
     `read_resource` give up. Use `client.session.<method>(..., allow_input_required=True)`
     to drive the loop manually instead."""
 
-    extensions: dict[str, dict[str, Any]] | None = None
-    """SEP-2133 extension support to advertise under `ClientCapabilities.extensions`
-    (identifier -> settings), e.g. `{"io.modelcontextprotocol/ui": {"mimeTypes": [...]}}`."""
+    extensions: Sequence[ClientExtension] | None = None
+    """Opt-in client extensions (SEP-2133).
+
+    Each instance contributes its capability ad (advertised under
+    `ClientCapabilities.extensions`), its result claims (extra `tools/call` result
+    shapes that `call_tool` resolves transparently through the claim's resolver),
+    and its notification bindings. For an ad-only entry — an identifier plus
+    settings, no client-side behaviour — use `mcp.client.advertise(identifier,
+    settings)`. Each extension's `settings()` is read once, at construction; the
+    returned dict is held by reference."""
 
     cache: CacheConfig | Literal[False] | None = None
     """Client-side response caching for the SEP-2549 cacheable methods (2026-07-28).
@@ -286,6 +360,7 @@ async def main():
     _exit_stack: AsyncExitStack | None = field(init=False, default=None)
     _connect: _Connector = field(init=False, repr=False, compare=False)
     _response_cache: ClientResponseCache | None = field(init=False, default=None, repr=False, compare=False)
+    _folded_extensions: _FoldedExtensions = field(init=False, repr=False, compare=False)
 
     def __post_init__(self) -> None:
         if self.mode not in ("legacy", "auto") and self.mode not in MODERN_PROTOCOL_VERSIONS:
@@ -298,6 +373,8 @@ def __post_init__(self) -> None:
                 f"mode must be 'legacy', 'auto', or one of {list(MODERN_PROTOCOL_VERSIONS)}; got {self.mode!r}{hint}"
             )
 
+        self._folded_extensions = _fold_extensions(self.extensions)
+
         srv = self.server
         if isinstance(srv, MCPServer):
             srv = srv._lowlevel_server  # pyright: ignore[reportPrivateUsage]
@@ -348,7 +425,9 @@ async def _build_session(self, exit_stack: AsyncExitStack) -> ClientSession:
             message_handler=message_handler,
             client_info=self.client_info,
             elicitation_callback=self.elicitation_callback,
-            extensions=self.extensions,
+            extensions=self._folded_extensions.ad,
+            result_claims=self._folded_extensions.claims,
+            notification_bindings=self._folded_extensions.bindings,
         )
 
     async def __aenter__(self) -> Client:
@@ -611,6 +690,13 @@ async def call_tool(
         persist `request_state` across process restarts — use
         `client.session.call_tool(..., allow_input_required=True)`.
 
+        If the server returns a result shape claimed by one of this client's
+        `extensions`, the owning claim's resolver finishes the call and its
+        `CallToolResult` is returned — the claimed shape never surfaces here.
+        Resolver exceptions propagate as-is; the extension owns its error
+        vocabulary. To receive the claimed shape yourself, use
+        `client.session.call_tool(..., allow_claimed=True)`.
+
         Args:
             name: The name of the tool to call.
             arguments: Arguments to pass to the tool.
@@ -629,7 +715,7 @@ async def call_tool(
             MCPError: A callback returned `ErrorData` for an embedded input request.
         """
 
-        async def retry(r: InputResponses | None, s: str | None) -> CallToolResult | InputRequiredResult:
+        async def retry(r: InputResponses | None, s: str | None) -> CallToolResult | InputRequiredResult | Result:
             return await self.session.call_tool(
                 name,
                 arguments,
@@ -639,9 +725,28 @@ async def retry(r: InputResponses | None, s: str | None) -> CallToolResult | Inp
                 request_state=s,
                 meta=meta,
                 allow_input_required=True,
+                # The driver's retry leg must also admit claimed shapes — the spec
+                # resolves multi-round-trip input before a claimed result, so a claim
+                # may terminate any round, not just the first.
+                allow_claimed=True,
             )
 
-        return await self._drive_input_required(await retry(input_responses, request_state), retry)
+        result = await self._drive_input_required(await retry(input_responses, request_state), retry)
+        if isinstance(result, CallToolResult):
+            return result
+        # Only claimed shapes escape the parse (`_drive_input_required` never returns an
+        # `InputRequiredResult`), so the lookup is total; a KeyError here is an SDK bug.
+        claim = self._folded_extensions.by_model[type(result)]
+        final = await claim.resolve(
+            result,
+            ClaimContext(session=self.session, tool_name=name, read_timeout_seconds=read_timeout_seconds),
+        )
+        if not final.is_error:
+            # The resolver's product gets the same output-schema revalidation as the
+            # direct path (`ClientSession.call_tool`'s own guard); isError results
+            # must not raise, also matching the direct path.
+            await self.session.validate_tool_result(name, final)
+        return final
 
     async def list_prompts(
         self,