fastmcp.client.group

Coordination of independent MCP client connections.

Classes

ToolRoute ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/group.py#L23" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

The client and upstream name behind a public group tool name.

ClientGroup ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/group.py#L31" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

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.

Callers may manage the clients' connections themselves or use the group as a convenience context manager. Entering an already-connected FastMCP client is safe because client contexts are reference counted.

Methods:

clients ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/group.py#L53" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

clients(self) -> Mapping[str, Client[Any]]

The group's clients, keyed by server name.

Read-only: membership is fixed at construction, since discovered routes hold the client that advertised each tool and would silently go stale if the mapping were swapped underneath them.

from_config ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/group.py#L63" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

from_config(cls, config: MCPConfig | dict[str, Any]) -> ClientGroup

Create one independent client for each configured server.

A server entry may include a FastMCP-specific mode field. It applies only to that server; entries without one use default_mode.

protocol_versions ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/group.py#L88" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

protocol_versions(self) -> dict[str, str | None]

list_tools ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/group.py#L152" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

list_tools(self) -> list[mcp_types.Tool]

List tools from every client with namespaced names.

An explicit call is the group's catalog-refresh mechanism, so it defaults to cache_mode="refresh": a client-side response cache (SEP-2549) is repopulated rather than served, and the routes reflect what every server advertises now. Pass cache_mode="use" to allow cache hits when staleness within the server's hint is acceptable.

resolve_tool ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/group.py#L189" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

resolve_tool(self, name: str) -> ToolRoute

Resolve a public tool name to its client and upstream identity.

A known route only requires its own client to be connected; one dead server does not couple failures onto calls routed to healthy servers. Loading the catalog (the first resolution, or after a refresh) still requires every client, since discovery queries them all.

call_tool_mcp ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/group.py#L224" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

call_tool_mcp(self, name: str, arguments: dict[str, Any] | None = None) -> mcp_types.CallToolResult

Call a namespaced tool and return its raw MCP result.

call_tool ^{<a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/client/group.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> CallToolResult

Call a namespaced tool through the client that advertised it.