Add `streamable_http_client` which accepts `httpx.AsyncClient` instead of `httpx_client_factory` #1177

Kludex · 2025-07-21T08:43:12Z

The current name is not very intuitive considering the class name and the module.

Closes httpx.ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain (_ssl.c:1002) #1370
Closes SSLV3_ALERT_HANDSHAKE_FAILURE when using private gateway #1470

ihrpr

The deprecated wrapper is missing the httpx_client_factory and auth parameters. This could break existing code using those parameters.

(it's probably a good time to replace httpx_client_factory with an object)

Kludex · 2025-07-21T10:08:12Z

I blame copilot. 😄

Kludex · 2025-07-21T10:18:53Z

(it's probably a good time to replace httpx_client_factory with an object)

I think the timeouts, the auth and the httpx_client_factory CAN be replaced. The timeouts I think can be subjective, but the auth and the httpx_client_factory I think need to be replaced.

ihrpr · 2025-07-21T12:18:46Z

(it's probably a good time to replace httpx_client_factory with an object)

I think the timeouts, the auth and the httpx_client_factory CAN be replaced. The timeouts I think can be subjective, but the auth and the httpx_client_factory I think need to be replaced.

should we just replace it now, since we are deprecating one method, would be good to have a nice alternative and not to deprecate it twice?

Kludex · 2025-07-21T12:25:11Z

(it's probably a good time to replace httpx_client_factory with an object)

I think the timeouts, the auth and the httpx_client_factory CAN be replaced. The timeouts I think can be subjective, but the auth and the httpx_client_factory I think need to be replaced.

should we just replace it now, since we are deprecating one method, would be good to have a nice alternative and not to deprecate it twice?

I didn't get what you said. I agree that it's a good moment to change the parameters of the new streamable_http_client.

dsp-ant · 2025-09-02T12:40:10Z

Should we do this and deprecate the old module?

felixweinberger · 2025-09-22T21:04:18Z

FYI for viewers: on my todo list to update this

outdated - pushed updated version making httpx_client a param instead of factory

felixweinberger · 2025-10-01T18:37:13Z

src/mcp/client/streamable_http.py

        self.session_id = None
        self.protocol_version = None
        self.request_headers = {
+            **self.headers,


Previously we would have streamablehttp_client create the httpx.AsyncClient via a factory after initializing the transport. That means we could use these transport.request_headers when creating the httpx.AsyncClient to ensure the client and the transport have the same headers.

If we now accept httpx_client as an argument to streamable_http_client, that client might have custom headers! In fact by default httpx.AsyncClient creates headers here that need to be overriden (hence moving the ACCEPT and CONTENT_TYPE after), for example accept: */*

Therefore the transport needs to override these headers now if they're present to be configured correctly.

src/mcp/client/streamable_http.py

felixweinberger · 2025-10-01T19:05:47Z

@Kludex @ihrpr @dsp-ant gave this a shot, trying to replace the factory with a client object.

Results in some ugly header mangling that I don't see how to avoid given the existing structure. Keen for thoughts.

felixweinberger · 2025-10-01T19:15:43Z

src/mcp/shared/_httpx_utils.py

    # Handle timeout
    if timeout is None:
-        kwargs["timeout"] = httpx.Timeout(30.0)
+        kwargs["timeout"] = httpx.Timeout(MCP_DEFAULT_TIMEOUT, read=MCP_DEFAULT_SSE_READ_TIMEOUT)


Previously we'd rely on the transport setting this to 60 * 5 when creating our client, but we can't rely on that anymore as the client may now be created before the transport.

Modernize streamable_http_client API by accepting httpx.AsyncClient instances directly instead of factory functions, following industry standards. - New API: httpx_client: httpx.AsyncClient | None parameter - Default client created with recommended timeouts if None - Deprecated wrapper provides backward compatibility - Updated examples to show custom client usage - Add MCP_DEFAULT_TIMEOUT constants to _httpx_utils

This commit fixes all test failures introduced by the API change from httpx_client_factory to direct httpx_client parameter: 1. Updated deprecated imports: Changed streamablehttp_client to streamable_http_client in test files 2. Fixed 307 redirect errors: Replaced httpx.AsyncClient with create_mcp_http_client which includes follow_redirects=True by default 3. Fixed test assertion: Updated test_session_group.py to mock create_mcp_http_client and verify the new API signature where streamable_http_client receives httpx_client parameter instead of individual headers/timeout parameters 4. Removed unused httpx import from main.py after inlining client creation All tests now pass with the new API.

Added missing type annotation imports that were causing NameError and preventing test collection: - RequestResponder from mcp.shared.session - SessionMessage from mcp.shared.message - GetSessionIdCallback from mcp.client.streamable_http - RequestContext from mcp.shared.context This fixes 4 NameError collection failures and 10 F821 ruff errors, allowing all 20 tests in the file to be properly collected and executed.

Restore type annotations on test function parameters in test_streamable_http.py that were accidentally removed during the function renaming from streamablehttp_client to streamable_http_client. Added type annotations to: - Fixture parameters: basic_server, basic_server_url, json_response_server, json_server_url, event_server, monkeypatch - Test function parameters: initialized_client_session This fixes all 61 pyright errors and ensures type safety matches the main branch standards.

Remove complex mocking of create_mcp_http_client in the streamablehttp test case. Instead, let the real create_mcp_http_client execute and only verify that streamable_http_client receives the correct parameters including a real httpx.AsyncClient instance. This simplifies the test by: - Removing 13 lines of mock setup code - Removing 14 lines of mock verification code - Removing 3 lines of mock cleanup code - Trusting that create_mcp_http_client works (it has its own tests) The test now focuses on verifying the integration between session_group and streamable_http_client rather than re-testing create_mcp_http_client.

This commit addresses two API design concerns: 1. Remove private module usage in examples: Examples no longer import from the private mcp.shared._httpx_utils module. Instead, they create httpx clients directly using the public httpx library. 2. Rename httpx_client parameter to http_client: The 'httpx_client' parameter name was redundant since the type annotation already specifies it's an httpx.AsyncClient. Renaming to 'http_client' provides a cleaner, more concise API. Changes: - Updated oauth_client.py and simple-auth-client examples to use public APIs - Renamed httpx_client to http_client in function signatures - Updated all internal callers and tests - Updated deprecated streamablehttp_client wrapper function

Remove client.headers.update() call that was unnecessarily mutating user-provided httpx.AsyncClient instances. The mutation was defensive but unnecessary since: 1. All transport methods pass headers explicitly to httpx requests 2. httpx merges request headers with client defaults, with request headers taking precedence 3. HTTP requests are identical with or without the mutation 4. Not mutating respects user's client object integrity Add comprehensive test coverage for header behavior: - Verify client headers are not mutated after use - Verify MCP protocol headers override httpx defaults in requests - Verify custom and MCP headers coexist correctly in requests All existing tests pass, confirming no behavior change to actual HTTP requests.

@deprecated

…ner header handling This commit addresses three issues identified in PR review: 1. **Restore RequestContext fields for backwards compatibility** - Re-add `headers` and `sse_read_timeout` fields as optional with None defaults - Mark them as deprecated in docstring since they're no longer used internally - Prevents breaking changes for any code accessing these fields 2. **Add runtime deprecation warnings for StreamableHTTPTransport constructor** - Use sentinel value pattern to detect when deprecated parameters are passed - Issue DeprecationWarning at runtime when headers, timeout, sse_read_timeout, or auth are provided - Complements existing @deprecated decorator for type checkers with actual runtime warnings - Improve deprecation message clarity 3. **Simplify header handling by removing redundant client parameter** - Remove `client` parameter from `_prepare_headers()` method - Stop extracting and re-passing client.headers since httpx automatically merges them - Only build MCP-specific headers (Accept, Content-Type, session headers) - httpx merges these with client.headers automatically, with our headers taking precedence - Reduces code complexity and eliminates unnecessary header extraction The header handling change leverages httpx's built-in header merging behavior, similar to how headers were handled before the refactoring but without the redundant extraction-and-repass pattern.

Kludex · 2025-12-10T17:23:42Z

I didn't think this was going to be merged already. I've been thinking about this, and I'm unsure this is the cleanest approach.

I think this API is not going to last, I think the right approach is to create the MCPClient/Client that it will manage the lifecycle of the HTTP client there. Right now, most of the LLM providers are doing this thing of accepting the HTTP client, but I think what everybody should be doing is allowing to pass all the parameters (a bit contradictory to what was the motivation to this PR, since I'm saying the completely opposite).

I think the TestClient from Starlette is more or less how I see that happening (doesn't need to be with inheritance, it can be with composition).

maxisbey · 2025-12-10T17:48:52Z

I didn't think this was going to be merged already. I've been thinking about this, and I'm unsure this is the cleanest approach.

I think this API is not going to last, I think the right approach is to create the MCPClient/Client that it will manage the lifecycle of the HTTP client there. Right now, most of the LLM providers are doing this thing of accepting the HTTP client, but I think what everybody should be doing is allowing to pass all the parameters (a bit contradictory to what was the motivation to this PR, since I'm saying the completely opposite).

I think the TestClient from Starlette is more or less how I see that happening (doesn't need to be with inheritance, it can be with composition).

Hmm, could you make an issue for this for v2 with some thoughts? would be good to capture it when going through the refactoring

felixweinberger · 2025-12-11T11:35:24Z

I didn't think this was going to be merged already. I've been thinking about this, and I'm unsure this is the cleanest approach.
I think this API is not going to last, I think the right approach is to create the MCPClient/Client that it will manage the lifecycle of the HTTP client there. Right now, most of the LLM providers are doing this thing of accepting the HTTP client, but I think what everybody should be doing is allowing to pass all the parameters (a bit contradictory to what was the motivation to this PR, since I'm saying the completely opposite).
I think the TestClient from Starlette is more or less how I see that happening (doesn't need to be with inheritance, it can be with composition).

Hmm, could you make an issue for this for v2 with some thoughts? would be good to capture it when going through the refactoring

@maxisbey @Kludex made one here for discussion: #1773

Kludex requested review from a team, ihrpr and ochafik July 21, 2025 08:43

ihrpr previously requested changes Jul 21, 2025

View reviewed changes

felixweinberger self-assigned this Sep 22, 2025

felixweinberger added the needs maintainer action Potentially serious issue - needs proactive fix and maintainer attention label Sep 22, 2025

felixweinberger mentioned this pull request Sep 23, 2025

Replace httpx_client_factory with direct httpx_client parameter for better flexibility #1280

Closed

9 tasks

felixweinberger added the needs more work Not ready to be merged yet, needs additional follow-up from the author(s). label Sep 23, 2025

felixweinberger removed the needs more work Not ready to be merged yet, needs additional follow-up from the author(s). label Oct 1, 2025

felixweinberger force-pushed the rename-streamable-http branch from 222b13f to 74fa629 Compare October 1, 2025 18:18

felixweinberger requested review from ihrpr and removed request for ihrpr and ochafik October 1, 2025 18:24

felixweinberger reviewed Oct 1, 2025

View reviewed changes

src/mcp/client/streamable_http.py Outdated Show resolved Hide resolved

felixweinberger requested a review from ihrpr October 1, 2025 19:05

felixweinberger added needs more eyes and removed needs maintainer action Potentially serious issue - needs proactive fix and maintainer attention labels Oct 1, 2025

felixweinberger changed the title ~~Rename streamablehttp_client to streamable_http_client~~ Add streamable_http_client which accepts httpx.AsyncClient instead of httpx_client_factory Oct 1, 2025

felixweinberger force-pushed the rename-streamable-http branch from 7a6c89d to 43dec02 Compare October 1, 2025 19:14

felixweinberger reviewed Oct 1, 2025

View reviewed changes

maxisbey mentioned this pull request Nov 13, 2025

adding alias streamable_http_client for streamablehttp_client #1621

Closed

9 tasks

maxisbey force-pushed the rename-streamable-http branch from 24dfbc3 to 0d56c71 Compare November 13, 2025 13:58

Kludex mentioned this pull request Nov 25, 2025

MCP client using httpx.client is closed after one request pydantic/pydantic-ai#2502

Closed

2 tasks

felixweinberger force-pushed the rename-streamable-http branch from 0d56c71 to 32fa804 Compare December 1, 2025 19:31

felixweinberger requested review from maxisbey and removed request for ihrpr and maxisbey December 1, 2025 19:53

maxisbey mentioned this pull request Dec 2, 2025

SSLV3_ALERT_HANDSHAKE_FAILURE when using private gateway #1470

Closed

2 tasks

Kludex and others added 13 commits December 4, 2025 17:54

Rename streamablehttp_client to streamable_http_client

646a0d5

Apply pre-commit

433da3e

Add missing paramters

bcc4b19

Add overload for deprecation

862c22f

Add pragma comments for coverage on anyio 4.12.0

f897932

felixweinberger force-pushed the rename-streamable-http branch from 6500f51 to f897932 Compare December 4, 2025 18:04

maxisbey approved these changes Dec 10, 2025

View reviewed changes

maxisbey merged commit a3a4b8d into main Dec 10, 2025
21 checks passed

maxisbey deleted the rename-streamable-http branch December 10, 2025 16:39

jlowin mentioned this pull request Dec 10, 2025

Switch to streamable_http_client API from MCP SDK jlowin/fastmcp#2594

Open

felixweinberger mentioned this pull request Dec 11, 2025

V2: Redesign HTTP client lifecycle management with MCPClient/Client approach #1773

Open

Add streamable_http_client which accepts httpx.AsyncClient instead of httpx_client_factory #1177

Add streamable_http_client which accepts httpx.AsyncClient instead of httpx_client_factory #1177

Conversation

Kludex commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ihrpr left a comment

Choose a reason for hiding this comment

Uh oh!

Kludex commented Jul 21, 2025

Uh oh!

Kludex commented Jul 21, 2025 • edited by ihrpr Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ihrpr commented Jul 21, 2025

Uh oh!

Kludex commented Jul 21, 2025

Uh oh!

dsp-ant commented Sep 2, 2025

Uh oh!

felixweinberger commented Sep 22, 2025

Uh oh!

felixweinberger Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

felixweinberger commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felixweinberger Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Kludex commented Dec 10, 2025

Uh oh!

maxisbey commented Dec 10, 2025

Uh oh!

felixweinberger commented Dec 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Add `streamable_http_client` which accepts `httpx.AsyncClient` instead of `httpx_client_factory` #1177

Add `streamable_http_client` which accepts `httpx.AsyncClient` instead of `httpx_client_factory` #1177

Kludex commented Jul 21, 2025 •

edited

Loading

Kludex commented Jul 21, 2025 •

edited by ihrpr

Loading

felixweinberger Oct 1, 2025 •

edited

Loading

felixweinberger commented Oct 1, 2025 •

edited

Loading