cannot import name 'streamablehttp_client': The MCP SDK 2 Rename, and the Timeout It Hides (2026)

Quick Answer (2026)

ImportError: cannot import name 'streamablehttp_client' from 'mcp.client.streamable_http' means you are running MCP Python SDK 2.x against client code written for 1.x. The function was renamed. One underscore moved:

streamablehttp_client is now streamable_http_client.

That rename is the easy half, and it is the only half most advice on this error covers. Two further things changed on the same call, and neither of them raises:

1. It now yields a 2-tuple, not a 3-tuple. The get_session_id callback is gone.
2. If you pass your own HTTP client, which you must if you previously used headers= or auth=, you silently lose the 300 second read timeout and inherit httpx2's flat 5 second default on a long-lived stream.

The second one is the expensive one, because your import starts working and your connection starts dropping.

Verified against mcp 2.2.0, read at source, in September 2026.

Why this broke on a day you changed nothing

The MCP Python SDK shipped 2.0.0 on 28 July 2026, and the release notes are blunt about what that means for installs:

Release notes, verbatim: "pip install mcp now installs 2.x."

So nothing in your code had to change. An unpinned dependency, a rebuilt container, a fresh lockfile, or a CI runner that does not cache wheels is enough. The same release moved 1.x to a maintenance branch that receives critical bug fixes and security patches only.

Confirm which side of the line you are on in one command:

python -c "import importlib.metadata as m; print(m.version('mcp'))"

Anything starting 2. is the new major. This is not a rare edge case. Anthropic's own skills repository hit it in August 2026, because its requirements file allowed the 2.x line through.

Which of the two breaks do you have?

The 2.0 rewrite split cleanly down the client and server line, and the two sides fail with different exceptions and need different fixes. Before changing anything, find out which one you are looking at:

python - <<'EOF'
import importlib
for mod, name in [
    ("mcp.client.streamable_http", "streamable_http_client"),
    ("mcp.client.streamable_http", "streamablehttp_client"),
    ("mcp.server.mcpserver", "MCPServer"),
]:
    try:
        m = importlib.import_module(mod)
        print(f"{mod}.{name}:", hasattr(m, name))
    except Exception as e:
        print(f"{mod}: {type(e).__name__}: {e}")
EOF

On 2.x you get True, False, True, in that order. The rest of this guide is the client side. If your traceback names mcp.server.fastmcp instead, skip to the server section below.

The rename, before and after

Here is the v1 call that raises:

from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client(
    url="http://localhost:8000/mcp",
    headers={"Authorization": "Bearer token"},
    timeout=30,
    sse_read_timeout=300,
) as (read_stream, write_stream, get_session_id):
    ...

Four of those five arguments no longer exist on the function. The v2 signature, copied from the source of mcp/client/streamable_http.py at tag v2.2.0, is the entire surface:

async def streamable_http_client(
    url: str,
    *,
    http_client: httpx2.AsyncClient | None = None,
    terminate_on_close: bool = True,
) -> AsyncGenerator[TransportStreams, None]:

headers, timeout, sse_read_timeout and auth moved off the transport and onto the HTTP client you hand it. httpx_client_factory was removed with no replacement: call your factory yourself and pass the result as http_client. terminate_on_close is unchanged.

The trap: the timeout you did not know you had

This is the part worth slowing down for, because it does not raise and it does not show up in a smoke test against a fast local server.

In v1, streamablehttp_client built its own HTTP client with MCP's timeouts baked in. In v2 that still happens, but only if you leave http_client unset. The source makes the branch explicit:

client_provided = http_client is not None
client = http_client

if client is None:
    # Create default client with recommended MCP timeouts
    client = create_mcp_http_client()

And create_mcp_http_client carries the constants:

MCP_DEFAULT_TIMEOUT = 30.0            # General operations (seconds)
MCP_DEFAULT_SSE_READ_TIMEOUT = 300.0  # SSE streams - 5 minutes (seconds)

Now put those two facts together. The only reason to pass http_client at all is that you needed headers or auth, which is to say you are talking to a remote, authenticated server. That is precisely the case where the server-to-client GET stream is held open longest, and it is precisely the case that loses the read timeout.

The middle row is what people write, because it is the smallest change that gets headers back. The migration guide flags the consequence in a single clause that is easy to read past:

Migration guide, verbatim: "a bare httpx2.AsyncClient() falls back to httpx2's flat 5-second timeout, too short for the long-lived GET stream"

So the failure mode is: import fixed, tests green against localhost, and then read timeouts on an idle stream in staging. If you migrated this call and started seeing dropped streams afterwards, this is the first thing to check.

The correct v2 form keeps the old numbers explicitly:

import httpx2
from mcp.client.streamable_http import streamable_http_client

http_client = httpx2.AsyncClient(
    headers={"Authorization": "Bearer token"},
    timeout=httpx2.Timeout(30, read=300),
)

async with http_client:
    async with streamable_http_client(
        url="http://localhost:8000/mcp",
        http_client=http_client,
    ) as (read_stream, write_stream):
        ...

Note httpx2, not httpx. The SDK swapped its HTTP dependency in the same release, so import httpx in this file is now the wrong library even on a machine where httpx is installed.

One thing you can drop while you are here: v1's internal client set follow_redirects=True. You do not need it. As of 2.2.0 the transport follows a method-preserving redirect within the endpoint's origin itself, and refuses to follow one anywhere else regardless of how your client is configured.

The 2-tuple, and getting the session id back

The third element of the tuple is gone:

# v1
async with streamablehttp_client(url) as (read_stream, write_stream, get_session_id):

# v2
async with streamable_http_client(url) as (read_stream, write_stream):

Keep the three-name form and you get a plain unpacking error, so unlike the timeout this one announces itself. The GetSessionIdCallback type alias was removed as well, and so was the StreamableHTTPTransport.get_session_id() method that backed it.

If you were using the callback for session-resumption tests, the documented replacement is an httpx2 response hook:

captured_session_ids: list[str] = []

async def capture_session_id(response: httpx2.Response) -> None:
    session_id = response.headers.get("mcp-session-id")
    if session_id:
        captured_session_ids.append(session_id)

http_client = httpx2.AsyncClient(event_hooks={"response": [capture_session_id]})

The hook fires on every response the client sees, so on a reconnecting client take the last entry rather than the first. Worth knowing if you write that test: terminate_on_close still defaults to True, so the transport sends its own DELETE on exit. If your test already deleted the session, pass terminate_on_close=False or you will see a Session termination failed: 404 warning from a second delete against a session that is already gone.

What did not change, so you do not over-migrate

Half the cost of a major version bump is touching things that were fine. Four useful negatives:

• sse_client is unchanged apart from being retyped to httpx2. It still takes url, headers, timeout, sse_read_timeout, auth and httpx_client_factory. Only the streamable HTTP transport lost its transport-level parameters, so do not migrate both by symmetry.
• ClientSession still exists and is still exported from the mcp package root. You are not forced onto the new high-level Client object just to get running again.
• stdio_client and StdioServerParameters keep their v1 import paths.
• Server-side transport entry points (stdio_server(), SseServerTransport, StreamableHTTPSessionManager) keep their v1 import paths and signatures.

If your traceback says mcp.server.fastmcp instead

That is the server side of the same release, and it is a different exception with a different fix. from mcp.server.fastmcp import FastMCP raises ModuleNotFoundError, because FastMCP was renamed to MCPServer and moved to mcp.server.mcpserver. The SDK ships a stub module at the old path whose only job is to say so, rather than let you see a bare "no module named" message with no hint that the installed SDK is a different major version.

One disambiguation is worth making explicitly, because community answers to this error routinely get it wrong. The thing that was renamed is the official SDK's FastMCP. The separately maintained fastmcp package is a different project with its own upgrade path and its own maintainer. "Change your import to from fastmcp import FastMCP" is advice to adopt a second dependency, not advice to complete this migration. Both are defensible choices. They are not the same choice.

Pin or migrate

There is a legitimate third answer, which is "not today".

Pinning is not a defeat. The 1.x line is explicitly maintained on its own branch and documented separately. What is not viable is leaving the requirement unbounded, because that is what turned a migration you could have scheduled into an outage you could not:

mcp            ->  resolves to 2.x today
mcp>=1.28,<2   ->  resolves to the maintained 1.x line

That upper bound is the vendor's own suggested form, and it is the single highest-value line to add to any MCP project you are not migrating this week.

A correction to our own tutorials

Two tutorials in this library were written against the v1 API and have been shipping imports that raise on a fresh install since 28 July 2026: our remote MCP server walkthrough, which uses streamablehttp_client, and our FastMCP server tutorial, which uses mcp.server.fastmcp. Both now carry a version note at the install step.

We found them by sweeping our own corpus for the third-party API entry points it depends on, not because anyone reported it. That is a reasonable argument that a tutorial library needs a standing check on the signatures it calls, and not only on the prices it quotes. A pinned version in a tutorial is a fact with a shelf life, and ours had expired six weeks earlier without anything noticing.

If you are debugging a server that starts and then dies, rather than one that fails to import, the companion piece is what MCP error -32000 actually means.