Replace httpx and httpx-sse with httpx2 (#2972)

Co-authored-by: Max Isbey <224885523+maxisbey@users.noreply.github.com>

docs/client/identity-assertion.md

@@ -19,7 +19,7 @@ Everything below is the second request: the client that sends it and the authori
 
 ## The client
 
-**`IdentityAssertionOAuthProvider`** lives in `mcp.client.auth.extensions.identity_assertion`. Like every provider in **[OAuth clients](oauth-clients.md)** it is an `httpx.Auth`: construct one, put it on `auth=`, hand the `httpx.AsyncClient` to the transport.
+**`IdentityAssertionOAuthProvider`** lives in `mcp.client.auth.extensions.identity_assertion`. Like every provider in **[OAuth clients](oauth-clients.md)** it is an `httpx2.Auth`: construct one, put it on `auth=`, hand the `httpx2.AsyncClient` to the transport.
 
 ```python title="client.py" hl_lines="49-50 53-61"
 --8<-- "docs_src/identity_assertion/tutorial001.py"
@@ -139,7 +139,7 @@ And notice what the returned `OAuthToken` does not carry: a refresh token. The I
 
 * [SEP-990](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/990) lets the enterprise identity provider, not the end user, decide which MCP servers a client may reach. The IdP signs that decision into an **ID-JAG**.
 * Obtaining the ID-JAG is an [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693) token exchange against *your IdP*, and the SDK does not make it. Presenting it to the MCP authorization server is the [RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523) `jwt-bearer` grant, and the SDK does both sides of that.
-* `IdentityAssertionOAuthProvider` is another `httpx.Auth`: a pre-registered confidential client, a pinned `issuer`, and one `assertion_provider(audience, resource)` callback. No browser, no registration, no refresh token.
+* `IdentityAssertionOAuthProvider` is another `httpx2.Auth`: a pre-registered confidential client, a pinned `issuer`, and one `assertion_provider(audience, resource)` callback. No browser, no registration, no refresh token.
 * The authorization server is never discovered from the resource server. Configure `issuer` to exactly the string its metadata document serves; the comparison is character for character.
 * Server side, `identity_assertion_enabled=True` plus `exchange_identity_assertion`. The SDK authenticates the client and gates the grant; validating the ID-JAG is entirely yours, and the issued token is bound to the ID-JAG's `resource`, not the request's.
 

docs/client/oauth-clients.md

@@ -2,7 +2,7 @@
 
 Some MCP servers are protected. Send them a request without a token and they answer `401 Unauthorized`.
 
-**`OAuthClientProvider`** is how you get the token. It is not an MCP object at all. It is an `httpx.Auth`, the standard httpx hook for "do something to every request". You attach it to an `httpx.AsyncClient`, hand that client to the Streamable HTTP transport, and stop thinking about it.
+**`OAuthClientProvider`** is how you get the token. It is not an MCP object at all. It is an `httpx2.Auth`, the standard httpx2 hook for "do something to every request". You attach it to an `httpx2.AsyncClient`, hand that client to the Streamable HTTP transport, and stop thinking about it.
 
 This page is the client side. Making your own server demand a token is **[Authorization](../run/authorization.md)**.
 
@@ -68,9 +68,9 @@ A real client runs a small local HTTP server on the redirect URI instead of call
 
 ### Into the `Client`
 
-Look at `main()`. The provider goes on the **httpx client**, the httpx client goes into `streamable_http_client(url, http_client=...)`, and that transport goes into `Client`.
+Look at `main()`. The provider goes on the **httpx2 client**, the httpx2 client goes into `streamable_http_client(url, http_client=...)`, and that transport goes into `Client`.
 
-`streamable_http_client` has no `auth=` keyword. Anything HTTP-level (auth, headers, timeouts, proxies) belongs on the `httpx.AsyncClient` you bring. That layering is **[Client transports](transports.md)**.
+`streamable_http_client` has no `auth=` keyword. Anything HTTP-level (auth, headers, timeouts, proxies) belongs on the `httpx2.AsyncClient` you bring. That layering is **[Client transports](transports.md)**.
 
 ## What the provider does for you
 
@@ -103,7 +103,7 @@ The URL must be HTTPS with a non-root path; anything else is a `ValueError` at c
 
 A nightly job, a CI step, another service. There is no browser and nobody to click "allow". That is the **client credentials** grant: you already hold a `client_id` and a `client_secret`, and the token endpoint is the whole flow.
 
-`ClientCredentialsOAuthProvider` is the same `httpx.Auth`, minus the human:
+`ClientCredentialsOAuthProvider` is the same `httpx2.Auth`, minus the human:
 
 ```python title="client.py" hl_lines="4 27-33"
 --8<-- "docs_src/oauth_clients/tutorial002.py"
@@ -113,7 +113,7 @@ What changed:
 
 * No `OAuthClientMetadata`, no handlers. You pass `client_id` and `client_secret`; the provider builds a minimal `client_credentials` registration around them and skips dynamic registration entirely.
 * `scopes` is a space-separated string, the OAuth wire format.
-* Everything downstream is identical: the same `TokenStorage`, the same `httpx.AsyncClient(auth=...)`, the same `streamable_http_client`.
+* Everything downstream is identical: the same `TokenStorage`, the same `httpx2.AsyncClient(auth=...)`, the same `streamable_http_client`.
 
 By default the secret travels as HTTP Basic auth on the token request (`client_secret_basic`). Pass `token_endpoint_auth_method="client_secret_post"` to put it in the form body instead. Some authorization servers only accept one of the two.
 
@@ -133,11 +133,11 @@ There is one more no-human situation: the client belongs to an enterprise whose
 
 When the OAuth flow goes wrong, the provider raises an `OAuthFlowError` from `mcp.client.auth`. It has two subclasses. `OAuthRegistrationError` means the authorization server refused to register you. `OAuthTokenError` means the token endpoint said no. One `except OAuthFlowError:` covers discovery, registration, authorization, and exchange.
 
-Not everything is a flow error. The network can still fail; those are ordinary `httpx` exceptions and pass through untouched.
+Not everything is a flow error. The network can still fail; those are ordinary `httpx2` exceptions and pass through untouched.
 
 ## Recap
 
-* `OAuthClientProvider` is an `httpx.Auth`. Put it on an `httpx.AsyncClient`, pass that to `streamable_http_client(url, http_client=...)`, and `Client` never knows OAuth happened.
+* `OAuthClientProvider` is an `httpx2.Auth`. Put it on an `httpx2.AsyncClient`, pass that to `streamable_http_client(url, http_client=...)`, and `Client` never knows OAuth happened.
 * You supply four things: the server URL, an `OAuthClientMetadata`, a `TokenStorage`, and the redirect/callback handler pair.
 * `TokenStorage` is a `Protocol`: four async methods, no base class. Persist `client_info` as well as the tokens.
 * Discovery, registration (dynamic, or via a **Client ID Metadata Document**), PKCE, the `state` and `iss` checks, and token refresh are the provider's job, not yours.

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,9 +41,9 @@ 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"
@@ -51,9 +51,16 @@ The moment you need an `Authorization` header, a cookie, a proxy, mTLS, or a dif
 
 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), set the standard `SSL_CERT_FILE`/`SSL_CERT_DIR`
+environment variables or 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 +70,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 +114,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.