Add `streamable_http_client` which accepts `httpx.AsyncClient` instead of `httpx_client_factory` by Kludex · Pull Request #1177 · modelcontextprotocol/python-sdk

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

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

Closeshttpx.ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain (_ssl.c:1002) #1370
ClosesSSLV3_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

 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.

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

 # 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.

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

tsingfei · 2026-01-05T16:20:29Z

Will McpHttpClientFactory be deprecated in the future? I need to automatically recreate the connection to a streamable-http mcp srerver. But now it seems that only create the connection with an http.AsyncClient instance is supported. Well, I need to write the factory myself or I can reuse the McpHttpClientFactory to implement that logic?

richardye101 · 2026-01-29T20:23:18Z

For anyone like me who just ran into this SSL issue and is unclear about how to use this PR to get around it, this is all I had to do on the client to bypass the SSL issues:

async with httpx.AsyncClient(verify=False) as custom_httpx_client:
async with streamable_http_client(url="https://my-mcp.com/mcp", http_client=custom_httpx_client) as (
read_stream,
write_stream,
_,
):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
tools = await session.list_tools()
print(tools)

…lient (#727) ## Summary  MCP python-sdk [updated streamable_http_client](modelcontextprotocol/python-sdk#1177), now deprecated in favor of `streamable_http_client` with a slightly different signature but returns the same exact tuple. Basically a name change! ## What Changed  ## Why  ## Related Issues  Closes # Related to # ## Checklist - [ ] I have performed a self-review of my code - [ ] I have made corresponding changes to the documentation (in https://github.com/dbt-labs/docs.getdbt.com) if required -- Mention it here - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes ## Additional Notes

The MCP Python SDK renamed the import from `streamablehttp_client` to `streamable_http_client` (PR modelcontextprotocol/python-sdk#1177). The old name is deprecated and has been removed from current main. Pyright/Windsurf flags it as deprecated. Signature is backward-compatible: `url` remains the only required arg and the context manager still yields a 3-tuple, so the destructuring `async with streamable_http_client(url) as (read, write, _):` still works without further changes.

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 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 74fa629Compare 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

Comment threadsrc/mcp/client/streamable_http.py Outdated

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

felixweinberger added needs more eyes and removed needs maintainer 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_factoryOct 1, 2025

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

felixweinberger reviewed Oct 1, 2025
View reviewed changes

felixweinbergerand others added 6 commits December 4, 2025 17:54

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 f897932Compare December 4, 2025 18:04

maxisbey approved these changes Dec 10, 2025
View reviewed changes

maxisbey merged commit a3a4b8d into mainDec 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 PrefectHQ/fastmcp#2594
Closed

felixweinberger mentioned this pull request Dec 11, 2025
V2: Redesign HTTP client lifecycle management with MCPClient/Client approach #1773
Closed

licux mentioned this pull request Dec 13, 2025
DeprecationWarning: Use streamable_http_client instead of streamablehttp_client aws/mcp-proxy-for-aws#128
Closed
1 task

DouweM mentioned this pull request Dec 17, 2025
MCPServerStreamableHTTP breaks with latest mcp version due to changes to streamble_http client pydantic/pydantic-ai#3745
Closed
2 tasks

eekstunt mentioned this pull request Dec 26, 2025
Fix MCPServerStreamableHTTP closing user-provided HTTP clients with MCP SDK 1.25+ pydantic/pydantic-ai#3854
Closed

ps06756 mentioned this pull request Dec 29, 2025
fix: Use streamable_http_client to avoid DeprecationWarning aws/mcp-proxy-for-aws#132
Closed
3 tasks

teknium1 mentioned this pull request Mar 29, 2026
fix(tools): use non-deprecated streamable_http_client for MCP HTTP transport (salvage #3391) NousResearch/hermes-agent#3646
Merged

jairus-m mentioned this pull request Apr 17, 2026
Update deprecated streamablehttp_client function to streamable_http_client dbt-labs/dbt-mcp#727
Merged
4 tasks

coderabbitaiBot mentioned this pull request Jun 22, 2026
Fix ts evaluations StavPonte11/text2sql-onboarding#21
Merged

maxrabin mentioned this pull request Jul 20, 2026
[DOCS] mcp.client.streamable_http switch from streamablehttp_client to streamable_http_client strands-agents/harness-sdk#3349
Open

Solaris-star mentioned this pull request Jul 20, 2026
docs(mcp): use streamable_http_client instead of deprecated name strands-agents/harness-sdk#3351
Open

maxisbey mentioned this pull request Jul 29, 2026
[Feature Request]: Support For "Proxy" in SSE and Streamable HTTP Client #1302
Closed

coderabbitaiBot mentioned this pull request Jul 30, 2026
chore: update dependencies JRM-FusionAL/FusionAL#79
Open

Uh oh!

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!

felixweinbergerOct 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!

felixweinbergerOct 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!

tsingfei commented Jan 5, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

richardye101 commented Jan 29, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

Kludex commented Jul 21, 2025•
edited
Loading

Kludex commented Jul 21, 2025•
edited by ihrpr
Loading

felixweinbergerOct 1, 2025•
edited
Loading

felixweinberger commented Oct 1, 2025•
edited
Loading

tsingfei commented Jan 5, 2026•
edited
Loading

richardye101 commented Jan 29, 2026•
edited
Loading