Only follow method-preserving redirects; resolve unfollowed ones on every path

Review follow-ups for the origin-scoped redirect handling:

- A same-origin 301/302/303 answering a POST is no longer followed: httpx2's
  next-request rules turn those into a body-less GET, which would drop the
  JSON-RPC message. Only redirects that keep the method (307/308, or any
  status for a GET) are followed; the rest come back unfollowed like an
  off-origin redirect and the call fails naming the location.
- The standalone GET stream and the resumption GET now handle an unfollowed
  redirect the way the message POST does: the GET stream logs it and stops
  instead of spending its reconnection attempts on the same answer, and a
  resumed request is resolved with the error instead of being left waiting.
  One helper builds the message for all three.
- OAuth authorization-server metadata discovery treats a 3xx from a
  well-known candidate like a 4xx and tries the next candidate, matching the
  protected-resource metadata handler, now that these requests see redirect
  responses directly.
- The simple-tool example keeps the 30s/300s timeouts it had before it
  stopped using the MCP client factory.

Author: maxisbey

docs/client/transports.md

@@ -29,7 +29,7 @@ Pass a URL string and you get **Streamable HTTP**, the transport you deploy behi
 --8<-- "docs_src/client_transports/tutorial002.py"
 ```
 
-That is the whole production client. `Client` wraps the URL in `streamable_http_client(...)` for you, on top of an `httpx2.AsyncClient` configured the way MCP needs: a 30-second timeout for connect/write/pool, and a 300-second read timeout because the server may hold a response stream open. Whichever client is underneath, the transport follows 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 the default ports), which covers a trailing-slash redirect. A redirect anywhere else is not followed, and the call it answered fails with an `MCPError` naming the location; if that address is the server you meant, use it as the URL.
+That is the whole production client. `Client` wraps the URL in `streamable_http_client(...)` for you, on top of an `httpx2.AsyncClient` configured the way MCP needs: a 30-second timeout for connect/write/pool, and a 300-second read timeout because the server may hold a response stream open. Whichever client is underneath, the transport follows 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 the default ports) and keeps the request method, which covers a 307/308 trailing-slash redirect. Any other redirect is not followed, and the call it answered fails with an `MCPError` naming the location; if that address is the server you meant, use it as the URL.
 
 !!! check
     A `Client` you have constructed is **not** connected. Construction only picks the transport;

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

@@ -9,7 +9,8 @@ async def fetch_website(
     url: str,
 ) -> list[types.ContentBlock]:
     headers = {"User-Agent": "MCP Test Server (github.com/modelcontextprotocol/python-sdk)"}
-    async with httpx2.AsyncClient(headers=headers, follow_redirects=True) as client:
+    timeout = httpx2.Timeout(30, read=300)
+    async with httpx2.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)]

src/mcp/client/auth/utils.py

@@ -230,9 +230,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_authorization_response_iss(iss: str | None, oauth_metadata: OAuthMetadata | None) -> None:

src/mcp/client/sse.py

@@ -53,11 +53,12 @@ async def sse_client(
         timeout: HTTP timeout for regular operations (in seconds).
         sse_read_timeout: Timeout for SSE read operations (in seconds).
         httpx_client_factory: Factory function for creating the httpx2 client. Whichever client it
-            returns, MCP requests follow a redirect only within the endpoint's origin (same scheme,
-            host and port, or http to https on the same host with default ports); a redirect
-            anywhere else 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.
+            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 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.
         auth: Optional httpx2 authentication handler.
         on_session_created: Optional callback invoked with the session ID when received.
     """

src/mcp/client/streamable_http.py

@@ -67,6 +67,14 @@ class ResumptionError(StreamableHTTPError):
     """Raised when resumption request is invalid."""
 
 
+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
+    return f"Redirect to {location} not followed; use that URL as the endpoint if it is the intended server"
+
+
 @dataclass
 class RequestContext:
     """Context for a request operation."""
@@ -216,6 +224,10 @@ async def handle_get_stream(self, client: httpx2.AsyncClient, read_stream_writer
                     headers[LAST_EVENT_ID] = last_event_id
 
                 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")
 
@@ -259,6 +271,13 @@ async def _handle_resumption_request(self, ctx: RequestContext) -> None:
             original_request_id = ctx.session_message.message.id
 
         async with sse_within_origin(ctx.client, self.url, headers=headers) as event_source:
+            if (redirect := _unfollowed_redirect(event_source.response)) is not None:
+                logger.warning(redirect)
+                assert original_request_id is not None
+                await self._resolve_abandoned_request(
+                    ctx.read_stream_writer, original_request_id, redirect, code=INVALID_REQUEST
+                )
+                return
             event_source.response.raise_for_status()
             logger.debug("Resumption GET SSE connection established")
 
@@ -345,18 +364,11 @@ async def _handle_post_request(self, ctx: RequestContext) -> None:
                     )
                 return
 
-            if response.next_request is not None:
-                # Left unfollowed by stream_within_origin: the location is outside the endpoint's origin.
-                location = response.next_request.url
-                logger.warning(
-                    f"Server redirected {self.url} to {location}, outside the endpoint's origin; not followed"
-                )
+            if (redirect := _unfollowed_redirect(response)) is not None:
+                logger.warning(redirect)
                 if isinstance(message, JSONRPCRequest):
                     await self._resolve_abandoned_request(
-                        ctx.read_stream_writer,
-                        message.id,
-                        f"Redirect to {location} not followed: it is outside the endpoint's origin",
-                        code=INVALID_REQUEST,
+                        ctx.read_stream_writer, message.id, redirect, code=INVALID_REQUEST
                     )
                 return
 
@@ -671,11 +683,12 @@ async def streamable_http_client(
         http_client: Optional pre-configured httpx2.AsyncClient. If None, a default
             client with recommended MCP timeouts will be created. To configure headers,
             authentication, or other HTTP settings, create an httpx2.AsyncClient and pass it here.
-            Whichever client is used, MCP requests follow a redirect only within the endpoint's
-            origin (same scheme, host and port, or http to https on the same host with default
-            ports); a redirect anywhere else 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.
+            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); 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.
         terminate_on_close: If True, send a DELETE request to terminate the session when the context exits.
 
     Yields:

src/mcp/shared/_httpx_utils.py

@@ -87,13 +87,16 @@ async def stream_within_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), such as a trailing-slash
-    normalisation, is followed using httpx2's own next-request rules. A redirect
-    anywhere else 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, and requests an `httpx2.Auth` flow makes during
-    the call are sent the same way, so they do not follow redirects either.
+    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.
@@ -103,7 +106,11 @@ async def stream_within_origin(
         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 not _within_origin(response.request.url, next_request.url):
+        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:

tests/client/test_auth.py

@@ -24,6 +24,7 @@
     extract_resource_metadata_from_www_auth,
     extract_scope_from_www_auth,
     get_client_metadata_scopes,
+    handle_auth_metadata_response,
     handle_registration_response,
     is_valid_client_metadata_url,
     should_use_client_metadata_url,
@@ -824,6 +825,17 @@ async def test_resource_param_included_with_protected_resource_metadata(self, oa
         assert "resource=" in content
 
 
+@pytest.mark.anyio
+@pytest.mark.parametrize(("status", "keep_trying"), [(404, True), (307, True), (500, False)])
+async def test_auth_metadata_response_says_whether_to_try_the_next_discovery_url(
+    status: int, keep_trying: bool
+) -> None:
+    """SDK-defined: a 4xx or a 3xx (redirects are not followed on these requests) from a discovery
+    candidate means the metadata is not served there and the next well-known URL is tried; a 5xx
+    stops discovery."""
+    assert await handle_auth_metadata_response(httpx2.Response(status)) == (keep_trying, None)
+
+
 @pytest.mark.parametrize(
     ("protocol_version", "expected"),
     [

tests/client/test_streamable_http.py

@@ -831,7 +831,7 @@ async def record(request: httpx2.Request) -> None:
 
     assert exc_info.value.error.code == INVALID_REQUEST
     assert exc_info.value.error.message == snapshot(
-        "Redirect to http://other.example/mcp/ not followed: it is outside the endpoint's origin"
+        "Redirect to http://other.example/mcp/ not followed; use that URL as the endpoint if it is the intended server"
     )
     assert [url for url in urls if "other.example" in url] == []
 
@@ -861,3 +861,57 @@ def handler(request: httpx2.Request) -> httpx2.Response:
     assert reply.message.id == 7
     assert reply.message.error.code == INVALID_REQUEST
     assert urls == ["http://test/mcp", "http://test/mcp"]
+
+
+@pytest.mark.anyio
+async def test_get_stream_gives_up_without_retrying_when_the_endpoint_redirects_elsewhere() -> None:
+    """SDK-defined: the standalone GET stream is not opened through a redirect to another origin,
+    and since the same GET would be redirected again the transport logs it and stops instead of
+    spending its reconnection attempts."""
+    gets: list[str] = []
+
+    def handler(request: httpx2.Request) -> httpx2.Response:
+        gets.append(str(request.url))
+        return httpx2.Response(307, headers={"location": "http://other.example/mcp"})
+
+    transport = StreamableHTTPTransport("http://test/mcp")
+    transport.session_id = "session-1"
+    send, receive = create_context_streams[SessionMessage | Exception](1)
+    with anyio.fail_after(5):
+        async with httpx2.AsyncClient(transport=httpx2.MockTransport(handler)) as http:
+            await transport.handle_get_stream(http, send)
+    assert gets == ["http://test/mcp"]
+    send.close()
+    receive.close()
+
+
+@pytest.mark.anyio
+async def test_resumption_redirected_elsewhere_resolves_that_request_with_an_error() -> None:
+    """SDK-defined: a resumption GET answered with a redirect to another origin is not followed;
+    the resumed request is resolved with an error naming the location rather than left waiting."""
+    seen: list[tuple[str, str | None]] = []
+
+    def handler(request: httpx2.Request) -> httpx2.Response:
+        seen.append((f"{request.method} {request.url}", request.headers.get("last-event-id")))
+        return httpx2.Response(307, headers={"location": "http://other.example/mcp"})
+
+    with anyio.fail_after(5):
+        async with (
+            httpx2.AsyncClient(transport=httpx2.MockTransport(handler)) as http,
+            streamable_http_client("http://test/mcp", http_client=http) as (read, write),
+        ):
+            await write.send(
+                SessionMessage(
+                    JSONRPCRequest(jsonrpc="2.0", id="resume-1", method="tools/call", params={}),
+                    metadata=ClientMessageMetadata(resumption_token="evt-41"),
+                )
+            )
+            reply = await read.receive()
+    assert isinstance(reply, SessionMessage)
+    assert isinstance(reply.message, JSONRPCError)
+    assert reply.message.id == "resume-1"
+    assert reply.message.error.code == INVALID_REQUEST
+    assert reply.message.error.message == snapshot(
+        "Redirect to http://other.example/mcp not followed; use that URL as the endpoint if it is the intended server"
+    )
+    assert seen == [("GET http://test/mcp", "evt-41")]

tests/shared/test_httpx_utils.py

@@ -118,8 +118,36 @@ async def test_redirect_outside_origin_is_not_followed(location: str):
     assert closed == [True]
 
 
+@pytest.mark.parametrize("status", [301, 302, 303])
+async def test_method_changing_redirect_of_a_post_is_not_followed(status: int):
+    """httpx2 turns a POST into a body-less GET for 301/302/303, which would drop the message, so a
+    same-origin redirect with one of those codes is handed back unfollowed (SDK-defined)."""
+    url = "http://mcp.example/mcp"
+    client, received, _ = _recording_client({url: (status, "/mcp/")})
+
+    async with client, stream_within_origin(client, "POST", url, content=b"payload") as response:
+        pass
+
+    assert response.status_code == status
+    assert received == [f"POST {url}"]
+
+
+@pytest.mark.parametrize("status", [301, 302, 303, 307, 308])
+async def test_same_origin_redirect_of_a_get_is_followed_for_every_redirect_status(status: int):
+    """A GET keeps its method under every redirect status, so the SSE GET follows all of them
+    within the origin (SDK-defined policy over httpx2's method rules)."""
+    url = "http://mcp.example/sse"
+    client, received, _ = _recording_client({url: (status, "/sse/")})
+
+    async with client, stream_within_origin(client, "GET", url) as response:
+        await response.aread()
+
+    assert response.status_code == 200
+    assert received == [f"GET {url}", "GET http://mcp.example/sse/"]
+
+
 async def test_https_to_http_on_same_host_is_outside_origin():
-    """Only the upgrade direction counts as staying on the origin; a downgrade is refused."""
+    """Only the upgrade direction counts as staying on the origin; a downgrade is not followed."""
     url = "https://mcp.example/mcp"
     client, received, _ = _recording_client({url: (302, "http://mcp.example/mcp")})