Client Groups

A ClientGroup coordinates several independent FastMCP clients without combining them behind a proxy server. Each client keeps its own connection, negotiated protocol version, capabilities, and handlers. The group adds namespaced tool discovery and routes each call back to the client that advertised the tool.

This differs from passing a multi-server configuration directly to Client. Client(config) presents one aggregate MCP endpoint and therefore selects one protocol era shared by its proxy chain. A ClientGroup retains one MCP connection per configured server, so legacy and modern servers can operate in their native eras at the same time.

Create a group from clients

Construct the clients explicitly when each server needs its own handlers, authentication, or connection settings:

from pathlib import Path
import asyncio

from fastmcp import Client
from fastmcp.client.group import ClientGroup

legacy_client = Client(Path("legacy_server.py"), mode="legacy")
modern_client = Client("https://modern.example.com/mcp", mode="auto")

group = ClientGroup(
    {
        "legacy": legacy_client,
        "modern": modern_client,
    }
)


async def main() -> None:
    async with group:
        tools = await group.list_tools()
        print([tool.name for tool in tools])

        result = await group.call_tool(
            "modern_get_weather",
            {"city": "Chicago"},
        )
        print(result)


asyncio.run(main())

Tool names are prefixed with the configured client name by default. For example, a get_weather tool exposed by the modern client becomes modern_get_weather.

A group with a single client is a supported way to get namespacing alone: the one server’s tools are presented under its configured name, with no other behavior change.

The first routed call loads the tool catalog lazily. After a successful load, unknown tool names fail locally rather than repeating discovery against every server. Call list_tools() explicitly to refresh the routes when servers add or remove tools dynamically — the explicit call refreshes past any client-side response cache, so the catalog reflects what every server advertises now.

Bind tools to their owning client

Tool adapters — code that turns MCP tools into callables for an agent framework — often need more than routed calls: session-driven input loops, handler context, and interceptors must run on the connection that owns the tool. resolve_tool() returns that route, so an adapter can discover through the group and still bind each generated tool to its real client:

async with group:
    for tool in await group.list_tools():
        route = await group.resolve_tool(tool.name)
        # route.client is the connected FastMCP client for this tool;
        # route.upstream_name is the name the server itself advertises
        register_agent_tool(tool, client=route.client, name=route.upstream_name)

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.

Create a group from configuration

ClientGroup.from_config creates one client per server rather than passing the entire configuration through a proxy. A FastMCP-specific mode field can select the protocol behavior for each server:

from fastmcp.client.group import ClientGroup

config = {
    "mcpServers": {
        "legacy": {
            "command": "python",
            "args": ["legacy_server.py"],
            "mode": "legacy",
        },
        "modern": {
            "url": "https://modern.example.com/mcp",
            "mode": "auto",
        },
    }
}

group = ClientGroup.from_config(config)

Entries without a mode use "auto" by default.

Manage connections explicitly

Using the group as a context manager is optional. Applications can own each client connection and use the group only for discovery and routing:

async with legacy_client, modern_client:
    tools = await group.list_tools()

It is also safe to enter the group inside a client context. FastMCP client contexts are reference counted, so leaving the group does not close a connection still owned by an outer context.

The group adds no session handling of its own. Each client owns its transport and session exactly as it does standalone, so a legacy stateful session (for example over SSE or stdio) is held open by its client for as long as that client’s context is active, whether the group or the caller entered it.

Related: SDK session groups

The MCP Python SDK has its own aggregation primitive, ClientSessionGroup, which pools raw ClientSession connections. ClientGroup exists because FastMCP clients carry more than a session: authentication, handlers, caching, result parsing, and protocol negotiation all live on the Client, and routing calls through the client that advertised each tool keeps every one of those intact. Reach for the SDK’s group when working with raw sessions directly; reach for ClientGroup when the servers are already configured as FastMCP clients.