Skip to content

🚀 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.mdx
index 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.py
index 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 CacheMode
from fastmcp.client.client import CallToolResult, Client, ConnectMode
from fastmcp.client.progress import ProgressHandler
from fastmcp.mcp_config import MCPConfig
+from fastmcp.skills.models import MCPSkill
from 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 as
a convenience context manager. The group's context is reentrant in the
@@ -259,6 +261,43 @@ class ClientGroup:
self._catalog_loaded = True
return 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.py
index 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_capabilities
server_extensions = capabilities.extensions if capabilities else None
if 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.py
new file mode 100644
index 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")