Scope HTTP client redirect following to the request's origin

create_mcp_http_client followed every redirect, so everything configured
on a client (headers, auth, request bodies) was re-sent to whatever host
a Location header named. Clients built by the factory now follow
redirects within the same origin (scheme, host, and port), plus
http-to-https upgrades of the same host on default ports, and raise the
new RedirectError for anything else - before the next request is sent.

- transports resolve a refused redirect in-band: requests get a JSON-RPC
  error naming the target and the remedy, notifications are delivered to
  the session's message handler; the standalone GET stream stops
  retrying an endpoint that keeps redirecting
- caller-supplied clients that follow no redirects get the same clear
  error on POST, GET stream, and SSE connect instead of an opaque
  content-type error
- OAuth discovery, registration, token, refresh, and the
  identity-assertion token exchange fail loudly on redirect responses
  instead of silently trying the next URL or abandoning the discovery
  chain
- RedirectError and create_mcp_http_client are exported from the
  top-level mcp package; migration.md documents the behavior change;
  docs and examples configure clients through the factory, and the
  general-purpose fetch example uses a browser-like client of its own

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 `httpx.AsyncClient` configured the way MCP needs: `follow_redirects=True`, a 30-second timeout for connect/write/pool, and a 300-second read timeout because the server may hold a response stream open.
+That is the whole production client. `Client` wraps the URL in `streamable_http_client(...)` for you, on top of an `httpx.AsyncClient` configured the way MCP needs: same-origin redirect handling, a 30-second timeout for connect/write/pool, and a 300-second read timeout because the server may hold a response stream open.
 
 !!! check
     A `Client` you have constructed is **not** connected. Construction only picks the transport;

docs/migration.md

@@ -1595,14 +1595,15 @@ async with streamablehttp_client(
 
 ```python
 import httpx
+from mcp import create_mcp_http_client
 from mcp.client.streamable_http import streamable_http_client
 
-# Configure headers, timeout, and auth on the httpx.AsyncClient
-http_client = httpx.AsyncClient(
+# Configure headers, timeout, and auth on the client. create_mcp_http_client
+# applies the SDK defaults (timeouts, same-origin redirect handling).
+http_client = create_mcp_http_client(
     headers={"Authorization": "Bearer token"},
     timeout=httpx.Timeout(30, read=300),
     auth=my_auth,
-    follow_redirects=True,
 )
 
 async with http_client:
@@ -1613,7 +1614,26 @@ async with http_client:
         ...
 ```
 
-v1's internal client set `follow_redirects=True`; set it explicitly when supplying your own `httpx.AsyncClient` to preserve that behavior.
+Prefer `create_mcp_http_client` when supplying your own client: a plain `httpx.AsyncClient` does not follow redirects at all, and configuring `follow_redirects=True` yourself sends everything on the client (headers, auth, bodies) to whichever server a redirect names.
+
+### HTTP clients only follow same-origin redirects
+
+Clients created by the SDK (including `Client("http://...")`, `sse_client`, and the
+default client inside `streamable_http_client`) now vet redirect targets before
+following. Redirects that stay on the same origin (scheme, host, and port) and
+http-to-https upgrades of the same host still work; any other redirect raises
+`mcp.RedirectError` naming the target instead of being followed. Everything
+configured on a client - headers, auth, request bodies - is sent to whichever
+server it talks to, so requests now stay with the server you configured, and a
+misconfigured URL fails with a clear error instead of silently bouncing.
+
+To migrate: connect to the final URL the error names. If your deployment
+genuinely requires following a redirect to a different origin, supply your own
+`httpx.AsyncClient(follow_redirects=True)` - after verifying you trust every
+destination in the chain.
+
+`create_mcp_http_client` (the SDK's client factory) and `RedirectError` are now
+exported from the top-level `mcp` package.
 
 ### `get_session_id` callback removed from `streamable_http_client`
 
@@ -1638,6 +1658,7 @@ async with streamable_http_client(url) as (read_stream, write_stream, get_sessio
 
 ```python
 import httpx
+from mcp import create_mcp_http_client
 from mcp.client.streamable_http import streamable_http_client
 
 # Option 1: Simply ignore if you don't need the session ID
@@ -1653,10 +1674,8 @@ async def capture_session_id(response: httpx.Response) -> None:
     if session_id:
         captured_session_ids.append(session_id)
 
-http_client = httpx.AsyncClient(
-    event_hooks={"response": [capture_session_id]},
-    follow_redirects=True,
-)
+http_client = create_mcp_http_client()
+http_client.event_hooks["response"].append(capture_session_id)
 
 async with http_client:
     async with streamable_http_client(url, http_client=http_client) as (read_stream, write_stream):

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`. (The trailing slash is the canonical path for this mount shape; the bare `/notes` answers with a same-origin redirect to it.)
 
 ## CORS for browser clients
 

docs_src/client_transports/tutorial003.py

@@ -1,14 +1,13 @@
 import httpx
 
-from mcp import Client
+from mcp import Client, create_mcp_http_client
 from mcp.client.streamable_http import streamable_http_client
 
 
 async def main() -> None:
-    async with httpx.AsyncClient(
+    async with create_mcp_http_client(
         headers={"Authorization": "Bearer ..."},
         timeout=httpx.Timeout(30.0, read=300.0),
-        follow_redirects=True,
     ) as http_client:
         transport = streamable_http_client("http://localhost:8000/mcp", http_client=http_client)
         async with Client(transport) as client:

docs_src/identity_assertion/tutorial001.py

@@ -1,10 +1,9 @@
 import time
 import uuid
 
-import httpx
 import jwt
 
-from mcp import Client
+from mcp import Client, create_mcp_http_client
 from mcp.client.auth.extensions.identity_assertion import IdentityAssertionOAuthProvider
 from mcp.client.streamable_http import streamable_http_client
 from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
@@ -62,7 +61,7 @@ async def fetch_id_jag(audience: str, resource: str) -> str:
 
 
 async def main() -> None:
-    async with httpx.AsyncClient(auth=oauth, follow_redirects=True) as http_client:
+    async with create_mcp_http_client(auth=oauth) as http_client:
         transport = streamable_http_client("http://localhost:8001/mcp", http_client=http_client)
         async with Client(transport) as client:
             result = await client.list_tools()

docs_src/oauth_clients/tutorial001.py

@@ -1,9 +1,8 @@
 from urllib.parse import parse_qs, urlparse
 
-import httpx
 from pydantic import AnyUrl
 
-from mcp import Client
+from mcp import Client, create_mcp_http_client
 from mcp.client.auth import AuthorizationCodeResult, OAuthClientProvider
 from mcp.client.streamable_http import streamable_http_client
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
@@ -55,7 +54,7 @@ async def wait_for_callback() -> AuthorizationCodeResult:
 
 
 async def main() -> None:
-    async with httpx.AsyncClient(auth=oauth, follow_redirects=True) as http_client:
+    async with create_mcp_http_client(auth=oauth) as http_client:
         transport = streamable_http_client("http://localhost:8001/mcp", http_client=http_client)
         async with Client(transport) as client:
             result = await client.list_tools()

docs_src/oauth_clients/tutorial002.py

@@ -1,6 +1,4 @@
-import httpx
-
-from mcp import Client
+from mcp import Client, create_mcp_http_client
 from mcp.client.auth.extensions.client_credentials import ClientCredentialsOAuthProvider
 from mcp.client.streamable_http import streamable_http_client
 from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
@@ -34,7 +32,7 @@ async def set_client_info(self, client_info: OAuthClientInformationFull) -> None
 
 
 async def main() -> None:
-    async with httpx.AsyncClient(auth=oauth, follow_redirects=True) as http_client:
+    async with create_mcp_http_client(auth=oauth) as http_client:
         transport = streamable_http_client("http://localhost:8001/mcp", http_client=http_client)
         async with Client(transport) as client:
             result = await client.list_tools()

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

@@ -17,7 +17,7 @@
 from typing import Any
 from urllib.parse import parse_qs, urlparse
 
-import httpx
+from mcp import create_mcp_http_client
 from mcp.client._transport import ReadStream, WriteStream
 from mcp.client.auth import AuthorizationCodeResult, OAuthClientProvider, TokenStorage
 from mcp.client.session import ClientSession
@@ -233,7 +233,7 @@ async def _default_redirect_handler(authorization_url: str) -> None:
                     await self._run_session(read_stream, write_stream)
             else:
                 print("📡 Opening StreamableHTTP transport connection with auth...")
-                async with httpx.AsyncClient(auth=oauth_auth, follow_redirects=True) as custom_client:
+                async with create_mcp_http_client(auth=oauth_auth) as custom_client:
                     async with streamable_http_client(url=self.server_url, http_client=custom_client) as (
                         read_stream,
                         write_stream,

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

@@ -1,15 +1,18 @@
 import anyio
 import click
+import httpx
 import mcp_types as types
 from mcp.server import Server, ServerRequestContext
-from mcp.shared._httpx_utils import create_mcp_http_client
 
 
 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:
+    # A general-purpose web fetch wants ordinary browser-like redirect
+    # behavior; create_mcp_http_client is for talking to a configured MCP
+    # endpoint and only follows same-origin redirects.
+    async with httpx.AsyncClient(headers=headers, follow_redirects=True, timeout=30.0) as client:
         response = await client.get(url)
         response.raise_for_status()
         return [types.TextContent(type="text", text=response.text)]

examples/snippets/clients/identity_assertion_client.py

@@ -16,9 +16,7 @@
 
 import asyncio
 
-import httpx
-
-from mcp import ClientSession
+from mcp import ClientSession, create_mcp_http_client
 from mcp.client.auth.extensions.identity_assertion import IdentityAssertionOAuthProvider
 from mcp.client.streamable_http import streamable_http_client
 from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
@@ -66,7 +64,7 @@ async def main() -> None:
         scope="user",
     )
 
-    async with httpx.AsyncClient(auth=oauth_auth, follow_redirects=True) as http_client:
+    async with create_mcp_http_client(auth=oauth_auth) as http_client:
         async with streamable_http_client("http://localhost:8001/mcp", http_client=http_client) as (read, write):
             async with ClientSession(read, write) as session:
                 await session.initialize()