π The fast, Pythonic way to build MCP servers and clients.
docs: transport inference trust contract; trim SDK session-group comparison (#4940)
nate nowack1f021142978e
diff --git a/docs/clients/client-groups.mdx b/docs/clients/client-groups.mdxindex f501c9c62..988735ce0 100644--- a/docs/clients/client-groups.mdx+++ b/docs/clients/client-groups.mdx@@ -108,8 +108,6 @@ It is also safe to enter the group inside a client context. FastMCP client conteThe 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.-## Relationship to SDK session groups+## Related: SDK session groups-The upstream official MCP Python SDK provides `ClientSessionGroup` for aggregating raw `ClientSession` connections, including tools, resources, and prompts. Its `connect_to_server()` path uses the classic `initialize` handshake, so it does not negotiate the modern protocol. Use it when classic sessions, raw SDK results, and dynamic group membership fit the application.--`connect_with_session()` can register a modern session that was connected separately, but the caller must create and keep that client alive because the SDK group does not own sessions registered this way. `ClientGroup` instead manages fully configured FastMCP clients directly. Each client can negotiate its own modern or legacy protocol, and calls continue through that client, preserving its authentication, handlers, caching, tracing, result parsing, and multi-round tool behavior. The API is intentionally narrower and currently aggregates tools only.+The MCP Python SDK has its own aggregation primitive, [`ClientSessionGroup`](https://py.sdk.modelcontextprotocol.io/client/session-groups/), 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.diff --git a/docs/clients/transports.mdx b/docs/clients/transports.mdxindex 23acab535..d165eb953 100644--- a/docs/clients/transports.mdx+++ b/docs/clients/transports.mdx@@ -42,6 +42,10 @@ from fastmcp import Clientclient = Client("my_server.py") # Limited - no configuration options```+<Warning>+Transport inference treats its input as trusted configuration. A string naming an existing `.py` or `.js` file starts that file as a subprocess, and a configuration dictionary can run any command with any arguments. An application that accepts server locations from users should validate them at its own boundary and construct the transport explicitly, for example `StreamableHttpTransport(url=...)` for a URL, rather than passing the raw value to `Client`.+</Warning>+### Environment VariablesValues you pass through `env` are merged on top of the inherited allowlist, so you add configuration rather than replacing the base environment. Anything your server needs beyond those six variables has to be listed explicitly.