Port the httpx2 migration notes into the restructured docs

The migration guide and client docs were reorganized on main after the
swap branched: re-add the httpx2 section under Packaging with rows in
the dependency table, convert the After-v2 examples that arrived with
the reorganization (Before-v1 blocks keep httpx), and surface the
system-trust-store TLS note on the transports page.

No-Verification-Needed: documentation-only change

Author: maxisbey

docs/client/transports.md

@@ -29,7 +29,7 @@ Pass a URL string and you get **Streamable HTTP**, the transport you deploy behi
 --8<-- "docs_src/client_transports/tutorial002.py"
 ```
 
-That is the whole production client. `Client` wraps the URL in `streamable_http_client(...)` for you, on top of an `httpx.AsyncClient` configured the way MCP needs: `follow_redirects=True`, a 30-second timeout for connect/write/pool, and a 300-second read timeout because the server may hold a response stream open.
+That is the whole production client. `Client` wraps the URL in `streamable_http_client(...)` for you, on top of an `httpx2.AsyncClient` configured the way MCP needs: `follow_redirects=True`, a 30-second timeout for connect/write/pool, and a 300-second read timeout because the server may hold a response stream open.
 
 !!! check
     A `Client` you have constructed is **not** connected. Construction only picks the transport;
@@ -41,19 +41,25 @@ That is the whole production client. `Client` wraps the URL in `streamable_http_
 
     Nothing was resolved, fetched or spawned when you wrote `Client("http://...")`. That line is free.
 
-### Bring your own `httpx.AsyncClient`
+### Bring your own `httpx2.AsyncClient`
 
-The moment you need an `Authorization` header, a cookie, a proxy, mTLS, or a different timeout, build the `httpx.AsyncClient` yourself and hand it to `streamable_http_client`:
+The moment you need an `Authorization` header, a cookie, a proxy, mTLS, or a different timeout, build the `httpx2.AsyncClient` yourself and hand it to `streamable_http_client`:
 
 ```python title="client.py" hl_lines="8-14"
 --8<-- "docs_src/client_transports/tutorial003.py"
 ```
 
 Two things to notice:
 
-* You own the `httpx.AsyncClient`, so **you** enter and exit it. The SDK never closes a client it didn't create.
+* You own the `httpx2.AsyncClient`, so **you** enter and exit it. The SDK never closes a client it didn't create.
 * `streamable_http_client(url, http_client=...)` returns a transport, and `Client(transport)` accepts it like anything else.
 
+One TLS note: `httpx2` verifies certificates against the operating system trust store (via
+[`truststore`](https://pypi.org/project/truststore/)), not a bundled CA list. In an environment with
+no usable system CA store - some minimal containers - pass an explicit `verify=ssl_context` to your
+`httpx2.AsyncClient` (background in
+[`httpx` and `httpx-sse` replaced by `httpx2`](../migration.md#httpx-and-httpx-sse-replaced-by-httpx2)).
+
 !!! warning
     `streamable_http_client` used to take `headers=` and `timeout=` directly. It does not any more:
     its only parameters are `url`, `http_client` and `terminate_on_close`. Reach for `headers=` out
@@ -63,12 +69,13 @@ Two things to notice:
     TypeError: streamable_http_client() got an unexpected keyword argument 'headers'
     ```
 
-    Everything HTTP-shaped now lives on the one `httpx.AsyncClient` you pass in.
+    Everything HTTP-shaped now lives on the one `httpx2.AsyncClient` you pass in.
 
 !!! info
-    If you know `httpx`, you already know how to do auth, proxies, event hooks, retries and connection
-    limits here. The SDK adds nothing on top and takes nothing away. It is also where OAuth plugs in:
-    `httpx.AsyncClient(auth=OAuthClientProvider(...))`. That whole flow is **[OAuth clients](oauth-clients.md)**.
+    `httpx2` keeps the familiar `httpx` API, so if you know `httpx` you already know how to do auth,
+    proxies, event hooks, retries and connection limits here. The SDK adds nothing on top and takes
+    nothing away. It is also where OAuth plugs in:
+    `httpx2.AsyncClient(auth=OAuthClientProvider(...))`. That whole flow is **[OAuth clients](oauth-clients.md)**.
 
 ## stdio
 
@@ -106,7 +113,7 @@ A **transport** is any async context manager that yields a `(read, write)` pair
 
 * `Client(mcp)` (the server object) connects in memory. Use it for tests and for embedding.
 * `Client("http://.../mcp")` (a URL) connects over Streamable HTTP, the production transport.
-* Headers, auth, proxies and timeouts belong on an `httpx.AsyncClient` you pass to `streamable_http_client(url, http_client=...)`. There is no `headers=` keyword.
+* Headers, auth, proxies and timeouts belong on an `httpx2.AsyncClient` you pass to `streamable_http_client(url, http_client=...)`. There is no `headers=` keyword.
 * stdio is `Client(stdio_client(StdioServerParameters(...)))`, never the parameters object alone.
 * The subprocess gets an allow-listed environment, not yours; `env=` adds to it.
 * A transport is anything you can `async with x as (read, write)`. `Client` hands anything that isn't a server object or a URL straight to that protocol.

docs/migration.md

@@ -67,6 +67,9 @@ v2 raises the minimum versions of several shared dependencies and adds new requi
 | pywin32 (Windows) | `>=310` (Python <3.14) | `>=311` | floor raised on Python <3.14 |
 | opentelemetry-api | not a dependency | `>=1.28.0` | new required dependency |
 | mcp-types | not a dependency | `==<exact mcp version>` | new, exact-pinned |
+| httpx | `>=0.27.1,<1.0.0` | removed | see [`httpx` and `httpx-sse` replaced by `httpx2`](#httpx-and-httpx-sse-replaced-by-httpx2) |
+| httpx-sse | `>=0.4` | removed | see [`httpx` and `httpx-sse` replaced by `httpx2`](#httpx-and-httpx-sse-replaced-by-httpx2) |
+| httpx2 | not a dependency | `>=2.5.0` | new required dependency |
 | `ws` extra | `websockets>=15.0.1` | removed | see [WebSocket transport removed](#websocket-transport-removed) |
 
 **Before (v1):**
@@ -89,6 +92,46 @@ dependencies = [
 
 Relax or bump any conflicting pins when upgrading. sse-starlette jumps two majors, so a project that imports `sse_starlette` itself must also work through that library's own breaking changes to co-install with mcp v2. `opentelemetry-api` is a new hard dependency because every outbound request now carries a `_meta` envelope used for OpenTelemetry trace propagation; see [Every outbound request now carries a `_meta` envelope](#every-outbound-request-now-carries-a-_meta-envelope-opentelemetry-is-on-by-default). `mcp-types` is exact-pinned to the SDK version; nothing in a v1 tree can conflict with it, but do not pin `mcp-types` independently of `mcp`.
 
+### `httpx` and `httpx-sse` 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 swap itself does not change any SDK signatures - `streamable_http_client`
+and `sse_client` accept the same arguments as elsewhere in v2 - but the client
+type they expect is now `httpx2.AsyncClient`. If you construct your own client to pass as
+`http_client` (or build an `httpx2.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.
+
+TLS verification also changes: `httpx` validated certificates against the
+bundled `certifi` CA list, while `httpx2` validates against the operating
+system trust store via [`truststore`](https://pypi.org/project/truststore/).
+If your environment has no usable system CA store (some minimal containers),
+or you relied on certifi's bundle specifically, pass an explicit
+`verify=ssl_context` to your `httpx2.AsyncClient`.
+
 ### `mcp dev` and `mcp install` pin the spawned environment to your SDK version
 
 Both commands run your server through a fresh `uv run --with ...` environment. In v1 the
@@ -111,7 +154,7 @@ unchanged. Only the `mcp.types` submodule and `mcp.shared.version` were removed.
 package's API reference is at [`mcp_types`](api/mcp_types/index.md).
 
 **Why:** keeping the wire types in their own package lets tooling and lightweight clients
-depend on the protocol schema without pulling in `httpx`, `starlette`, `uvicorn`, and the
+depend on the protocol schema without pulling in `httpx2`, `starlette`, `uvicorn`, and the
 rest of the server/transport stack.
 
 **Before (v1):**
@@ -1594,13 +1637,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,
 )
@@ -1613,15 +1656,15 @@ 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.
 
 ### `get_session_id` callback removed from `streamable_http_client`
 
 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.
 
 The `GetSessionIdCallback` type alias is gone as well, so `from mcp.client.streamable_http import GetSessionIdCallback` now raises `ImportError`. Drop the annotation, or inline `Callable[[], str | None]` if your own wrapper code still needs the type.
 
-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):**
 
@@ -1637,23 +1680,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,
 )
@@ -1667,7 +1710,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.
 
@@ -1730,7 +1773,7 @@ async with streamable_http_client(url) as (read, write):
                 raise
 ```
 
-Move HTTP-status failure handling from around the transport context to around the individual calls, catching `MCPError` (see [`McpError` renamed to `MCPError`](#mcperror-renamed-to-mcperror)). Connect-level failures such as `httpx.ConnectError` still escape the transport context as before; keep context-level handling for those only.
+Move HTTP-status failure handling from around the transport context to around the individual calls, catching `MCPError` (see [`McpError` renamed to `MCPError`](#mcperror-renamed-to-mcperror)). Connect-level failures such as `httpx2.ConnectError` still escape the transport context as before; keep context-level handling for those only.
 
 ### `terminate_windows_process` removed