fix: add SSRF redirect protection to httpx client factory
What changed
Adds a RedirectPolicy enum and redirect validation event hook to create_mcp_http_client() in src/mcp/shared/_httpx_utils.py to protect against SSRF attacks via HTTP redirects.
Changes:
-
src/mcp/shared/_httpx_utils.py:- Added
RedirectPolicyenum with three presets:BLOCK_SCHEME_DOWNGRADE(default) — blocks HTTPS→HTTP redirect downgradesENFORCE_HTTPS— only allows HTTPS redirect destinationsALLOW_ALL— no restrictions (legacy behavior)
- Added
_check_redirect()async response event hook that validates redirect targets against the configured policy usingresponse.has_redirect_locationand theLocationheader - Added
redirect_policyparameter tocreate_mcp_http_client()(default:BLOCK_SCHEME_DOWNGRADE) McpHttpClientFactoryProtocol left unchanged —redirect_policyis an internal concern ofcreate_mcp_http_client, not part of the caller-side contract
- Added
-
src/mcp/client/streamable_http.py:- Added docstring note on
http_clientparameter clarifying that user-provided clients do not receive SSRF redirect protection - Added
logger.debugwhen a user-provided client is used
- Added docstring note on
-
tests/shared/test_httpx_utils.py:- 14 unit tests covering all three policies, edge cases (non-redirect responses, missing
Locationheader), and all scheme combinations - 2 integration tests using
httpx.MockTransportthat exercise the event hook wiring end-to-end through the real httpx client
- 14 unit tests covering all three policies, edge cases (non-redirect responses, missing
Why
A malicious MCP server can respond with a 3xx redirect pointing to internal network addresses (http://169.254.169.254, http://localhost, etc.), enabling SSRF attacks. The SDK previously set follow_redirects=True with zero redirect validation. The default BLOCK_SCHEME_DOWNGRADE policy prevents the most common SSRF vector (HTTPS→HTTP downgrade to reach internal services) while remaining backward-compatible for legitimate use cases.
Bug discovered during review
The initial implementation used response.next_request to inspect redirect targets, but httpx never populates next_request when follow_redirects=True — causing the protection to silently bypass all checks. Fixed to use response.has_redirect_location + parse the Location header directly, matching httpx's own _build_redirect_request flow.
How verified
ruff check .— all checks passedruff format --check .— no formatting issuespyright— 0 errors, 0 warningspytest tests/shared/test_httpx_utils.py -v— 16 passedpytest tests/client/test_client.py -v— 19 passed (no regressions)
Tradeoffs / risks
- The new
redirect_policyparameter oncreate_mcp_http_clienthas a default value, so all existing callers are unaffected — no breaking change McpHttpClientFactoryProtocol is not modified, preserving compatibility for downstream code implementing custom factories- Users who need the legacy behavior can pass
redirect_policy=RedirectPolicy.ALLOW_ALL - Private/link-local IP range blocking is not included in this PR — suggested as a follow-up
Scope notes
RedirectPolicyis not re-exported frommcp.__init__—create_mcp_http_clientitself is also not publicly exported, so both share the same visibility viamcp.shared._httpx_utils. Public API surface expansion is suggested as a follow-upHttpResourceinresources/types.pyuses a barehttpx.AsyncClient()(separate concern, not addressed here)
Closes #2106