Replace httpx and httpx-sse with httpx2

httpx2 (2.5.0) is the next-generation httpx fork with server-sent
events support built in, so the separate httpx-sse dependency is no
longer needed.

- Swap the httpx/httpx-sse dependencies for httpx2>=2.5.0 in the SDK
  and the example projects.
- Rewrite the SSE transports against httpx2's API: aconnect_sse(...) ->
  client.stream(...)/client.sse(...) wrapped in EventSource, and
  iterate the EventSource directly instead of .aiter_sse().
- Document the swap as a v2 breaking change in docs/migration.md and
  update docs/installation.md, README.v2.md, and the example sources.

Verified: ruff, pyright, and the full test suite pass at 100% coverage.

Author: Kludex

README.v2.md

@@ -2319,7 +2319,7 @@ cd to the `examples/snippets` directory and run:
 import asyncio
 from urllib.parse import parse_qs, urlparse
 
-import httpx
+import httpx2
 from pydantic import AnyUrl
 
 from mcp import ClientSession
@@ -2382,7 +2382,7 @@ async def main():
         callback_handler=handle_callback,
     )
 
-    async with httpx.AsyncClient(auth=oauth_auth, follow_redirects=True) as custom_client:
+    async with httpx2.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()

docs/installation.md

@@ -15,8 +15,7 @@ The Python SDK is available on PyPI as [`mcp`](https://pypi.org/project/mcp/) so
 
 The following dependencies are automatically installed:
 
-- [`httpx`](https://pypi.org/project/httpx/): HTTP client to handle HTTP Streamable and SSE transports.
-- [`httpx-sse`](https://pypi.org/project/httpx-sse/): HTTP client to handle SSE transport.
+- [`httpx2`](https://pypi.org/project/httpx2/): HTTP client to handle HTTP Streamable and SSE transports.
 - [`pydantic`](https://pypi.org/project/pydantic/): Types, JSON schema generation, data validation, and [more](https://docs.pydantic.dev/latest/).
 - [`starlette`](https://pypi.org/project/starlette/): Web framework used to build the HTTP transport endpoints.
 - [`python-multipart`](https://pypi.org/project/python-multipart/): Handle HTTP body parsing.

docs/migration.md

@@ -8,6 +8,39 @@ Version 2 of the MCP Python SDK introduces several breaking changes to improve t
 
 ## Breaking Changes
 
+### `httpx` replaced by `httpx2`
+
+The SDK now depends on [`httpx2`](https://pypi.org/project/httpx2/) instead of
+`httpx` and `httpx-sse`. `httpx2` is the next-generation HTTP client (a fork of
+`httpx`) with server-sent events support built in, so the separate `httpx-sse`
+dependency is gone.
+
+The public API surface is unchanged in shape - `streamable_http_client` and
+`sse_client` still accept the same arguments - but the client type they expect
+is now `httpx2.AsyncClient`. If you construct your own client to pass as
+`http_client` (or build an `httpx.Auth` subclass for `auth`), import from
+`httpx2`:
+
+**Before (v1):**
+
+```python
+import httpx
+
+http_client = httpx.AsyncClient(follow_redirects=True)
+```
+
+**After (v2):**
+
+```python
+import httpx2
+
+http_client = httpx2.AsyncClient(follow_redirects=True)
+```
+
+`httpx2` is API-compatible with `httpx`, so usually only the import name
+changes. To consume SSE directly, use `httpx2.EventSource` (or
+`AsyncClient.sse()`) instead of the `httpx-sse` helpers.
+
 ### `MCPServer.call_tool()` returns `CallToolResult`
 
 `MCPServer.call_tool()` now always returns a `CallToolResult`. It previously
@@ -55,13 +88,13 @@ async with streamablehttp_client(
 **After (v2):**
 
 ```python
-import httpx
+import httpx2
 from mcp.client.streamable_http import streamable_http_client
 
-# Configure headers, timeout, and auth on the httpx.AsyncClient
-http_client = httpx.AsyncClient(
+# Configure headers, timeout, and auth on the httpx2.AsyncClient
+http_client = httpx2.AsyncClient(
     headers={"Authorization": "Bearer token"},
-    timeout=httpx.Timeout(30, read=300),
+    timeout=httpx2.Timeout(30, read=300),
     auth=my_auth,
     follow_redirects=True,
 )
@@ -74,7 +107,7 @@ async with http_client:
         ...
 ```
 
-v1's internal client set `follow_redirects=True`; set it explicitly when supplying your own `httpx.AsyncClient` to preserve that behavior.
+v1's internal client set `follow_redirects=True`; set it explicitly when supplying your own `httpx2.AsyncClient` to preserve that behavior.
 
 ### OAuth `callback_handler` returns `AuthorizationCodeResult`
 
@@ -109,7 +142,7 @@ Forward the `iss` query parameter from the redirect so the validation can run: o
 
 The `get_session_id` callback (third element of the returned tuple) has been removed from `streamable_http_client`. The function now returns a 2-tuple `(read_stream, write_stream)` instead of a 3-tuple.
 
-If you need to capture the session ID (e.g., for session resumption testing), you can use httpx event hooks to capture it from the response headers:
+If you need to capture the session ID (e.g., for session resumption testing), you can use httpx2 event hooks to capture it from the response headers:
 
 **Before (v1):**
 
@@ -125,23 +158,23 @@ async with streamable_http_client(url) as (read_stream, write_stream, get_sessio
 **After (v2):**
 
 ```python
-import httpx
+import httpx2
 from mcp.client.streamable_http import streamable_http_client
 
 # Option 1: Simply ignore if you don't need the session ID
 async with streamable_http_client(url) as (read_stream, write_stream):
     async with ClientSession(read_stream, write_stream) as session:
         await session.initialize()
 
-# Option 2: Capture session ID via httpx event hooks if needed
+# Option 2: Capture session ID via httpx2 event hooks if needed
 captured_session_ids: list[str] = []
 
-async def capture_session_id(response: httpx.Response) -> None:
+async def capture_session_id(response: httpx2.Response) -> None:
     session_id = response.headers.get("mcp-session-id")
     if session_id:
         captured_session_ids.append(session_id)
 
-http_client = httpx.AsyncClient(
+http_client = httpx2.AsyncClient(
     event_hooks={"response": [capture_session_id]},
     follow_redirects=True,
 )
@@ -155,7 +188,7 @@ async with http_client:
 
 ### `StreamableHTTPTransport` parameters removed
 
-The `headers`, `timeout`, `sse_read_timeout`, and `auth` parameters have been removed from `StreamableHTTPTransport`. Configure these on the `httpx.AsyncClient` instead (see example above).
+The `headers`, `timeout`, `sse_read_timeout`, and `auth` parameters have been removed from `StreamableHTTPTransport`. Configure these on the `httpx2.AsyncClient` instead (see example above).
 
 Note: `sse_client` retains its `headers`, `timeout`, `sse_read_timeout`, and `auth` parameters — only the streamable HTTP transport changed.
 

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

@@ -17,7 +17,7 @@
 from typing import Any
 from urllib.parse import parse_qs, urlparse
 
-import httpx
+import httpx2
 from mcp.client._transport import ReadStream, WriteStream
 from mcp.client.auth import AuthorizationCodeResult, OAuthClientProvider, TokenStorage
 from mcp.client.session import ClientSession
@@ -233,7 +233,7 @@ async def _default_redirect_handler(authorization_url: str) -> None:
                     await self._run_session(read_stream, write_stream)
             else:
                 print("📡 Opening StreamableHTTP transport connection with auth...")
-                async with httpx.AsyncClient(auth=oauth_auth, follow_redirects=True) as custom_client:
+                async with httpx2.AsyncClient(auth=oauth_auth, follow_redirects=True) as custom_client:
                     async with streamable_http_client(url=self.server_url, http_client=custom_client) as (
                         read_stream,
                         write_stream,

examples/clients/simple-chatbot/mcp_simple_chatbot/main.py

@@ -8,7 +8,7 @@
 from contextlib import AsyncExitStack
 from typing import Any
 
-import httpx
+import httpx2
 from dotenv import load_dotenv
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import stdio_client
@@ -230,7 +230,7 @@ def get_response(self, messages: list[dict[str, str]]) -> str:
             The LLM's response as a string.
 
         Raises:
-            httpx.RequestError: If the request to the LLM fails.
+            httpx2.RequestError: If the request to the LLM fails.
         """
         url = "https://api.groq.com/openai/v1/chat/completions"
 
@@ -249,17 +249,17 @@ def get_response(self, messages: list[dict[str, str]]) -> str:
         }
 
         try:
-            with httpx.Client() as client:
+            with httpx2.Client() as client:
                 response = client.post(url, headers=headers, json=payload)
                 response.raise_for_status()
                 data = response.json()
                 return data["choices"][0]["message"]["content"]
 
-        except httpx.RequestError as e:
+        except httpx2.RequestError as e:
             error_message = f"Error getting LLM response: {str(e)}"
             logging.error(error_message)
 
-            if isinstance(e, httpx.HTTPStatusError):
+            if isinstance(e, httpx2.HTTPStatusError):
                 status_code = e.response.status_code
                 logging.error(f"Status code: {status_code}")
                 logging.error(f"Response details: {e.response.text}")

examples/clients/sse-polling-client/mcp_sse_polling_client/main.py

@@ -92,7 +92,7 @@ def main(url: str, items: int, checkpoint_every: int, log_level: str) -> None:
         format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
     )
     # Suppress noisy HTTP client logging
-    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("httpx2").setLevel(logging.WARNING)
     logging.getLogger("httpcore").setLevel(logging.WARNING)
 
     asyncio.run(run_demo(url, items, checkpoint_every))

examples/mcpserver/text_me.py

@@ -19,7 +19,7 @@
 
 from typing import Annotated
 
-import httpx
+import httpx2
 from pydantic import BeforeValidator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
@@ -44,7 +44,7 @@ class SurgeSettings(BaseSettings):
 @mcp.tool(name="textme", description="Send a text message to me")
 def text_me(text_content: str) -> str:
     """Send a text message to a phone number via https://surgemsg.com/"""
-    with httpx.Client() as client:
+    with httpx2.Client() as client:
         response = client.post(
             "https://api.surgemsg.com/messages",
             headers={

examples/servers/everything-server/pyproject.toml

@@ -7,7 +7,7 @@ requires-python = ">=3.10"
 authors = [{ name = "Model Context Protocol a Series of LF Projects, LLC." }]
 keywords = ["mcp", "llm", "automation", "conformance", "testing"]
 license = { text = "MIT" }
-dependencies = ["anyio>=4.5", "click>=8.2.0", "httpx>=0.27", "mcp", "starlette", "uvicorn"]
+dependencies = ["anyio>=4.5", "click>=8.2.0", "httpx2>=2.5.0", "mcp", "starlette", "uvicorn"]
 
 [project.scripts]
 mcp-everything-server = "mcp_everything_server.server:main"

examples/servers/simple-auth/mcp_simple_auth/token_verifier.py

@@ -33,18 +33,18 @@ def __init__(
 
     async def verify_token(self, token: str) -> AccessToken | None:
         """Verify token via introspection endpoint."""
-        import httpx
+        import httpx2
 
         # Validate URL to prevent SSRF attacks
         if not self.introspection_endpoint.startswith(("https://", "http://localhost", "http://127.0.0.1")):
             logger.warning(f"Rejecting introspection endpoint with unsafe scheme: {self.introspection_endpoint}")
             return None
 
         # Configure secure HTTP client
-        timeout = httpx.Timeout(10.0, connect=5.0)
-        limits = httpx.Limits(max_connections=10, max_keepalive_connections=5)
+        timeout = httpx2.Timeout(10.0, connect=5.0)
+        limits = httpx2.Limits(max_connections=10, max_keepalive_connections=5)
 
-        async with httpx.AsyncClient(
+        async with httpx2.AsyncClient(
             timeout=timeout,
             limits=limits,
             verify=True,  # Enforce SSL verification

examples/servers/simple-auth/pyproject.toml

@@ -9,7 +9,7 @@ license = { text = "MIT" }
 dependencies = [
     "anyio>=4.5",
     "click>=8.2.0",
-    "httpx>=0.27",
+    "httpx2>=2.5.0",
     "mcp",
     "pydantic>=2.0",
     "pydantic-settings>=2.5.2",