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.

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.

src/mcp/shared/_httpx_utils.py

maxisbey · 2025-10-23T22:20:12Z

README.md

-    async with streamablehttp_client("http://localhost:8001/mcp", auth=oauth_auth) as (read, write, _):
-        async with ClientSession(read, write) as session:
-            await session.initialize()
+    async with httpx.AsyncClient(auth=oauth_auth, follow_redirects=True) as custom_client:


would it be worth adding a comment like # optionally create custom httpx.AsyncClient since by default this would work without creating the custom client here (I assume)

Actually in this case you do need the custom client because that's the way to add auth now

Ahh ok makes sense. Hmm, well then what if you also want the default timeouts we've set for MCP (re: #1177 (comment))

You'd have to set up the timeouts yourself if you're setting up the client yourself. To avoid surprising the user with unexpected behaviors, if they create their own custom client we should assume they want to control the pieces.

There's a valid point though about potentially making _httpx_utils public and thus allowing people to use create_mcp_http_client. Not sure if that's really very valuable though because it's a very thin wrapper 🤔

maxisbey · 2025-10-23T22:24:05Z

src/mcp/shared/_httpx_utils.py


 def create_mcp_http_client(
    headers: dict[str, str] | None = None,
    timeout: httpx.Timeout | None = None,


(non blocking question) why do we not set the timeout default here instead of doing the check inside the function?

Seems like a stylistic choice, I just went with the existing pattern but it's a fair point it could be done differently.

Kludex · 2025-10-24T08:02:33Z

src/mcp/client/streamable_http.py

+    timeout = client.timeout.connect if (client.timeout and client.timeout.connect is not None) else MCP_DEFAULT_TIMEOUT
+    sse_read_timeout = (
+        client.timeout.read if (client.timeout and client.timeout.read is not None) else MCP_DEFAULT_SSE_READ_TIMEOUT
+    )


If the client is provided, why do we need to do this? 🤔

Hm, the mechanical reason is because we changed the ordering in which things get created.

In the previous model we created the transport first with the settings (see line 473 before this change). Then we used the client factory to create the client with the same settings that we added to the transport.

In order for the two to match, we need to do the inverse now as the client can be created first. However, I see your point, there's some redundancy as the client is then used in the handlers...

I guess there's a question whether StreamableHTTPTransport still needs all these arguments in the first place if we're supporting explicit creation of the client object?

headers: dict[str, str] | None = None, timeout: float | timedelta = 30, sse_read_timeout: float | timedelta = 60 * 5, auth: httpx.Auth | None = None,

I guess the decision we need to make is whether the client passed in is the source of truth on all configuration matters (headers, timeout, auth) or not. And if not, which things does the transport definitively need to override.

In the current model, the factory creates a client with the settings passed to streamablehttp_client, which creates some duplication. Then in handle_get_stream / post_writer / _handle_post_request the transport seems to override headers, timeout, sse_read_timeout again, but not always. So there's some unclear division of responsibility between which settings the client owns and which ones the transport owns.

If we follow a principle of "least surprise", I think we shouldn't be overriding anything if a client is explicitly constructed by the user of this API and passed in. So ideally the API of StreamableHTTPTransport becomes just StreamableHTTPTransport(url) and that's it, no other settings on the transport. The client owns all the settings and the transport takes the client as given.

And in the case where a user doesn't pass in a client they configured themself, we configure a "sane" client that matches the current defaults, but we let the client fully own that configuration.

Does that make sense?

I added a commit on top of this to demonstrate what this could look like: 94df64b

Is that more the direction you were thinking @Kludex?

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.

…ation Implements "principle of least surprise" by making the httpx client the single source of truth for HTTP configuration (headers, timeout, auth). Changes: - StreamableHTTPTransport constructor now only takes url parameter - Transport reads configuration from client when making requests - Removed redundant config extraction and storage - Removed headers and sse_read_timeout from RequestContext - Removed MCP_DEFAULT_TIMEOUT and MCP_DEFAULT_SSE_READ_TIMEOUT from _httpx_utils public API (__all__) This addresses PR feedback about awkward config extraction when client is provided. The transport now only adds protocol requirements (MCP headers, session headers) on top of the client's configuration rather than extracting and overriding it. All tests pass, no type errors.

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 changes. label Sep 23, 2025

felixweinberger removed the needs more work Not ready to be merged yet, needs additional changes. 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 Needs alignment among maintainers whether this is something we want to add 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

felixweinberger force-pushed the rename-streamable-http branch from deac57e to a14eeb2 Compare October 23, 2025 21:32

felixweinberger marked this pull request as ready for review October 23, 2025 21:35

maxisbey reviewed Oct 23, 2025

View reviewed changes

Kludex commented Oct 24, 2025

View reviewed changes

OS-anasantos added a commit to OS-anasantos/python-sdk that referenced this pull request Oct 24, 2025

Adapt to PR modelcontextprotocol#1177

8714c53

felixweinberger requested review from ihrpr, maxisbey and ochafik and removed request for ihrpr and ochafik October 24, 2025 17:37

felixweinberger force-pushed the rename-streamable-http branch from e4e0d48 to 90af4b2 Compare October 24, 2025 17:40

Kludex and others added 10 commits October 24, 2025 10:46

Rename streamablehttp_client to streamable_http_client

14f7bbf

Apply pre-commit

f82d266

Add missing paramters

06f7ff4

felixweinberger force-pushed the rename-streamable-http branch 3 times, most recently from 7b05e41 to 579c35c Compare October 24, 2025 17:49

felixweinberger force-pushed the rename-streamable-http branch from 579c35c to 94df64b Compare October 24, 2025 17:55

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

Are you sure you want to change the base?

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

felixweinberger Oct 23, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

felixweinberger Oct 24, 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!

Choose a reason for hiding this comment

Uh oh!

felixweinberger Oct 24, 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!

felixweinberger Oct 24, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 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

felixweinberger Oct 23, 2025 •

edited

Loading

felixweinberger Oct 24, 2025 •

edited

Loading

felixweinberger Oct 24, 2025 •

edited

Loading

felixweinberger Oct 24, 2025 •

edited

Loading