Follow redirects only within the MCP endpoint's origin

Merged
MA
2mo ago
+1029-205

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→https on 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's max_redirects — a 301/302/303 answering a POST is not, because httpx2 would replay it as a body-less GET, and neither is a Location carrying userinfo;
  • any other redirect (including one past the max_redirects budget, 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 an MCPError naming 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 with httpx2.HTTPStatusError for the redirect response. When an https endpoint redirects to plain http on the same host — usually a TLS-terminating proxy the server doesn't trust plus a trailing slash — the error says so and suggests the https form of the location, never the http one.

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 with follow_redirects=True is still scoped; the SSE form sends the headers AsyncClient.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_client with 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 with MCPError while the next call on the same session succeeds, and that origin is never contacted; the SSE connect equivalents. These fail on main and 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 in Unexpected content type (caller-supplied client). The http→https allowance 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.TooManyRedirects out of the transport.
  • follow_redirects on 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_client no longer enables follow_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=True when building a client; docs/client/transports.md and docs/client/oauth-clients.md describe the redirect behaviour, the docs/migration.md passages that told v1 users to set the flag are corrected, and docs/run/asgi.md points clients at the mounted path that doesn't redirect. Translated pages aren't regenerated in this PR.
  • examples/servers/simple-tool fetched arbitrary web pages through the private MCP client factory; it now uses a plain httpx2.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.

AI Disclaimer