🚀 The fast, Pythonic way to build MCP servers and clients.
Add skills discovery to ClientGroup (#6072)
nate nowackfdfa5ef9b684
diff --git a/docs/clients/client-groups.mdx b/docs/clients/client-groups.mdxindex 9f0f3e607..357ac254c 100644--- a/docs/clients/client-groups.mdx+++ b/docs/clients/client-groups.mdx@@ -70,6 +70,25 @@ async with group:The group aggregates names and detects collisions; it never stands between the adapter and the client, so everything a single `Client` supports keeps working per tool.+## List skills across servers++`list_skills()` collects [Skills extension](/servers/skills) entries from every client that opted into it, keyed by server name, since two servers can publish the same skill URI. Clients created without `SkillsClientExtension()`, including those from `from_config`, and servers that don't advertise the extension are left out.++```python+from fastmcp import Client, ClientGroup+from fastmcp.skills import SkillsClientExtension++docs = Client("https://docs.example.com/mcp", extensions=[SkillsClientExtension()])+ops = Client("https://ops.example.com/mcp", extensions=[SkillsClientExtension()])+group = ClientGroup({"docs": docs, "ops": ops})++async with group:+ for server_name, entries in (await group.list_skills()).items():+ for entry in entries:+ print(server_name, entry.uri)+ deploy = await group.get_skill("ops", "skill://deploy/SKILL.md")+```+## Create a group from configuration`ClientGroup.from_config` creates one client per server rather than passing the entire configuration through a proxy. Each entry’s `timeout` applies to that client in milliseconds; `0` disables the request timeout. A FastMCP-specific `mode` field can select the protocol behavior for each server:diff --git a/fastmcp_slim/fastmcp/client/group.py b/fastmcp_slim/fastmcp/client/group.pyindex 18b3f146d..bebc4f5aa 100644--- a/fastmcp_slim/fastmcp/client/group.py+++ b/fastmcp_slim/fastmcp/client/group.py@@ -17,6 +17,7 @@ from mcp.client.caching import CacheModefrom fastmcp.client.client import CallToolResult, Client, ConnectModefrom fastmcp.client.progress import ProgressHandlerfrom fastmcp.mcp_config import MCPConfig+from fastmcp.skills.models import MCPSkillfrom fastmcp.utilities.async_utils import gather@@ -47,7 +48,8 @@ class ClientGroup:"""Coordinate independent clients without introducing a proxy server.Each client retains its own transport, session, capabilities, and protocol- version. The group only combines tool discovery and routes tool calls.+ version. The group only combines tool and skill discovery and routes tool+ calls.Callers may manage the clients' connections themselves or use the group asa convenience context manager. The group's context is reentrant in the@@ -259,6 +261,43 @@ class ClientGroup:self._catalog_loaded = Truereturn tools+ async def list_skills(+ self, *, cache_mode: CacheMode = "use"+ ) -> dict[str, list[MCPSkill]]:+ """List skills from every client that negotiated the Skills extension.++ Results are keyed by server name, since skill URIs are only unique+ within one server. Clients without the extension, because they didn't+ pass `SkillsClientExtension()` or their server doesn't advertise it,+ are left out.+ """+ self._require_connected()+ clients = [+ (name, client)+ for name, client in self._clients.items()+ if client._skills_unavailable_reason() is None+ ]+ skill_lists = await gather(+ client.list_skills(cache_mode=cache_mode) for _, client in clients+ )+ return {+ name: skills for (name, _), skills in zip(clients, skill_lists, strict=True)+ }++ async def get_skill(+ self, server_name: str, uri: str, *, cache_mode: CacheMode = "use"+ ) -> MCPSkill:+ """Fetch one skill entry from the named server."""+ try:+ client = self._clients[server_name]+ except KeyError as exc:+ raise KeyError(f"Unknown ClientGroup server: {server_name!r}") from exc+ if not client.is_connected():+ raise RuntimeError(+ f"ClientGroup client for server {server_name!r} is not connected"+ )+ return await client.get_skill(uri, cache_mode=cache_mode)+async def resolve_tool(self, name: str) -> ToolRoute:"""Resolve a public tool name to its client and upstream identity.diff --git a/fastmcp_slim/fastmcp/client/mixins/skills.py b/fastmcp_slim/fastmcp/client/mixins/skills.pyindex d76f33835..56bd42390 100644--- a/fastmcp_slim/fastmcp/client/mixins/skills.py+++ b/fastmcp_slim/fastmcp/client/mixins/skills.py@@ -37,18 +37,19 @@ def _trace_meta() -> mcp_types.RequestParamsMeta | None:class ClientSkillsMixin:"""Mixin providing SEP-2640 Skills methods for `Client`."""- def _require_skills_extension(self: Client) -> None:+ def _skills_unavailable_reason(self: Client) -> str | None:+ """Why this connection can't send Skills requests, or None if it can."""if self.protocol_version is None:- raise RuntimeError(+ return ("Client is not connected. Use the 'async with client:' context ""manager first.")if self.protocol_version not in MODERN_PROTOCOL_VERSIONS:- raise RuntimeError("The Skills extension requires a modern MCP connection")+ return "The Skills extension requires a modern MCP connection"client_extensions = self._session_kwargs.get("extensions") or {}if SKILLS_EXTENSION_ID not in client_extensions:- raise RuntimeError(+ return ("This client did not opt into the Skills extension; pass ""SkillsClientExtension() in Client(extensions=[...])")@@ -56,7 +57,13 @@ class ClientSkillsMixin:capabilities = self.server_capabilitiesserver_extensions = capabilities.extensions if capabilities else Noneif not server_extensions or SKILLS_EXTENSION_ID not in server_extensions:- raise RuntimeError("The server does not advertise the Skills extension")+ return "The server does not advertise the Skills extension"+ return None++ def _require_skills_extension(self: Client) -> None:+ reason = self._skills_unavailable_reason()+ if reason is not None:+ raise RuntimeError(reason)async def list_skills_mcp(self: Client,diff --git a/tests/client/group/test_skills.py b/tests/client/group/test_skills.pynew file mode 100644index 000000000..decf62998--- /dev/null+++ b/tests/client/group/test_skills.py@@ -0,0 +1,62 @@+import pytest++from fastmcp import Client, ClientGroup, FastMCP+from fastmcp.skills import Skill, SkillsClientExtension+from fastmcp.skills.provider import SkillCatalogProvider+++def skill_server(name: str) -> FastMCP:+ skill = Skill(name=name, description=f"The {name} skill", instructions="# Hi\n")+ return FastMCP(name, providers=[SkillCatalogProvider([skill])])+++def skills_client(server: FastMCP) -> Client:+ return Client(server, extensions=[SkillsClientExtension()])+++async def test_list_skills_keys_entries_by_server():+ group = ClientGroup(+ {+ "a": skills_client(skill_server("review")),+ "b": skills_client(skill_server("review")),+ }+ )+ async with group:+ listed = await group.list_skills()+ assert {name: [e.uri for e in entries] for name, entries in listed.items()} == {+ "a": ["skill://review/SKILL.md"],+ "b": ["skill://review/SKILL.md"],+ }+++async def test_list_skills_skips_clients_without_the_extension():+ group = ClientGroup(+ {+ "skills": skills_client(skill_server("review")),+ "opted_out": Client(skill_server("deploy")),+ "no_skills": skills_client(FastMCP("plain")),+ }+ )+ async with group:+ listed = await group.list_skills()+ assert list(listed) == ["skills"]+++async def test_get_skill_reads_from_the_named_server():+ group = ClientGroup(+ {+ "a": skills_client(skill_server("review")),+ "b": skills_client(skill_server("deploy")),+ }+ )+ async with group:+ entry = await group.get_skill("b", "skill://deploy/SKILL.md")+ assert entry.frontmatter.description == "The deploy skill"+ with pytest.raises(KeyError, match="Unknown ClientGroup server"):+ await group.get_skill("c", "skill://deploy/SKILL.md")+++async def test_get_skill_requires_a_connection():+ group = ClientGroup({"a": skills_client(skill_server("review"))})+ with pytest.raises(RuntimeError, match="not connected"):+ await group.get_skill("a", "skill://review/SKILL.md")