Repository navigation
Expose create_mcp_http_client and McpHttpClientFactory as public API (2.0 made them private-only) #3238
Description
Summary
Customizing the HTTP client for streamable_http_client (custom headers, auth, timeout, proxy, etc.) is a common and legitimate need, but as of 2.0.0 the only supported way to build a conforming client is through helpers that live in the private module mcp.shared._httpx_utils. Users are therefore forced to depend on a private API.
What changed in 2.0
In 1.x, streamable_http_client accepted convenience kwargs directly:
streamable_http_client(url, headers=..., timeout=..., sse_read_timeout=..., auth=...)2.0 (via #2972, which replaced httpx/httpx-sse with httpx2) removed those kwargs. The signature is now:
async def streamable_http_client(
url: str,
*,
http_client: httpx2.AsyncClient | None = None,
terminate_on_close: bool = True,
) -> ...So the only way to pass custom headers/auth/timeout is to build an httpx2.AsyncClient yourself and pass it as http_client=. The standardized factory for doing so is create_mcp_http_client — but it is only available at the private path:
from mcp.shared._httpx_utils import create_mcp_http_client # private moduleThe same applies to McpHttpClientFactory: in 1.x it was importable from the public mcp.client.streamable_http, but in 2.0 it is defined in mcp.shared._httpx_utils and is no longer re-exported from any public module.
Why this is a problem
- "Connect to an MCP server that requires auth headers / a custom timeout / a proxy" is a standard use case, not an edge case.
- The leading underscore on
mcp.shared._httpx_utilssignals "private, may change without notice", so every downstream project that needs a custom client has to take on that fragility. - It's inconsistent: the consumption side (
streamable_http_client(url, http_client=...)) is public, but the construction side (create_mcp_http_client,McpHttpClientFactory) is private.
Suggestion
Re-export create_mcp_http_client and McpHttpClientFactory from a public module — e.g. mcp.client.streamable_http (where McpHttpClientFactory used to live) or mcp.shared — so building a custom HTTP client does not require importing a private module.
(Related: because the HTTP layer now uses httpx2, a short note in the migration docs on how to build/pass a custom http_client would also help.)
Activity
Avoid restricting the star-import surface; re-export via aliases
Ecocitizenz commentedon Aug 4, 2026
ProgrammerPlus1998 commentedon Aug 5, 2026
Thanks Adam — I really appreciate you endorsing this fix and laying out the reasoning so clearly. The asymmetry you describe — a public injection point paired with a private construction mechanism — is exactly what this change addresses: it re-exports
create_mcp_http_client,McpHttpClientFactory(and the two timeout constants) into the public, client-facingmcp.client.streamable_httpnamespace, and documents the recommended pattern in the migration guide. It's great to hear the security-consistency and auditability benefits resonate — they're a big part of why exposing the canonical construction mechanism felt worthwhile.Ecocitizenz commentedon Aug 5, 2026
ProgrammerPlus1998 commentedon Aug 18, 2026
I've already prepared an implementation for this (see the linked PR). Happy to be assigned whenever a maintainer has a chance to review — the PR will reopen automatically once assigned.
maxisbey commentedon Oct 2, 2026
Closed by #3618 (merged to
main), with docs rather than the export you asked for.All
create_mcp_http_clientadds to a plainhttpx2.AsyncClientistimeout=httpx2.Timeout(30.0, read=300.0). So instead of making it andMcpHttpClientFactorypublic, the Transports docs page now says to keep that timeout on a client you build yourself, and our own examples that had left it off now pass it.Thanks for the clear report and for #3239, which will stay closed since nothing is being exported.
AI Disclaimer