refactor: Address API design improvements in StreamableHTTP client

This commit addresses two API design concerns:

1. Remove private module usage in examples: Examples no longer import from
   the private mcp.shared._httpx_utils module. Instead, they create httpx
   clients directly using the public httpx library.

2. Rename httpx_client parameter to http_client: The 'httpx_client' parameter
   name was redundant since the type annotation already specifies it's an
   httpx.AsyncClient. Renaming to 'http_client' provides a cleaner, more
   concise API.

Changes:
- Updated oauth_client.py and simple-auth-client examples to use public APIs
- Renamed httpx_client to http_client in function signatures
- Updated all internal callers and tests
- Updated deprecated streamablehttp_client wrapper function

Author: felixweinberger

examples/clients/simple-auth-client/mcp_simple_auth_client/main.py

@@ -15,11 +15,12 @@
 from typing import Any
 from urllib.parse import parse_qs, urlparse
 
+import httpx
+
 from mcp.client.auth import OAuthClientProvider, TokenStorage
 from mcp.client.session import ClientSession
 from mcp.client.sse import sse_client
 from mcp.client.streamable_http import streamable_http_client
-from mcp.shared._httpx_utils import create_mcp_http_client
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
 
 
@@ -205,10 +206,10 @@ async def _default_redirect_handler(authorization_url: str) -> None:
                     await self._run_session(read_stream, write_stream, None)
             else:
                 print("📡 Opening StreamableHTTP transport connection with auth...")
-                async with create_mcp_http_client(auth=oauth_auth) as custom_client:
+                async with httpx.AsyncClient(auth=oauth_auth, follow_redirects=True) as custom_client:
                     async with streamable_http_client(
                         url=self.server_url,
-                        httpx_client=custom_client,
+                        http_client=custom_client,
                     ) as (read_stream, write_stream, get_session_id):
                         await self._run_session(read_stream, write_stream, get_session_id)
 

examples/snippets/clients/oauth_client.py

@@ -10,12 +10,12 @@
 import asyncio
 from urllib.parse import parse_qs, urlparse
 
+import httpx
 from pydantic import AnyUrl
 
 from mcp import ClientSession
 from mcp.client.auth import OAuthClientProvider, TokenStorage
 from mcp.client.streamable_http import streamable_http_client
-from mcp.shared._httpx_utils import create_mcp_http_client
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
 
 
@@ -69,8 +69,8 @@ async def main():
         callback_handler=handle_callback,
     )
 
-    async with create_mcp_http_client(auth=oauth_auth) as custom_client:
-        async with streamable_http_client("http://localhost:8001/mcp", httpx_client=custom_client) as (read, write, _):
+    async with httpx.AsyncClient(auth=oauth_auth, follow_redirects=True) as custom_client:
+        async with streamable_http_client("http://localhost:8001/mcp", http_client=custom_client) as (read, write, _):
             async with ClientSession(read, write) as session:
                 await session.initialize()
 

src/mcp/client/session_group.py

@@ -263,7 +263,7 @@ async def _establish_session(
 
                 client = streamable_http_client(
                     url=server_params.url,
-                    httpx_client=httpx_client,
+                    http_client=httpx_client,
                     terminate_on_close=server_params.terminate_on_close,
                 )
                 read, write, _ = await session_stack.enter_async_context(client)

src/mcp/client/streamable_http.py

@@ -452,7 +452,7 @@ def get_session_id(self) -> str | None:
 async def streamable_http_client(
     url: str,
     *,
-    httpx_client: httpx.AsyncClient | None = None,
+    http_client: httpx.AsyncClient | None = None,
     terminate_on_close: bool = True,
 ) -> AsyncGenerator[
     tuple[
@@ -467,7 +467,7 @@ async def streamable_http_client(
 
     Args:
         url: The MCP server endpoint URL.
-        httpx_client: Optional pre-configured httpx.AsyncClient. If None, a default
+        http_client: Optional pre-configured httpx.AsyncClient. If None, a default
             client with recommended MCP timeouts will be created. To configure headers,
             authentication, or other HTTP settings, create an httpx.AsyncClient and pass it here.
         terminate_on_close: If True, send a DELETE request to terminate the session
@@ -486,8 +486,8 @@ async def streamable_http_client(
     write_stream, write_stream_reader = anyio.create_memory_object_stream[SessionMessage](0)
 
     # Determine if we need to create and manage the client
-    client_provided = httpx_client is not None
-    client = httpx_client
+    client_provided = http_client is not None
+    client = http_client
 
     if client is None:
         # Create default client with recommended MCP timeouts
@@ -579,7 +579,7 @@ async def streamablehttp_client(
     async with client:
         async with streamable_http_client(
             url,
-            httpx_client=client,
+            http_client=client,
             terminate_on_close=terminate_on_close,
         ) as streams:
             yield streams

tests/client/test_session_group.py

@@ -347,13 +347,13 @@ async def test_establish_session_parameterized(
                 elif client_type_name == "streamablehttp":
                     assert isinstance(server_params_instance, StreamableHttpParameters)
                     # Verify streamable_http_client was called with url, httpx_client, and terminate_on_close
-                    # The httpx_client is created by the real create_mcp_http_client
+                    # The http_client is created by the real create_mcp_http_client
                     import httpx
 
                     call_args = mock_specific_client_func.call_args
                     assert call_args.kwargs["url"] == server_params_instance.url
                     assert call_args.kwargs["terminate_on_close"] == server_params_instance.terminate_on_close
-                    assert isinstance(call_args.kwargs["httpx_client"], httpx.AsyncClient)
+                    assert isinstance(call_args.kwargs["http_client"], httpx.AsyncClient)
 
                 mock_client_cm_instance.__aenter__.assert_awaited_once()
 

tests/shared/test_streamable_http.py

@@ -1008,7 +1008,7 @@ async def test_streamable_http_client_session_termination(basic_server: None, ba
         headers[MCP_SESSION_ID_HEADER] = captured_session_id
 
     async with create_mcp_http_client(headers=headers) as httpx_client:
-        async with streamable_http_client(f"{basic_server_url}/mcp", httpx_client=httpx_client) as (
+        async with streamable_http_client(f"{basic_server_url}/mcp", http_client=httpx_client) as (
             read_stream,
             write_stream,
             _,
@@ -1075,7 +1075,7 @@ async def mock_delete(self: httpx.AsyncClient, *args: Any, **kwargs: Any) -> htt
         headers[MCP_SESSION_ID_HEADER] = captured_session_id
 
     async with create_mcp_http_client(headers=headers) as httpx_client:
-        async with streamable_http_client(f"{basic_server_url}/mcp", httpx_client=httpx_client) as (
+        async with streamable_http_client(f"{basic_server_url}/mcp", http_client=httpx_client) as (
             read_stream,
             write_stream,
             _,
@@ -1175,7 +1175,7 @@ async def run_tool():
         headers[MCP_PROTOCOL_VERSION_HEADER] = captured_protocol_version
 
     async with create_mcp_http_client(headers=headers) as httpx_client:
-        async with streamable_http_client(f"{server_url}/mcp", httpx_client=httpx_client) as (
+        async with streamable_http_client(f"{server_url}/mcp", http_client=httpx_client) as (
             read_stream,
             write_stream,
             _,
@@ -1398,7 +1398,7 @@ async def test_streamablehttp_request_context_propagation(context_aware_server:
     }
 
     async with create_mcp_http_client(headers=custom_headers) as httpx_client:
-        async with streamable_http_client(f"{basic_server_url}/mcp", httpx_client=httpx_client) as (
+        async with streamable_http_client(f"{basic_server_url}/mcp", http_client=httpx_client) as (
             read_stream,
             write_stream,
             _,
@@ -1436,7 +1436,7 @@ async def test_streamablehttp_request_context_isolation(context_aware_server: No
         }
 
         async with create_mcp_http_client(headers=headers) as httpx_client:
-            async with streamable_http_client(f"{basic_server_url}/mcp", httpx_client=httpx_client) as (
+            async with streamable_http_client(f"{basic_server_url}/mcp", http_client=httpx_client) as (
                 read_stream,
                 write_stream,
                 _,