[v1.x] Follow redirects only within the MCP endpoint's origin

Merged
MA
2mo ago
+948-192

v1.x backport of #3397.

streamable_http_client / streamablehttp_client and sse_client on 1.x now follow a redirect only when it stays on the endpoint's origin and keeps the request method, whoever built the httpx.AsyncClient, and OAuthClientProvider applies the same rule to the requests its flow makes.

Motivation and Context

Same as #3397. On 1.x the default client from create_mcp_http_client followed every redirect, so a Location naming another host moved the connection there with everything configured for the endpoint (headers, auth, request body), while a caller-supplied client followed none unless it set follow_redirects=True, which the examples did. The transports now send each request with following off and re-send httpx's own next request only when it stays on the origin (same scheme, host and port, or http→https on the same host with default ports), keeps the method (307/308; any status for a GET) and carries no userinfo, up to the client's max_redirects. Anything else is handed back unfollowed and no request is made to its location.

Differences from #3397:

  • 1.x has no per-request error path for HTTP failures: a non-2xx answer to a message POST raises httpx.HTTPStatusError inside the transport's task group and ends the connection. An unfollowed redirect does the same, with the message from #3397 ("Redirect to … not followed; use that URL as the endpoint if it is the intended server", and the TLS-terminating-proxy explanation for an https→http downgrade) in place of httpx's generic redirect text. The standalone GET stream logs it and stops, as on main.
  • httpx / httpx-sse instead of httpx2: the SSE helper adds the two headers aconnect_sse adds and yields httpx_sse.EventSource. Checked against httpx 0.28.1 and 0.27.2 (the lowest-direct floor).
  • Only OAuthClientProvider defines an auth flow on 1.x (the client-credentials providers subclass it), so it is the only class moved onto the RedirectAwareAuth base; async_auth_flow keeps its name and signature.
  • sse_client now also closes its receive streams in its finally; before, failing to connect (which the new test does on purpose) left them to the garbage collector.
  • Docs: a short "HTTP redirects" section in docs/client.md; docs/authorization.md and the examples drop follow_redirects=True. 1.x has no deploy page, so the proxy hint lives in that section.

How Has This Been Tested?

  • tests/shared/test_httpx_utils.py (ported): within-origin, relative, host-case/port-normalised and https-upgrade redirects followed with method and body and the intermediate response closed; other host / port / subdomain / scheme, https→http, 301/302/303-on-POST and userinfo locations handed back with no request to the location; max_redirects budget; a follow_redirects=True client is still scoped; SSE headers; auth sub-requests inherit no-follow.
  • Transport tests: Starlette's /mcp → /mcp/ 307 over a real uvicorn server is followed with a caller-supplied client at httpx's default; a 307 to another origin with a follow_redirects=True client ends the connection with HTTPStatusError carrying the message above and that origin is never contacted; GET stream gives up after one request; resumption GET; the three message texts; sse_client follows /sse → /sse/ and refuses another origin. OAuth: a flow request follows a same-origin redirect, hands back a cross-origin one, stops after five hops; a 3xx discovery answer means "try the next URL"; the registration error names the redirect without userinfo or query. The behaviour tests fail on v1.x and pass here (the helper module imports names v1.x lacks, so it cannot be collected there).
  • By hand over loopback with uvicorn: the Mount 307 is followed and call_tool works for the default client, a no-follow client, a follow_redirects=True client and streamablehttp_client(headers=…); an endpoint that 307s to another port fails with the error above for all four and for sse_client, and the other port logs nothing (on v1.x it receives the initialize POST with the caller's headers); 301-on-POST and a userinfo Location are not followed; a same-origin loop stops at max_redirects; an OAuth flow whose first metadata URL 307s to another port skips it and whose registration endpoint 308s to /register/ registers normally.
  • Full suite with coverage, pyright, ruff, markdownlint and mkdocs build --strict pass locally.

Breaking Changes

  • A redirect from the MCP endpoint to another origin, or a 301/302/303 answering a POST, is no longer followed; connecting or the call fails with httpx.HTTPStatusError as for any non-2xx response. The http→https allowance applies only when neither side names a non-default port.
  • follow_redirects on a caller-supplied client is not consulted for MCP requests; same-origin redirects are followed regardless of it, so the trailing-slash case no longer needs the flag.
  • OAuthClientProvider's own requests follow the same rule; a 3xx from a metadata URL is treated like a 4xx. A redirect loop ends at the client's max_redirects with HTTPStatusError rather than httpx.TooManyRedirects.
  • The private 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

examples/servers/simple-tool fetched arbitrary pages through the private client factory and relied on it following redirects; it now builds its own httpx.AsyncClient(follow_redirects=True). The session-termination-204 test patched AsyncClient.delete, which the transport no longer calls, so it wraps the HTTP transport instead.

AI Disclaimer