Apply the redirect rule to OAuth's own requests; clearer message for an https-to-http redirect

Second round of review follow-ups for the origin-scoped redirect handling:

- The rule "follow a redirect only within the request's origin, only when it
  keeps the method" now lives in one predicate, next_request_within_origin,
  which also declines a Location that carries userinfo (httpx2 would send it
  as Basic auth).
- OAuthClientProvider and IdentityAssertionOAuthProvider apply that rule to
  the requests their flows make (metadata discovery, registration, token,
  refresh) through a small RedirectAwareAuth base, instead of those requests
  following nothing. A redirect elsewhere is still handed to the flow as a
  non-success, and the registration/token/refresh errors now name it.
- When the redirect budget (the client's max_redirects) is spent, the last
  redirect is handed back unfollowed like any other, so a redirect loop fails
  the one call with the usual error instead of raising TooManyRedirects out
  of the transport.
- The "not followed" error for an https endpoint redirected to plain http on
  the same host explains the likely cause (a TLS-terminating proxy the server
  does not trust, often plus a trailing slash) and suggests the https form of
  the location rather than the http one; locations are printed without query
  or userinfo.
- docs: the OAuth and transports pages describe the shared rule; the ASGI
  mounting example points clients at /notes/ (the path that does not redirect).

Author: maxisbey

docs/client/oauth-clients.md

@@ -83,7 +83,7 @@ The first time `Client` sends a request, the server answers `401`. The provider
 
 After that it is quiet. Tokens come out of storage, an expired access token is refreshed with the refresh token, and only when none of that works does it run the flow again.
 
-One transport rule applies to all of these requests: they are made while an MCP request is in flight, and like it they do not follow redirects to other addresses (they follow none at all), so the metadata, registration and token URLs must answer directly.
+One transport rule applies to all of these requests: like the MCP request they run inside, they follow a redirect only when it stays on the same origin and keeps the method (a trailing-slash 307/308, say), and treat any other redirect as that URL not answering.
 
 You wrote none of it. Two keyword arguments remain (`client_metadata_url` and `validate_resource_url`), and this file needs neither. `client_metadata_url` is the one worth knowing about; it gets its own section below.
 

docs/client/transports.md

@@ -76,9 +76,8 @@ environment variables or pass an explicit `verify=ssl_context` to your `httpx2.A
     `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, with one exception: redirects. MCP requests follow the same-origin rule above rather
-    than the client's `follow_redirects`, and requests an `auth=` handler makes while one is in flight
-    (OAuth discovery, registration, token) do not follow redirects, so those URLs must answer directly.
-    It is also where OAuth plugs in:
+    than the client's `follow_redirects`, and the requests the SDK's OAuth providers make while one is
+    in flight (discovery, registration, token) follow that rule too. It is also where OAuth plugs in:
     `httpx2.AsyncClient(auth=OAuthClientProvider(...))`. That whole flow is **[OAuth clients](oauth-clients.md)**.
 
 ## stdio

docs/run/asgi.md

@@ -94,7 +94,7 @@ That trailing `/mcp` is `streamable_http_path`. Set it to `"/"` and the mount pr
 --8<-- "docs_src/asgi/tutorial004.py"
 ```
 
-Now clients connect to `/notes`, not `/notes/mcp`.
+Now clients connect to `/notes/`, not `/notes/mcp`.
 
 ## CORS for browser clients
 

src/mcp/client/auth/extensions/identity_assertion.py

@@ -39,6 +39,7 @@
     union_scopes,
     validate_metadata_issuer,
 )
+from mcp.shared._httpx_utils import RedirectAwareAuth, redirect_note
 from mcp.shared.auth import JWT_BEARER_GRANT_TYPE, OAuthClientInformationFull, OAuthToken
 from mcp.shared.auth_utils import calculate_token_expiry, resource_url_from_server_url
 
@@ -56,7 +57,7 @@ def _origin(url: str) -> tuple[str, str, int | None]:
     return (parsed.scheme, parsed.hostname or "", port)
 
 
-class IdentityAssertionOAuthProvider(httpx2.Auth):
+class IdentityAssertionOAuthProvider(RedirectAwareAuth):
     """`httpx2.Auth` for the SEP-990 ID-JAG flow (RFC 7523 jwt-bearer grant) against a configured AS.
 
     The authorization server `issuer` is fixed at construction; metadata is fetched from its
@@ -159,7 +160,7 @@ def _build_token_request(self, scope: str | None, assertion: str) -> httpx2.Requ
             data["client_secret"] = self._client.client_secret
         return httpx2.Request("POST", self._token_endpoint, data=data, headers=headers)
 
-    async def async_auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx2.Request, httpx2.Response]:
+    async def _auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx2.Request, httpx2.Response]:
         async with self._lock:
             if not self._initialized:
                 self._tokens = await self._storage.get_tokens()
@@ -201,7 +202,9 @@ async def async_auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx
             token_response = yield self._build_token_request(scope_to_request, assertion)
             if token_response.status_code != 200:
                 body = (await token_response.aread()).decode(errors="replace")
-                raise OAuthTokenError(f"Token exchange failed ({token_response.status_code}): {body}")
+                raise OAuthTokenError(
+                    f"Token exchange failed ({token_response.status_code}){redirect_note(token_response)}: {body}"
+                )
             tokens = await handle_token_response_scopes(token_response)
             if tokens.scope is None:
                 tokens.scope = scope_to_request

src/mcp/client/auth/oauth2.py

@@ -41,6 +41,7 @@
     validate_authorization_response_iss,
     validate_metadata_issuer,
 )
+from mcp.shared._httpx_utils import RedirectAwareAuth, redirect_note
 from mcp.shared.auth import (
     AuthorizationCodeResult,
     OAuthClientInformationFull,
@@ -276,7 +277,7 @@ def prepare_token_auth(
         return data, headers
 
 
-class OAuthClientProvider(httpx2.Auth):
+class OAuthClientProvider(RedirectAwareAuth):
     """OAuth2 authentication for httpx2.
 
     Handles OAuth flow with automatic client registration and token storage.
@@ -469,7 +470,9 @@ async def _handle_token_response(self, response: httpx2.Response) -> None:
         if response.status_code not in {200, 201}:
             body = await response.aread()
             body_text = body.decode("utf-8")
-            raise OAuthTokenError(f"Token exchange failed ({response.status_code}): {body_text}")
+            raise OAuthTokenError(
+                f"Token exchange failed ({response.status_code}){redirect_note(response)}: {body_text}"
+            )
 
         # Parse and validate response with scope validation
         token_response = await handle_token_response_scopes(response)
@@ -519,7 +522,7 @@ async def _refresh_token(self) -> httpx2.Request:
     async def _handle_refresh_response(self, response: httpx2.Response) -> bool:
         """Handle token refresh response. Returns True if successful."""
         if response.status_code != 200:
-            logger.warning(f"Token refresh failed: {response.status_code}")
+            logger.warning(f"Token refresh failed: {response.status_code}{redirect_note(response)}")
             self.context.clear_tokens()
             return False
 
@@ -577,8 +580,8 @@ async def _validate_resource_match(self, prm: ProtectedResourceMetadata) -> None
         if not check_resource_allowed(requested_resource=default_resource, configured_resource=prm_resource):
             raise OAuthFlowError(f"Protected resource {prm_resource} does not match expected {default_resource}")
 
-    async def async_auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx2.Request, httpx2.Response]:
-        """httpx2 auth flow integration."""
+    async def _auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx2.Request, httpx2.Response]:
+        """The OAuth flow proper; `async_auth_flow` drives it (see `RedirectAwareAuth`)."""
         async with self.context.lock:
             if not self._initialized:
                 await self._initialize()

src/mcp/client/auth/utils.py

@@ -8,6 +8,7 @@
 from pydantic_core import from_json
 
 from mcp.client.auth import OAuthFlowError, OAuthRegistrationError, OAuthTokenError
+from mcp.shared._httpx_utils import redirect_note
 from mcp.shared.auth import (
     OAuthClientInformationFull,
     OAuthClientMetadata,
@@ -297,7 +298,9 @@ async def handle_registration_response(response: Response) -> OAuthClientInforma
     """Handle registration response."""
     if response.status_code not in (200, 201):
         await response.aread()
-        raise OAuthRegistrationError(f"Registration failed: {response.status_code} {response.text}")
+        raise OAuthRegistrationError(
+            f"Registration failed: {response.status_code}{redirect_note(response)} {response.text}"
+        )
 
     try:
         content = await response.aread()

src/mcp/client/sse.py

@@ -57,8 +57,8 @@ async def sse_client(
             (same scheme, host and port, or http to https on the same host with default ports) and
             keeps the request method; any other redirect is not followed, so connecting fails with
             `httpx2.HTTPStatusError` for the redirect response. The client's `follow_redirects`
-            setting is not consulted, and requests `auth` makes during an MCP request do not follow
-            redirects.
+            setting is not consulted; the SDK's OAuth providers apply the same rule to the requests
+            they make.
         auth: Optional httpx2 authentication handler.
         on_session_created: Optional callback invoked with the session ID when received.
     """

src/mcp/client/streamable_http.py

@@ -71,7 +71,16 @@ def _unfollowed_redirect(response: httpx2.Response) -> str | None:
     """Describe a redirect `stream_within_origin` left unfollowed, or None if `response` is not one."""
     if response.next_request is None:
         return None
-    location = response.next_request.url
+    sent = response.request.url
+    # Query and userinfo are left out: they can carry state that does not belong in logs.
+    location = response.next_request.url.copy_with(userinfo=b"", query=None, fragment=None)
+    if sent.scheme == "https" and location.scheme == "http" and location.host == sent.host:
+        return (
+            f"Redirect to {location} not followed: it would downgrade this HTTPS endpoint to plain HTTP.\n"
+            "The server is likely behind a TLS-terminating proxy whose forwarded headers it does not trust,\n"
+            f"often combined with a trailing-slash difference. Try {location.copy_with(scheme='https')} instead, "
+            "or fix the proxy settings."
+        )
     return f"Redirect to {location} not followed; use that URL as the endpoint if it is the intended server"
 
 
@@ -687,8 +696,8 @@ async def streamable_http_client(
             endpoint's origin (same scheme, host and port, or http to https on the same host with
             default ports) and keeps the request method (307/308); any other redirect is not
             followed and the message it answered fails with an error naming the location. The
-            client's `follow_redirects` setting is not consulted, and requests its `auth` handler
-            makes during an MCP request do not follow redirects.
+            client's `follow_redirects` setting is not consulted; the SDK's OAuth providers apply the
+            same rule to the requests they make.
         terminate_on_close: If True, send a DELETE request to terminate the session when the context exits.
 
     Yields:

src/mcp/shared/_httpx_utils.py

@@ -1,6 +1,7 @@
 """Utilities for creating and using httpx2 AsyncClient instances in the MCP transports."""
 
-from collections.abc import AsyncIterator
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 from typing import Any, Protocol
 
@@ -15,6 +16,9 @@
 # The headers httpx2.AsyncClient.sse() adds to an event-stream request.
 _SSE_HEADERS = {"Accept": "text/event-stream", "Cache-Control": "no-store"}
 
+# How many redirects one auth-flow request may follow within its origin (see RedirectAwareAuth).
+_AUTH_REDIRECT_LIMIT = 5
+
 
 class McpHttpClientFactory(Protocol):  # pragma: no branch
     def __call__(  # pragma: no branch
@@ -78,51 +82,65 @@ def _within_origin(url: httpx2.URL, location: httpx2.URL) -> bool:
     )
 
 
+def next_request_within_origin(response: httpx2.Response) -> httpx2.Request | None:
+    """The request that follows `response`'s redirect, if it is one the MCP transports follow.
+
+    That is when httpx2 built a next request for it (a redirect status with a
+    Location), the next request keeps the method (307/308, or any redirect of a
+    GET: httpx2 turns a POST into a body-less GET for 301/302/303, which would
+    drop the message), its URL stays within the origin of the request just sent
+    (same scheme, host and port, or http to https on the same host with default
+    ports), and the Location carries no userinfo (which httpx2 would otherwise
+    send as Basic auth). None for anything else, including a non-redirect.
+    """
+    next_request = response.next_request
+    if next_request is None:
+        return None
+    sent = response.request
+    if (
+        next_request.method != sent.method
+        or next_request.url.userinfo
+        or not _within_origin(sent.url, next_request.url)
+    ):
+        return None
+    return next_request
+
+
 @asynccontextmanager
 async def stream_within_origin(
     client: httpx2.AsyncClient, method: str, url: httpx2.URL | str, **kwargs: Any
-) -> AsyncIterator[httpx2.Response]:
+) -> AsyncGenerator[httpx2.Response]:
     """`client.stream(...)`, following redirects only while they stay within the request's origin.
 
     An MCP transport talks to one configured endpoint, and everything on a request
-    (headers, auth, body) was configured for that endpoint. A redirect that stays
-    on the origin of the request just sent (same scheme, host and port, or http to
-    https on the same host with default ports) and keeps the request's method,
-    such as a 307/308 trailing-slash normalisation, is followed using httpx2's
-    own next-request rules. Any other redirect is not followed: the redirect
-    response itself is yielded, the way httpx2 hands one back when
-    `follow_redirects` is off, and the caller treats it as the non-success it
-    is. (httpx2 rewrites a POST into a body-less GET for 301/302/303, which
-    would drop the message, so those count as not followed for anything but a
-    GET.) The client's own `follow_redirects` setting is not consulted, and
-    requests an `httpx2.Auth` flow makes during the call are sent the same way,
-    so they do not follow redirects either.
-
-    Raises:
-        httpx2.TooManyRedirects: More than `client.max_redirects` redirects were followed.
+    (headers, auth, body) was configured for that endpoint. A redirect that
+    `next_request_within_origin` accepts, such as a 307/308 trailing-slash
+    normalisation, is followed, at most `client.max_redirects` times. Any other
+    redirect (or one past that budget) is not followed: the redirect response
+    itself is yielded, the way httpx2 hands one back when `follow_redirects` is
+    off, and the caller treats it as the non-success it is. The client's own
+    `follow_redirects` setting is not consulted. Requests an `httpx2.Auth` flow
+    makes during the call are sent without following either; the SDK's OAuth
+    providers apply the same rule to their own requests.
     """
     request = client.build_request(method, url, **kwargs)
-    for _ in range(client.max_redirects + 1):
+    followed = 0
+    while True:
         response = await client.send(request, stream=True, follow_redirects=False)
-        # Set by httpx2, with its own method/body/header rules, only when the response is a redirect.
-        next_request = response.next_request
-        if (
-            next_request is None
-            or next_request.method != response.request.method
-            or not _within_origin(response.request.url, next_request.url)
-        ):
-            try:
-                yield response
-            finally:
-                await response.aclose()
-            return
+        next_request = next_request_within_origin(response)
+        if next_request is None or followed == client.max_redirects:
+            break
         try:
             # Drain the redirect body so the connection returns to the pool, as httpx2 does when it follows.
             await response.aread()
         finally:
             await response.aclose()
         request = next_request
-    raise httpx2.TooManyRedirects("Exceeded maximum allowed redirects.", request=request)
+        followed += 1
+    try:
+        yield response
+    finally:
+        await response.aclose()
 
 
 async def request_within_origin(
@@ -137,9 +155,53 @@ async def request_within_origin(
 @asynccontextmanager
 async def sse_within_origin(
     client: httpx2.AsyncClient, url: httpx2.URL | str, *, headers: dict[str, str] | None = None
-) -> AsyncIterator[httpx2.EventSource]:
+) -> AsyncGenerator[httpx2.EventSource]:
     """`client.sse(url)` with the redirect handling of `stream_within_origin`."""
     merged = httpx2.Headers(_SSE_HEADERS)
     merged.update(headers or {})
     async with stream_within_origin(client, "GET", url, headers=merged) as response:
         yield httpx2.EventSource(response)
+
+
+def redirect_note(response: httpx2.Response) -> str:
+    """A suffix naming the location of a redirect response that was not followed, else empty."""
+    if response.next_request is None:
+        return ""
+    return f" (redirected to {response.next_request.url}; not followed)"
+
+
+class RedirectAwareAuth(ABC, httpx2.Auth):
+    """An `httpx2.Auth` whose own requests follow redirects the way MCP transport requests do.
+
+    The transports send every request with redirect following off and follow a
+    redirect themselves only within the endpoint's origin (`stream_within_origin`).
+    httpx2 applies that per-request setting to the requests an auth flow makes
+    too (metadata discovery, registration, token), so on their own those would
+    follow nothing. Subclasses write their flow as `_auth_flow`; this class
+    drives it and, for each request the flow makes other than the one being
+    authenticated, follows a redirect that `next_request_within_origin` accepts,
+    up to `_AUTH_REDIRECT_LIMIT` times. Any other redirect response is handed
+    to the flow as it is.
+    """
+
+    @abstractmethod
+    def _auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx2.Request, httpx2.Response]:
+        """The subclass's flow, written as `httpx2.Auth.async_auth_flow` otherwise would be."""
+
+    async def async_auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx2.Request, httpx2.Response]:
+        flow = self._auth_flow(request)
+        try:
+            outgoing = await flow.__anext__()
+            while True:
+                response = yield outgoing
+                if outgoing is not request:
+                    for _ in range(_AUTH_REDIRECT_LIMIT):
+                        follow = next_request_within_origin(response)
+                        if follow is None:
+                            break
+                        response = yield follow
+                outgoing = await flow.asend(response)
+        except StopAsyncIteration:
+            return
+        finally:
+            await flow.aclose()