Load httpx2 with the HTTP transports only

The streamable-HTTP client transport (httpx2) is now imported when the
first URL Client is constructed instead of at import time, so a stdio-only
client (or a bare `import mcp.client`) never loads it. Tests cover the
resulting import contract: the client entry points load neither the
server stack nor httpx2 until they are used, and the package's lazy
server-side re-exports still resolve to their defining objects.

The test that patched `mcp.client.client.streamable_http_client` now
patches the transport at its defining module.

Author: maxisbey

src/mcp/client/client.py

@@ -58,7 +58,6 @@
     MessageHandlerFnT,
     SamplingFnT,
 )
-from mcp.client.streamable_http import streamable_http_client
 from mcp.client.subscriptions import ServerEvent, Subscription
 from mcp.client.subscriptions import listen as _listen
 from mcp.shared.direct_dispatcher import create_direct_dispatcher_pair
@@ -103,6 +102,16 @@ async def connect(exit_stack: AsyncExitStack, _mode: ConnectMode, _raise_excepti
     return connect
 
 
+def _connect_url(url: str) -> _Connector:
+    """Connector for a URL string: the streamable-HTTP client transport."""
+    # Function-level import (documented exception): `httpx2` is the heaviest client-side
+    # dependency and only the HTTP transports need it, so a stdio-only client (or bare
+    # `import mcp.client`) never loads it; the first URL `Client` constructed does, once.
+    from mcp.client.streamable_http import streamable_http_client
+
+    return _connect_transport(streamable_http_client(url))
+
+
 def _loaded_class(module: str, name: str) -> type | None:
     """Return class `name` from `module` if that module has already been imported, else `None`.
 
@@ -422,7 +431,7 @@ def __post_init__(self) -> None:
         if _is_lowlevel_server(srv):
             self._connect = _connect_inproc(srv)
         elif isinstance(srv, str):
-            self._connect = _connect_transport(streamable_http_client(srv))
+            self._connect = _connect_url(srv)
         else:
             self._connect = _connect_transport(srv)
 

tests/client/test_client.py

@@ -3,6 +3,9 @@
 from __future__ import annotations
 
 import contextvars
+import json
+import subprocess
+import sys
 from collections.abc import AsyncIterator, Iterator
 from contextlib import asynccontextmanager, contextmanager
 from unittest.mock import patch
@@ -397,11 +400,52 @@ async def test_complete_with_prompt_reference(simple_server: Server):
 
 
 def test_client_with_url_initializes_streamable_http_transport():
-    with patch("mcp.client.client.streamable_http_client") as mock:
+    # `Client` imports the streamable-HTTP transport lazily (at construction of the
+    # first URL client) so a stdio-only client never loads httpx2; patch its source.
+    with patch("mcp.client.streamable_http.streamable_http_client") as mock:
         _ = Client("http://localhost:8000/mcp")
     mock.assert_called_once_with("http://localhost:8000/mcp")
 
 
+# Runs in a fresh interpreter: this process has already imported the whole SDK, so its
+# `sys.modules` can't show what the client entry points load on their own. Prints which of
+# the deferred package prefixes are loaded after the imports, then again after building a
+# URL Client (which constructs its transport but only connects on __aenter__).
+FRESH_CLIENT_IMPORT_PROBE = """
+import json, sys
+
+import mcp
+import mcp.client.stdio
+from mcp import Client
+
+DEFERRED = ("mcp.server", "httpx2", "starlette", "uvicorn", "sse_starlette", "jwt", "cryptography")
+
+
+def loaded():
+    return sorted({p for p in DEFERRED for m in sys.modules if m == p or m.startswith(p + ".")})
+
+
+on_import = loaded()
+Client("http://localhost/mcp")
+print(json.dumps([on_import, loaded()]))
+"""
+
+
+def test_client_entry_points_load_the_server_stack_and_http_transports_only_when_used():
+    """SDK-defined: `import mcp` / `import mcp.client.stdio` / `from mcp import Client` load
+    neither the server stack nor httpx2; constructing the first URL `Client` is what loads
+    its streamable-HTTP transport (httpx2), and even then the server stack stays out."""
+    # A regression hangs forever, so the bound only has to beat never (matches the suite's
+    # other subprocess.run calls).
+    result = subprocess.run(
+        [sys.executable, "-c", FRESH_CLIENT_IMPORT_PROBE], capture_output=True, text=True, check=False, timeout=20
+    )
+    assert result.returncode == 0, result.stderr
+    on_import, after_url_client = json.loads(result.stdout)
+    assert on_import == []
+    assert after_url_client == ["httpx2"]
+
+
 async def test_client_uses_transport_directly(app: MCPServer):
     transport = InMemoryTransport(app)
     async with Client(transport, mode="legacy") as client:

tests/test_init.py

@@ -7,7 +7,10 @@
 from inline_snapshot import snapshot
 
 import mcp
+import mcp.server.session
+import mcp.server.stdio
 import mcp.shared.exceptions
+from mcp.client.session_group import ClientSessionGroup
 
 
 def test_exported_name_is_the_home_module_object_and_is_cached_on_the_package():
@@ -16,6 +19,14 @@ def test_exported_name_is_the_home_module_object_and_is_cached_on_the_package():
     assert vars(mcp)["MCPError"] is mcp.shared.exceptions.MCPError
 
 
+def test_client_and_server_reexports_are_the_defining_objects():
+    """SDK-defined: `mcp.ServerSession`, `mcp.stdio_server` and `mcp.ClientSessionGroup`
+    resolve on first access to the very objects their defining modules export."""
+    assert mcp.ServerSession is mcp.server.session.ServerSession
+    assert mcp.stdio_server is mcp.server.stdio.stdio_server
+    assert mcp.ClientSessionGroup is ClientSessionGroup
+
+
 def test_dir_lists_every_export_and_the_bound_submodules():
     """SDK-defined: `dir(mcp)` reports all of `__all__` plus the submodules a bare import binds."""
     listing = set(dir(mcp))