Follow redirects only within the MCP endpoint's origin
Redirect handling in the HTTP client transports depended on who built the httpx2.AsyncClient: the SDK's default client followed every redirect, while a client you pass in (the way to set headers or auth on 2.x) followed none unless you added follow_redirects=True, which the docs told you to do. This moves redirect handling into the transports themselves and scopes it to the endpoint's origin, so it behaves the same for every client and a redirect can't quietly move a connection to a different host.
Motivation and Context
follow_redirects=True was turned on in the client factory for trailing-slash 307s from Starlette-mounted servers (#105, #732) and hosted servers that redirect (#283) — same-origin redirects. Following any redirect also meant the transport would carry on against whatever host a Location header named, re-sending what was configured for the original endpoint (headers, auth, request body) there and treating the answer as the MCP server's. httpx2 leaves following off by default and keeps that kind of policy out of the library (encode/httpx#2533), so it belongs in the transport.
streamable_http_client and sse_client now send each request with following disabled at the request level and handle a redirect themselves:
- a redirect that stays on the endpoint's origin (same scheme, host and port, or
http→httpson the same host with default ports) and keeps the request method (307/308; any status for a GET) is followed, using httpx2's own next-request construction, up to the client'smax_redirects— a 301/302/303 answering a POST is not, because httpx2 would replay it as a body-less GET, and neither is aLocationcarrying userinfo; - any other redirect (including one past the
max_redirectsbudget, so a loop too) is not followed, and no request is made to its location. The transport gets the redirect response back unfollowed, exactly as httpx2 hands one back with following off, and treats it as the non-success it is: a message POST or a resumption GET resolves that call with anMCPErrornaming the location while the session stays usable (the per-request shape every other non-2xx already has on 2.x), the standalone GET stream logs it and stops rather than retrying, and the SSE connect fails withhttpx2.HTTPStatusErrorfor the redirect response. When anhttpsendpoint redirects to plainhttpon the same host — usually a TLS-terminating proxy the server doesn't trust plus a trailing slash — the error says so and suggests thehttpsform of the location, never thehttpone.
This holds whichever client is in use, so a caller-supplied client no longer needs follow_redirects=True for the trailing-slash case, and setting it doesn't widen what the transport follows. httpx2 applies the per-request setting to the requests an auth= flow makes as well, so OAuthClientProvider and IdentityAssertionOAuthProvider apply the same rule to their own requests (discovery, registration, token, refresh) through a small shared base: a within-origin, method-preserving redirect is followed, anything else is treated as that URL not answering (discovery moves on to the next well-known candidate; registration/token errors name the redirect). create_mcp_http_client drops follow_redirects=True and keeps only the timeouts.
How Has This Been Tested?
- Helper tests over
httpx2.MockTransport(tests/shared/test_httpx_utils.py): same-origin, relative and https-upgrade redirects followed with method and body intact and the intermediate response closed; other host, other port, subdomain, other scheme, https→http, 301/302/303-on-POST and userinfo locations handed back unfollowed with no request recorded for the location; the hop budget hands back the next redirect; a client built withfollow_redirects=Trueis still scoped; the SSE form sends the headersAsyncClient.sse()sends. OAuth flow tests: a flow request follows a same-origin redirect, hands back a cross-origin one, and stops after a few hops. - Transport tests through
Client/sse_clientwith in-process transports: Starlette's/mcp→/mcp/redirect is followed with a caller-supplied client left at httpx2's default; a redirect to another origin fails that one call withMCPErrorwhile the next call on the same session succeeds, and that origin is never contacted; the SSE connect equivalents. These fail onmainand pass here. - By hand against uvicorn on loopback: a
Mount-induced 307 is followed and tool calls work with default, no-follow and follow-enabled clients; an endpoint that 307s to a different port fails the call with the error above and the second server logs no request; an OAuth flow whose first metadata candidate 307s to another port skips it (that port sees nothing) and whose registration endpoint 308s to/register/registers normally; a same-origin redirect loop fails the one call and the session carries on. - The existing streamable HTTP and SSE suites exercise the new path on every connection (their in-process apps are
Mounted, so each one rides a real 307). Full suite with coverage, pyright and ruff pass locally.
Breaking Changes
- A redirect from the MCP endpoint to a different origin (or a 301/302/303 answering a POST) is no longer followed: the call fails with
MCPError("Redirect to … not followed; use that URL as the endpoint if it is the intended server") instead of being followed (SDK default client) or ending inUnexpected content type(caller-supplied client). Thehttp→httpsallowance applies only when neither side names a non-default port. - Requests the SDK's OAuth providers make follow the same rule; previously they followed whatever the client was configured to follow. A redirect loop now fails the one call instead of raising
httpx2.TooManyRedirectsout of the transport. follow_redirectson a caller-supplied client is no longer consulted for MCP requests; same-origin redirects are followed regardless of it.- The private
mcp.shared._httpx_utils.create_mcp_http_clientno longer enablesfollow_redirects.
Types of changes
- Bug fix (non-breaking change which fixes an issue)
- New feature (non-breaking change which adds functionality)
- Breaking change (fix or feature that would cause existing functionality to change)
- Documentation update
Checklist
- I am assigned to the linked issue (or it is labeled
help wanted, or I'm a maintainer) - I have disclosed any AI assistance and can explain the change in my own words
- I have read the MCP Documentation
- My code follows the repository's style guidelines
- New and existing tests pass locally
- I have added appropriate error handling
- I have added or updated documentation as needed
Additional context
- Docs and examples no longer pass
follow_redirects=Truewhen building a client;docs/client/transports.mdanddocs/client/oauth-clients.mddescribe the redirect behaviour, thedocs/migration.mdpassages that told v1 users to set the flag are corrected, anddocs/run/asgi.mdpoints clients at the mounted path that doesn't redirect. Translated pages aren't regenerated in this PR. examples/servers/simple-toolfetched arbitrary web pages through the private MCP client factory; it now uses a plainhttpx2.AsyncClient(follow_redirects=True)of its own.- Supersedes #3075, which scoped redirects at the client factory only and had grown well past that; this is the smaller change at the transport.