Expose typed client extension APIs and tighten Skills validation

Author: Kludex

docs/advanced/extensions.md

@@ -190,6 +190,30 @@ that did not declare it (error -32021), and a claimed shape from a server that
 skips the gate fails validation, exactly as the spec requires for an
 unrecognized `resultType`. Off by default, on both ends of the wire.
 
+An extension can also expose methods of its own. Pass its type to `client.extension()`
+after connecting to get the API bound to that connection:
+
+```python
+import anyio
+
+from mcp import Client
+from mcp.client.skills import Skills
+
+
+async def main() -> None:
+    async with Client("http://localhost:8000/mcp", extensions=[Skills()]) as client:
+        for skill in await client.extension(Skills).list_skills():
+            print(skill.uri)
+
+
+if __name__ == "__main__":
+    anyio.run(main)
+```
+
+`client.extension(Skills)` returns the type produced by `Skills.bind(session)`. Your own
+extension can define the same hook. The client raises `ValueError` when the type was not
+registered and `RuntimeError` when it is not connected.
+
 To advertise an identifier with **no** client-side behaviour (the server gates on
 the capability, the client does nothing, as in the search client above), use
 `advertise()`:

docs/advanced/skills.md

@@ -49,14 +49,14 @@ And that's it. `Skills(list_skills=..., get_skill=...)` is all a server needs;
 ## Fetching a skill
 
 On the client side, `Skills` is a [`ClientExtension`](extensions.md). You register it the same way
-you register any other one — by passing it to `Client(extensions=[...])` — and then call `bind` to
+you register any other one — by passing it to `Client(extensions=[...])` — and then call `extension` to
 get the verbs tied to that connection:
 
 ```python title="client.py" hl_lines="9-11"
 --8<-- "docs_src/skills/tutorial001_client.py"
 ```
 
-`skills.bind(client)` hands you a `BoundSkills`, and its methods are the SEP-2640 verbs:
+`client.extension(Skills)` hands you a `BoundSkills`, and its methods are the SEP-2640 verbs:
 
 * `list_skills` and `read_directory` follow `nextCursor` to completion, so a single call gives you
   every page's skills or resources.
@@ -124,8 +124,9 @@ setting.
 In protocol version `2026-07-28` and later, `skills/list` and `skills/get` results carry the base
 protocol's caching fields, [`ttlMs` and `cacheScope`](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549) —
 the same freshness hint `tools/list`, `resources/list`, and `resources/read` carry. `Skills` fills
-`cacheScope` with `"public"` when your handler leaves it unset, and omits both fields entirely on an
-older connection. So you don't have to branch on protocol version yourself.
+`cacheScope` with `"private"` when your handler leaves it unset, and omits both fields entirely on an
+older connection. Set `cache_scope="public"` only when the result is the same for every user.
+You don't have to branch on protocol version yourself.
 
 ## What this SDK doesn't do
 

docs_src/skills/tutorial001_client.py

@@ -6,9 +6,8 @@
 
 
 async def main() -> None:
-    skills = Skills()
-    async with Client("http://localhost:8000/mcp", extensions=[skills]) as client:
-        catalog = skills.bind(client)
+    async with Client("http://localhost:8000/mcp", extensions=[Skills()]) as client:
+        catalog = client.extension(Skills)
         for skill in await catalog.list_skills():
             print(skill.uri, skill.frontmatter["description"])
 

src/mcp/client/client.py

@@ -49,7 +49,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.extension import ClaimContext, ClientExtension, ClientExtensionBinding, NotificationBinding, ResultClaim
 from mcp.client.session import (
     ClientRequestContext,
     ClientSession,
@@ -87,6 +87,7 @@
 _T = TypeVar("_T")
 _ResultT = TypeVar("_ResultT")
 _CacheableT = TypeVar("_CacheableT", bound=CacheableResult)
+_BoundT = TypeVar("_BoundT")
 
 _Connector = Callable[[AsyncExitStack, ConnectMode, bool], Awaitable["Dispatcher[Any]"]]
 """Resolved at ``__post_init__`` from the shape of ``server`` alone: enter whatever resources
@@ -376,6 +377,7 @@ async def main():
     _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)
+    _registered_extensions: tuple[ClientExtension, ...] = 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:
@@ -389,6 +391,7 @@ def __post_init__(self) -> None:
             )
 
         self._folded_extensions = _fold_extensions(self.extensions)
+        self._registered_extensions = tuple(self.extensions or ())
 
         srv = self.server
         if isinstance(srv, MCPServer):
@@ -493,6 +496,19 @@ def session(self) -> ClientSession:
             raise RuntimeError("Client must be used within an async context manager")
         return self._session
 
+    def extension(self, extension_type: type[ClientExtensionBinding[_BoundT]]) -> _BoundT:
+        """Return the typed API of a registered extension for this connection.
+
+        Raises:
+            RuntimeError: If the client is not connected.
+            ValueError: If no extension of this type was registered.
+        """
+        session = self.session
+        for extension in self._registered_extensions:
+            if isinstance(extension, extension_type):
+                return cast(ClientExtensionBinding[_BoundT], extension).bind(session)
+        raise ValueError(f"client extension {extension_type.__name__!r} is not registered")
+
     # TODO(maxisbey): the by-construction shape is for __aenter__ to return a connected-view
     # type whose protocol_version/server_capabilities are non-Optional fields,
     # eliminating these guards (and the one in .session). Same family as resolving the

src/mcp/client/extension.py

@@ -15,6 +15,7 @@
 from mcp_types.version import MODERN_PROTOCOL_VERSIONS
 from pydantic import AliasChoices, AliasPath, BaseModel
 from pydantic.fields import FieldInfo
+from typing_extensions import Protocol
 
 from mcp.shared.extension import validate_extension_identifier
 
@@ -24,6 +25,7 @@
 __all__ = [
     "ClaimContext",
     "ClientExtension",
+    "ClientExtensionBinding",
     "NotificationBinding",
     "ResultClaim",
     "UnexpectedClaimedResult",
@@ -54,6 +56,15 @@ def _wire_keys(name: str, field: FieldInfo) -> frozenset[str]:
 
 ClaimedT = TypeVar("ClaimedT", bound=Result)
 NotifyParamsT = TypeVar("NotifyParamsT", bound=BaseModel)
+BoundT_co = TypeVar("BoundT_co", covariant=True)
+
+
+class ClientExtensionBinding(Protocol[BoundT_co]):
+    """An extension that exposes a typed API for one connected client."""
+
+    def bind(self, session: ClientSession) -> BoundT_co:
+        """Return the extension API bound to `session`."""
+        ...
 
 
 @dataclass(frozen=True, kw_only=True)

src/mcp/client/skills.py

@@ -2,14 +2,14 @@
 
 `Skills` is an opt-in [`ClientExtension`](../advanced/extensions.md) for talking
 to a skills catalog server. Register it with `Client(extensions=[Skills()])`,
-then call `bind(client)` for the SEP-2640 verbs — `list_skills`, `get_skill`,
+then call `client.extension(Skills)` for the SEP-2640 verbs — `list_skills`, `get_skill`,
 `read_skill_uri`, and `read_directory` — tied to that connection:
 
-    async with Client("http://localhost:8000/mcp", extensions=[skills := Skills()]) as client:
-        for skill in await skills.bind(client).list_skills():
+    async with Client("http://localhost:8000/mcp", extensions=[Skills()]) as client:
+        for skill in await client.extension(Skills).list_skills():
             print(skill.uri, skill.frontmatter["description"])
 
-`bind(client)` returns a `BoundSkills`. Its catalog verbs — `list_skills`,
+`client.extension(Skills)` returns a `BoundSkills`. Its catalog verbs — `list_skills`,
 `get_skill`, and `read_directory` — check that the server advertises the
 extension and validate its response; `list_skills` and `read_directory` follow
 `nextCursor` to completion, so one call returns every page's results.
@@ -19,8 +19,6 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
-
 from mcp_types import ReadResourceResult, Resource
 
 from mcp.client.extension import ClientExtension
@@ -41,35 +39,28 @@
 )
 from mcp.shared.skills import verify_skill_resource as verify_skill_resource
 
-if TYPE_CHECKING:
-    from mcp.client.client import Client
-
 __all__ = ["BoundSkills", "Skills", "verify_skill_resource"]
 
 
 class Skills(ClientExtension):
-    """The client-side Skills extension: register, then `bind` for typed verbs.
+    """The client-side Skills extension: register, then access its typed verbs.
 
     Pass an instance to `Client(extensions=[Skills()])` — this advertises
     `io.modelcontextprotocol/skills` under the client's capabilities — and call
-    `bind(client)` once the client is connected for a `BoundSkills` handle.
+    `client.extension(Skills)` once connected for a `BoundSkills` handle.
     """
 
     identifier = EXTENSION_ID
 
-    def bind(self, client: Client) -> BoundSkills:
-        """Return the SEP-2640 verbs bound to `client`'s connected session.
-
-        Raises:
-            RuntimeError: If `client` has not entered its `async with` block yet.
-        """
-        return BoundSkills(client.session)
+    def bind(self, session: ClientSession) -> BoundSkills:
+        """Return the SEP-2640 verbs bound to `session`."""
+        return BoundSkills(session)
 
 
 class BoundSkills:
     """The SEP-2640 verbs bound to one connected session.
 
-    Obtain it from `Skills.bind(client)`. The catalog verbs — `list_skills`,
+    Obtain it from `client.extension(Skills)`. The catalog verbs — `list_skills`,
     `get_skill`, and `read_directory` — check that the server advertises the
     extension and validate its response against the SEP-2640 conformance rules
     before returning; `list_skills` and `read_directory` also follow

src/mcp/server/skills.py

@@ -162,11 +162,9 @@ def _finalize_cacheable(result: CacheableResult, protocol_version: str) -> Handl
     `skills/list` and `skills/get` are extension methods, so — unlike a core spec
     method — the runner's per-version surface sieve never runs on their results;
     nothing else strips these fields for a legacy connection. `CacheableResult`
-    defaults to `cache_scope="private"`; SEP-2640 calls for `"public"` when unset.
+    defaults to `cache_scope="private"`, keeping user-specific entries out of shared caches.
     """
     if protocol_version in MODERN_PROTOCOL_VERSIONS:
-        if "cache_scope" not in result.model_fields_set:
-            result = result.model_copy(update={"cache_scope": "public"})
         return result
     dumped = result.model_dump(by_alias=True, mode="json", exclude_none=True)
     dumped.pop("ttlMs", None)

src/mcp/shared/skills.py

@@ -275,16 +275,15 @@ def validate_directory_result(uri: str, result: ReadDirectoryResult) -> None:
     """Validate that each entry in `result.resources` is a unique direct child of `uri`.
 
     Checks containment and shape only — that every listed resource is a direct
-    child of `uri` with a unique `uri` and `name`. It cannot confirm the listing
+    child of `uri` with a unique `uri`. It cannot confirm the listing
     is exhaustive, since it has no independent view of the directory's contents.
 
     Raises:
         ValueError: If `uri` is malformed, or any entry is not a direct child,
-            or two entries share a `uri` or `name`.
+            or two entries share a `uri`.
     """
     scheme, netloc, parent_path = parse_directory_uri(uri)
     seen_uris: set[str] = set()
-    seen_names: set[str] = set()
     prefix = parent_path.rstrip("/") + "/" if parent_path.rstrip("/") else "/"
     for resource in result.resources:
         child = urlsplit(resource.uri)
@@ -295,10 +294,9 @@ def validate_directory_result(uri: str, result: ReadDirectoryResult) -> None:
         relative = child.path.removeprefix(prefix)
         if relative == child.path or not relative or "/" in relative or relative in (".", ".."):
             raise ValueError(f"resource {resource.uri!r} is not a direct child of directory {uri!r}")
-        if resource.uri in seen_uris or resource.name in seen_names:
+        if resource.uri in seen_uris:
             raise ValueError(f"directory {uri!r} contains a duplicate child {resource.uri!r}")
         seen_uris.add(resource.uri)
-        seen_names.add(resource.name)
 
 
 def verify_skill_resource(skill: Skill, uri: str, content: bytes) -> None:

tests/client/test_client_extensions.py

@@ -17,7 +17,7 @@
 
 from mcp.client import ClaimContext, ClientExtension, NotificationBinding, ResultClaim, advertise
 from mcp.client.client import Client
-from mcp.client.session import ClientRequestContext, _CallToolResultAdapter
+from mcp.client.session import ClientRequestContext, ClientSession, _CallToolResultAdapter
 from mcp.server import Server, ServerRequestContext
 from mcp.server.context import CallNext, HandlerResult
 from mcp.server.extension import Extension
@@ -59,6 +59,13 @@ def claims(self) -> Sequence[ResultClaim[Any]]:
         return [ResultClaim(result_type="voucher", model=VoucherResult, resolve=self._resolve)]
 
 
+class _SessionExtension(ClientExtension):
+    identifier = "com.example/session"
+
+    def bind(self, session: ClientSession) -> ClientSession:
+        return session
+
+
 class _VoucherIssuer(Extension):
     """Server half: rewrites every `tools/call` result into the vendor-claimed shape."""
 
@@ -166,6 +173,30 @@ def test_mapping_extensions_get_the_migration_error() -> None:
     )
 
 
+async def test_extension_returns_a_custom_extensions_typed_binding() -> None:
+    """SDK-defined: custom extensions can expose typed methods through Client.extension."""
+    async with Client(_add_server(), extensions=[advertise("com.example/other"), _SessionExtension()]) as client:
+        bound = client.extension(_SessionExtension)
+        assert_type(bound, ClientSession)
+        assert bound is client.session
+
+
+async def test_extension_rejects_an_unregistered_type() -> None:
+    """SDK-defined: a client cannot bind an extension it did not register."""
+    async with Client(_add_server()) as client:
+        with pytest.raises(ValueError) as exc_info:
+            client.extension(_SessionExtension)
+    assert str(exc_info.value) == snapshot("client extension '_SessionExtension' is not registered")
+
+
+def test_extension_requires_a_connected_client() -> None:
+    """SDK-defined: extension methods require a live session."""
+    client = Client(_add_server(), extensions=[_SessionExtension()])
+    with pytest.raises(RuntimeError) as exc_info:
+        client.extension(_SessionExtension)
+    assert str(exc_info.value) == snapshot("Client must be used within an async context manager")
+
+
 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:

tests/client/test_skills.py

@@ -142,7 +142,7 @@ async def _skills(server: MCPServer) -> AsyncIterator[BoundSkills]:
     """Register the client `Skills` extension, connect, and yield the bound verbs."""
     extension = ClientSkills()
     async with Client(server, extensions=[extension]) as client:
-        yield extension.bind(client)
+        yield client.extension(ClientSkills)
 
 
 async def test_list_skills_follows_next_cursor_to_completion() -> None:
@@ -222,6 +222,29 @@ async def test_read_directory_follows_next_cursor_to_completion() -> None:
     ]
 
 
+async def test_read_directory_accepts_distinct_children_with_the_same_name() -> None:
+    """SEP-2640 Directory Listing: child identity comes from URI, not Resource.name."""
+
+    async def handler(ctx: ServerRequestContext[Any, Any], params: ReadDirectoryParams) -> ReadDirectoryResult:
+        return ReadDirectoryResult(
+            resources=[
+                Resource(uri="skill://git-workflow/references/a.md", name="example"),
+                Resource(uri="skill://git-workflow/references/b.md", name="example"),
+            ]
+        )
+
+    server = MCPServer(
+        "catalog",
+        extensions=[Skills(list_skills=_paginated_list_handler(), get_skill=_get_skill, read_directory=handler)],
+    )
+    async with _skills(server) as skills:
+        resources = await skills.read_directory("skill://git-workflow/references")
+    assert [resource.uri for resource in resources] == [
+        "skill://git-workflow/references/a.md",
+        "skill://git-workflow/references/b.md",
+    ]
+
+
 async def test_read_directory_requires_the_directory_read_setting() -> None:
     """The extension is advertised, but without `directoryRead: true`."""
     async with _skills(_server(with_directory_read=False)) as skills: