π The fast, Pythonic way to build MCP servers and clients.
Fix session persistence across tool calls in multi-server MCPConfigTransport (#3330)
Jeremy Simonf2dd2e5124e3
diff --git a/src/fastmcp/client/transports/config.py b/src/fastmcp/client/transports/config.pyindex 5f303567d..c8d5a8a40 100644--- a/src/fastmcp/client/transports/config.py+++ b/src/fastmcp/client/transports/config.py@@ -91,40 +91,57 @@ class MCPConfigTransport(ClientTransport):yield sessionreturn- # Multiple servers - create composite with mounted proxies- # Close any previous transports from prior connections to avoid leaking- for t in self._transports:- await t.close()- self._transports = []+ # Multiple servers - create composite with mounted proxies, connecting+ # each ProxyClient so its underlying transport session stays alive for+ # the duration of this context (fixes session persistence for+ # streamable-http backends β see #2790).timeout = session_kwargs.get("read_timeout_seconds")composite = FastMCP[Any](name="MCPRouter")- try:- for name, server_config in self.config.mcpServers.items():- transport, proxy = self._create_proxy(name, server_config, timeout)- self._transports.append(transport)- composite.mount(proxy, namespace=name if self.name_as_prefix else None)- except Exception:- # Clean up any transports created before the failure+ async with contextlib.AsyncExitStack() as stack:+ # Close any previous transports from prior connections to avoid leakingfor t in self._transports:await t.close()self._transports = []- raise- async with FastMCPTransport(mcp=composite).connect_session(- **session_kwargs- ) as session:- yield session+ try:+ for name, server_config in self.config.mcpServers.items():+ transport, _client, proxy = await self._create_proxy(+ name, server_config, timeout, stack+ )+ self._transports.append(transport)+ composite.mount(+ proxy, namespace=name if self.name_as_prefix else None+ )+ except Exception:+ # Clean up any transports created before the failure+ for t in self._transports:+ await t.close()+ self._transports = []+ raise++ async with FastMCPTransport(mcp=composite).connect_session(+ **session_kwargs+ ) as session:+ yield session- def _create_proxy(+ async def _create_proxy(self,name: str,config: MCPServerTypes,timeout: datetime.timedelta | None,- ) -> tuple[ClientTransport, FastMCP[Any]]:- """Create underlying transport and proxy server for a single backend."""+ stack: contextlib.AsyncExitStack,+ ) -> tuple[ClientTransport, Any, FastMCP[Any]]:+ """Create underlying transport, proxy client, and proxy server for a single backend.++ The ProxyClient is connected via the AsyncExitStack *before* being+ passed to create_proxy so the factory sees it as connected and reuses+ the same session for all tool calls (instead of creating fresh copies).++ Returns a tuple of (transport, proxy_client, proxy_server).+ """# Import here to avoid circular dependency- from fastmcp.server.providers.proxy import ProxyClient+ from fastmcp.server.providers.proxy import StatefulProxyClienttool_transforms = Noneinclude_tags = None@@ -144,7 +161,23 @@ class MCPConfigTransport(ClientTransport):else:transport = config.to_transport()- client = ProxyClient(transport=transport, timeout=timeout)+ client = StatefulProxyClient(transport=transport, timeout=timeout)+ # Connect the client *before* create_proxy so _create_client_factory+ # detects it as connected and reuses it for all tool calls, preserving+ # the session ID across requests. StatefulProxyClient is used instead+ # of ProxyClient because its context-restoring handler wrappers prevent+ # stale ContextVars in the reused session's receive loop.+ #+ # StatefulProxyClient.__aexit__ is a no-op (by design, for the+ # new_stateful() use case), so we cannot rely on enter_async_context+ # alone to clean up. Instead we connect manually and push an+ # explicit force-disconnect callback so the subprocess is terminated+ # when the AsyncExitStack unwinds.+ await client.__aenter__()+ # Callbacks run LIFO: transport.close() must run *after*+ # client._disconnect so push it first.+ stack.push_async_callback(transport.close)+ stack.push_async_callback(client._disconnect, force=True)# Create proxy without include_tags/exclude_tags - we'll add them after tool transformsproxy = create_proxy(client,@@ -160,7 +193,7 @@ class MCPConfigTransport(ClientTransport):proxy.enable(tags=set(include_tags), only=True)if exclude_tags:proxy.disable(tags=set(exclude_tags))- return transport, proxy+ return transport, client, proxyasync def close(self):for transport in self._transports:diff --git a/src/fastmcp/server/providers/proxy.py b/src/fastmcp/server/providers/proxy.pyindex be844bb4a..5d2ea562f 100644--- a/src/fastmcp/server/providers/proxy.py+++ b/src/fastmcp/server/providers/proxy.py@@ -127,7 +127,10 @@ class ProxyTool(Tool):# request. Stash the current RequestContext in the shared# ref so handlers can restore it before forwarding.if isinstance(client, StatefulProxyClient):- cast(list[Any], client._proxy_rc_ref)[0] = ctx.request_context+ cast(list[Any], client._proxy_rc_ref)[0] = (+ ctx.request_context,+ ctx._fastmcp, # weakref to FastMCP, not the Context+ )# Build meta dict from request contextmeta: dict[str, Any] | None = Noneif hasattr(ctx, "request_context"):@@ -791,24 +794,40 @@ async def default_proxy_progress_handler(def _restore_request_context(rc_ref: list[Any],) -> None:- """Set the ``request_ctx`` ContextVar from a stashed RequestContext.+ """Set the ``request_ctx`` and ``_current_context`` ContextVars from stashed values.Called at the start of proxy handler invocations in``StatefulProxyClient`` to fix stale ContextVars in the receive-looptask. Only overrides when the ContextVar is genuinely stale (samesession, different request_id) to avoid corrupting the concurrentcase where multiple sessions share the same ref via ``copy.copy``.++ We stash a ``(RequestContext, weakref[FastMCP])`` tuple β never a+ ``Context`` instance β because ``Context`` properties are themselves+ ContextVar-dependent and would resolve stale values in the receive+ loop. Instead we construct a fresh ``Context`` here after restoring+ ``request_ctx``, so its property accesses read the correct values."""- rc = rc_ref[0]- if rc is None:+ from fastmcp.server.context import Context, _current_context++ stashed = rc_ref[0]+ if stashed is None:return++ rc, fastmcp_ref = stashedtry:current_rc = request_ctx.get()except LookupError:request_ctx.set(rc)+ fastmcp = fastmcp_ref()+ if fastmcp is not None:+ _current_context.set(Context(fastmcp))returnif current_rc.session is rc.session and current_rc.request_id != rc.request_id:request_ctx.set(rc)+ fastmcp = fastmcp_ref()+ if fastmcp is not None:+ _current_context.set(Context(fastmcp))def _make_restoring_handler(handler: Callable, rc_ref: list[Any]) -> Callable:@@ -881,9 +900,10 @@ class StatefulProxyClient(ProxyClient[ClientTransportT]):# writes [0] before each backend call; handlers read it to detect# stale ContextVars and restore the correct request_ctx.#- # We store the concrete RequestContext (not fastmcp's Context) because- # Context properties are themselves ContextVar-dependent and resolve- # in the caller's async context β which is stale in the receive loop.+ # Stores a (RequestContext, weakref[FastMCP]) tuple β never a Context+ # instance β because Context properties are ContextVar-dependent and+ # would resolve stale values in the receive loop. The restore helper+ # constructs a fresh Context from the weakref after setting request_ctx._proxy_rc_ref: list[Any]def __init__(self, *args: Any, **kwargs: Any):diff --git a/tests/test_mcp_config.py b/tests/test_mcp_config.pyindex 51eeae5e1..786d4e4e2 100644--- a/tests/test_mcp_config.py+++ b/tests/test_mcp_config.py@@ -902,37 +902,83 @@ async def test_multi_server_timeout_propagation():transport = MCPConfigTransport(config)timeout = timedelta(seconds=42)- # Patch _create_proxy to verify timeout is passed correctly+ # Mock _create_proxy to avoid real stdio connections and verify timeout+ mock_create_proxy = AsyncMock(+ return_value=(AsyncMock(), AsyncMock(), FastMCP(name="MockProxy"))+ )+with (- patch("fastmcp.client.transports.FastMCP.as_proxy") as mock_as_proxy,- patch.object(- transport, "_create_proxy", wraps=transport._create_proxy- ) as mock_create_proxy,+ patch.object(transport, "_create_proxy", mock_create_proxy),+ patch(+ "fastmcp.client.transports.FastMCPTransport.connect_session"+ ) as mock_connect,):- # Make as_proxy return a mock FastMCP- mock_proxy = FastMCP(name="MockProxy")- mock_as_proxy.return_value = mock_proxy+ mock_session = AsyncMock()+ mock_connect.return_value.__aenter__ = AsyncMock(return_value=mock_session)+ mock_connect.return_value.__aexit__ = AsyncMock(return_value=None)++ async with transport.connect_session(read_timeout_seconds=timeout):+ pass++ # Verify _create_proxy was called with the timeout for each server+ assert mock_create_proxy.call_count == 2+ for call in mock_create_proxy.call_args_list:+ # Third positional arg is timeout+ call_timeout = call[0][2] if len(call[0]) > 2 else call.kwargs.get("timeout")+ assert call_timeout == timeout, (+ f"Expected timeout {timeout}, got {call_timeout}"+ )- # Mock connect_session on FastMCPTransport to avoid actual connection- with patch(- "fastmcp.client.transports.FastMCPTransport.connect_session"- ) as mock_connect:- mock_session = AsyncMock()- mock_connect.return_value.__aenter__ = AsyncMock(return_value=mock_session)- mock_connect.return_value.__aexit__ = AsyncMock(return_value=None)-- async with transport.connect_session(read_timeout_seconds=timeout):- pass-- # Verify _create_proxy was called with the timeout for each server- assert mock_create_proxy.call_count == 2- for call in mock_create_proxy.call_args_list:- _, kwargs = call.args, call.kwargs if call.kwargs else {}- # Third positional arg is timeout- call_timeout = call[0][2] if len(call[0]) > 2 else kwargs.get("timeout")- assert call_timeout == timeout, (- f"Expected timeout {timeout}, got {call_timeout}"- )++async def test_multi_server_session_persistence(tmp_path: Path):+ """Test that session IDs persist across tool calls in multi-server mode.++ Regression test for https://github.com/PrefectHQ/fastmcp/issues/2790 β+ MCPConfigTransport was not connecting ProxyClients before mounting, so+ each tool call opened a new session with the backend server.+ """+ server_script = inspect.cleandoc("""+ from fastmcp import FastMCP, Context++ mcp = FastMCP()++ @mcp.tool+ def get_session(ctx: Context) -> str:+ return ctx.session_id++ if __name__ == '__main__':+ mcp.run()+ """)++ script_path = tmp_path / "session_server.py"+ script_path.write_text(server_script)++ config = {+ "mcpServers": {+ "server1": {+ "command": "python",+ "args": [str(script_path)],+ },+ "server2": {+ "command": "python",+ "args": [str(script_path)],+ },+ }+ }++ client = Client(config)+ async with client:+ result1 = await client.call_tool("server1_get_session", {})+ assert isinstance(result1.content[0], TextContent)+ session_id_1 = result1.content[0].text++ result2 = await client.call_tool("server1_get_session", {})+ assert isinstance(result2.content[0], TextContent)+ session_id_2 = result2.content[0].text++ assert session_id_1 == session_id_2, (+ f"Session ID changed between calls: {session_id_1} != {session_id_2}"+ )async def test_single_server_config_transport():