[v1.x] Follow redirects only within the MCP endpoint's origin (#3448)

Author: maxisbey

docs/authorization.md

@@ -151,7 +151,7 @@ async def main():
         callback_handler=handle_callback,
     )
 
-    async with httpx.AsyncClient(auth=oauth_auth, follow_redirects=True) as custom_client:
+    async with httpx.AsyncClient(auth=oauth_auth) as custom_client:
         async with streamable_http_client("http://localhost:8001/mcp", http_client=custom_client) as (read, write, _):
             async with ClientSession(read, write) as session:
                 await session.initialize()

docs/client.md

@@ -130,6 +130,29 @@ if __name__ == "__main__":
 _Full example: [examples/snippets/clients/streamable_basic.py](https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/examples/snippets/clients/streamable_basic.py)_
 <!-- /snippet-source -->
 
+To configure headers, authentication or timeouts, create an `httpx.AsyncClient` and pass it as `http_client=`.
+
+## HTTP redirects
+
+The transport connects to the URL you gave it, and only that origin.
+
+* A `307`/`308` redirect that stays on the same scheme, host and port is followed, and so is `http://` → `https://` on the same host. That covers the usual `/mcp` → `/mcp/` trailing-slash redirect.
+* A redirect anywhere else is **not** followed. Connecting fails with:
+
+    ```text
+    httpx.HTTPStatusError: Redirect to https://other.example.com/mcp not followed; use that URL as the endpoint if it is the intended server
+    ```
+
+    If that URL is the server you meant, put it in your config. If it isn't, the server or a proxy in front of it is misconfigured.
+
+This holds for any `httpx.AsyncClient` you pass in: its `follow_redirects` setting is not consulted for MCP requests, in either direction. The SDK's OAuth providers apply the same rule to their own requests, and so does `sse_client()`.
+
+!!! tip
+    `Redirect to http://… not followed: it would downgrade this HTTPS endpoint to plain HTTP` means the
+    server sits behind a TLS-terminating proxy it doesn't know about and is issuing `http://` redirects.
+    That is fixed on the server (for uvicorn: `--proxy-headers` and `--forwarded-allow-ips`), or by
+    using the exact `https://…/` URL the message suggests.
+
 ## Client Display Utilities
 
 When building MCP clients, the SDK provides utilities to help display human-readable names for tools, resources, and prompts:

examples/clients/simple-auth-client/mcp_simple_auth_client/main.py

@@ -212,7 +212,7 @@ async def _default_redirect_handler(authorization_url: str) -> None:
                     await self._run_session(read_stream, write_stream, None)
             else:
                 print("📡 Opening StreamableHTTP transport connection with auth...")
-                async with httpx.AsyncClient(auth=oauth_auth, follow_redirects=True) as custom_client:
+                async with httpx.AsyncClient(auth=oauth_auth) as custom_client:
                     async with streamable_http_client(
                         url=self.server_url,
                         http_client=custom_client,

examples/servers/simple-tool/mcp_simple_tool/server.py

@@ -2,17 +2,18 @@
 
 import anyio
 import click
+import httpx
 import mcp.types as types
 from mcp.server.lowlevel import Server
-from mcp.shared._httpx_utils import create_mcp_http_client
 from starlette.requests import Request
 
 
 async def fetch_website(
     url: str,
 ) -> list[types.ContentBlock]:
     headers = {"User-Agent": "MCP Test Server (github.com/modelcontextprotocol/python-sdk)"}
-    async with create_mcp_http_client(headers=headers) as client:
+    timeout = httpx.Timeout(30, read=300)
+    async with httpx.AsyncClient(headers=headers, timeout=timeout, follow_redirects=True) as client:
         response = await client.get(url)
         response.raise_for_status()
         return [types.TextContent(type="text", text=response.text)]

examples/snippets/clients/oauth_client.py

@@ -69,7 +69,7 @@ async def main():
         callback_handler=handle_callback,
     )
 
-    async with httpx.AsyncClient(auth=oauth_auth, follow_redirects=True) as custom_client:
+    async with httpx.AsyncClient(auth=oauth_auth) as custom_client:
         async with streamable_http_client("http://localhost:8001/mcp", http_client=custom_client) as (read, write, _):
             async with ClientSession(read, write) as session:
                 await session.initialize()

src/mcp/client/auth/oauth2.py

@@ -40,6 +40,7 @@
     validate_metadata_issuer,
 )
 from mcp.client.streamable_http import MCP_PROTOCOL_VERSION
+from mcp.shared._httpx_utils import RedirectAwareAuth, redirect_note
 from mcp.shared.auth import (
     OAuthClientInformationFull,
     OAuthClientMetadata,
@@ -224,7 +225,7 @@ def _origin_issuer(server_url: str) -> str:
     return str(AnyHttpUrl(f"{parsed.scheme}://{parsed.netloc}"))
 
 
-class OAuthClientProvider(httpx.Auth):
+class OAuthClientProvider(RedirectAwareAuth):
     """
     OAuth2 authentication for httpx.
     Handles OAuth flow with automatic client registration and token storage.
@@ -421,7 +422,9 @@ async def _handle_token_response(self, response: httpx.Response) -> None:
         if response.status_code != 200:
             body = await response.aread()  # pragma: no cover
             body_text = body.decode("utf-8")  # pragma: no cover
-            raise OAuthTokenError(f"Token exchange failed ({response.status_code}): {body_text}")  # pragma: no cover
+            raise OAuthTokenError(  # pragma: no cover
+                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)
@@ -464,7 +467,7 @@ async def _refresh_token(self) -> httpx.Request:
     async def _handle_refresh_response(self, response: httpx.Response) -> bool:  # pragma: no cover
         """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
 
@@ -508,8 +511,8 @@ def _expected_issuer(self) -> str:
         the 2025-03-26 well-known URL is built from (RFC 8414 §3.3)."""
         return self.context.auth_server_url or _origin_issuer(self.context.server_url)
 
-    async def async_auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.Request, httpx.Response]:
-        """HTTPX auth flow integration."""
+    async def _auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.Request, httpx.Response]:
+        """The OAuth flow proper; `async_auth_flow` drives it (see `RedirectAwareAuth`)."""
         async with self.context.lock:
             if not self._initialized:
                 await self._initialize()  # pragma: no cover

src/mcp/client/auth/utils.py

@@ -9,6 +9,7 @@
 
 from mcp.client.auth import OAuthFlowError, OAuthRegistrationError, OAuthTokenError
 from mcp.client.streamable_http import MCP_PROTOCOL_VERSION
+from mcp.shared._httpx_utils import redirect_note
 from mcp.shared.auth import (
     OAuthClientInformationFull,
     OAuthClientMetadata,
@@ -205,9 +206,9 @@ async def handle_auth_metadata_response(response: Response) -> tuple[bool, OAuth
             return True, asm
         except ValidationError:  # pragma: no cover
             return True, None
-    elif response.status_code < 400 or response.status_code >= 500:
-        return False, None  # Non-4XX error, stop trying
-    return True, None
+    elif 300 <= response.status_code < 500:
+        return True, None  # Not served at this URL (redirects are not followed) - try the next candidate
+    return False, None  # Server error or unexpected status, stop trying
 
 
 def validate_metadata_issuer(oauth_metadata: OAuthMetadata, expected_issuer: str) -> None:
@@ -262,7 +263,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

@@ -8,10 +8,15 @@
 import httpx
 from anyio.abc import TaskStatus
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
-from httpx_sse import SSEError, aconnect_sse
+from httpx_sse import SSEError
 
 import mcp.types as types
-from mcp.shared._httpx_utils import McpHttpClientFactory, create_mcp_http_client
+from mcp.shared._httpx_utils import (
+    McpHttpClientFactory,
+    create_mcp_http_client,
+    request_within_origin,
+    sse_within_origin,
+)
 from mcp.shared.message import SessionMessage
 
 logger = logging.getLogger(__name__)
@@ -47,6 +52,13 @@ async def sse_client(
         headers: Optional headers to include in requests.
         timeout: HTTP timeout for regular operations.
         sse_read_timeout: Timeout for SSE read operations.
+        httpx_client_factory: Factory function for creating the httpx client. Whichever client it
+            returns, MCP requests follow a redirect only when it stays on the endpoint's origin
+            (same scheme, host and port, or http to https on the same host with default ports) and
+            keeps the request method (any status for the SSE GET, 307/308 for a message POST); any
+            other redirect is not followed, so connecting fails with `httpx.HTTPStatusError` for
+            the redirect response. The client's `follow_redirects` setting is not consulted; the
+            SDK's OAuth providers apply the same rule to the requests they make.
         auth: Optional HTTPX authentication handler.
         on_session_created: Optional callback invoked with the session ID when received.
     """
@@ -65,11 +77,7 @@ async def sse_client(
             async with httpx_client_factory(
                 headers=headers, auth=auth, timeout=httpx.Timeout(timeout, read=sse_read_timeout)
             ) as client:
-                async with aconnect_sse(
-                    client,
-                    "GET",
-                    url,
-                ) as event_source:
+                async with sse_within_origin(client, url) as event_source:
                     event_source.response.raise_for_status()
                     logger.debug("SSE connection established")
 
@@ -135,7 +143,9 @@ async def post_writer(endpoint_url: str):
                             async with write_stream_reader:
                                 async for session_message in write_stream_reader:
                                     logger.debug(f"Sending client message: {session_message}")
-                                    response = await client.post(
+                                    response = await request_within_origin(
+                                        client,
+                                        "POST",
                                         endpoint_url,
                                         json=session_message.message.model_dump(
                                             by_alias=True,
@@ -161,3 +171,7 @@ async def post_writer(endpoint_url: str):
         finally:
             await read_stream_writer.aclose()
             await write_stream.aclose()
+            # The receive sides too, so that failing to connect (which raises before the
+            # streams are handed to the caller) does not leave them to the garbage collector.
+            await read_stream.aclose()
+            await write_stream_reader.aclose()

src/mcp/client/streamable_http.py

@@ -19,12 +19,16 @@
 import httpx
 from anyio.abc import TaskGroup
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
-from httpx_sse import EventSource, ServerSentEvent, aconnect_sse
+from httpx_sse import EventSource, ServerSentEvent
 from typing_extensions import deprecated
 
 from mcp.shared._httpx_utils import (
     McpHttpClientFactory,
     create_mcp_http_client,
+    redirect_location,
+    request_within_origin,
+    sse_within_origin,
+    stream_within_origin,
 )
 from mcp.shared.message import ClientMessageMetadata, SessionMessage
 from mcp.types import (
@@ -72,6 +76,28 @@ class ResumptionError(StreamableHTTPError):
     """Raised when resumption request is invalid."""
 
 
+def _unfollowed_redirect(response: httpx.Response) -> str | None:
+    """Describe a redirect `stream_within_origin` left unfollowed, or None if `response` is not one."""
+    location = redirect_location(response)
+    if location is None:
+        return None
+    if response.request.url.scheme == "https" and location.scheme == "http":
+        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"
+
+
+def _raise_for_unfollowed_redirect(response: httpx.Response) -> None:
+    """Raise `httpx.HTTPStatusError`, as `raise_for_status()` does for a redirect response, saying why
+    this one was not followed."""
+    if (redirect := _unfollowed_redirect(response)) is not None:
+        raise httpx.HTTPStatusError(redirect, request=response.request, response=response)
+
+
 @dataclass
 class RequestContext:
     """Context for a request operation."""
@@ -263,12 +289,11 @@ async def handle_get_stream(
                 if last_event_id:
                     headers[LAST_EVENT_ID] = last_event_id  # pragma: no cover
 
-                async with aconnect_sse(
-                    client,
-                    "GET",
-                    self.url,
-                    headers=headers,
-                ) as event_source:
+                async with sse_within_origin(client, self.url, headers=headers) as event_source:
+                    if (redirect := _unfollowed_redirect(event_source.response)) is not None:
+                        # The same GET would be redirected again, so retrying cannot help.
+                        logger.warning(f"GET stream not opened: {redirect}")
+                        return
                     event_source.response.raise_for_status()
                     logger.debug("GET SSE connection established")
 
@@ -311,12 +336,8 @@ async def _handle_resumption_request(self, ctx: RequestContext) -> None:
         if isinstance(ctx.session_message.message.root, JSONRPCRequest):  # pragma: no branch
             original_request_id = ctx.session_message.message.root.id
 
-        async with aconnect_sse(
-            ctx.client,
-            "GET",
-            self.url,
-            headers=headers,
-        ) as event_source:
+        async with sse_within_origin(ctx.client, self.url, headers=headers) as event_source:
+            _raise_for_unfollowed_redirect(event_source.response)
             event_source.response.raise_for_status()
             logger.debug("Resumption GET SSE connection established")
 
@@ -337,7 +358,8 @@ async def _handle_post_request(self, ctx: RequestContext) -> None:
         message = ctx.session_message.message
         is_initialization = self._is_initialization_request(message)
 
-        async with ctx.client.stream(
+        async with stream_within_origin(
+            ctx.client,
             "POST",
             self.url,
             json=message.model_dump(by_alias=True, mode="json", exclude_none=True),
@@ -355,6 +377,7 @@ async def _handle_post_request(self, ctx: RequestContext) -> None:
                     )  # pragma: no cover
                 return  # pragma: no cover
 
+            _raise_for_unfollowed_redirect(response)
             response.raise_for_status()
             if is_initialization:
                 self._maybe_extract_session_id_from_response(response)
@@ -460,12 +483,7 @@ async def _handle_reconnection(
             original_request_id = ctx.session_message.message.root.id
 
         try:
-            async with aconnect_sse(
-                ctx.client,
-                "GET",
-                self.url,
-                headers=headers,
-            ) as event_source:
+            async with sse_within_origin(ctx.client, self.url, headers=headers) as event_source:
                 event_source.response.raise_for_status()
                 logger.info("Reconnected to SSE stream")
 
@@ -583,7 +601,7 @@ async def terminate_session(self, client: httpx.AsyncClient) -> None:  # pragma:
 
         try:
             headers = self._prepare_headers()
-            response = await client.delete(self.url, headers=headers)
+            response = await request_within_origin(client, "DELETE", self.url, headers=headers)
 
             if response.status_code == 405:
                 logger.debug("Server does not allow session termination")
@@ -619,6 +637,13 @@ async def streamable_http_client(
         http_client: Optional pre-configured httpx.AsyncClient. If None, a default
             client with recommended MCP timeouts will be created. To configure headers,
             authentication, or other HTTP settings, create an httpx.AsyncClient and pass it here.
+            Whichever client is used, MCP requests follow a redirect only when it stays on the
+            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 for a POST; any status for the GET
+            stream); any other redirect is not followed and, like any non-2xx response, raises
+            `httpx.HTTPStatusError`, here naming the location. The 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.