Repository navigation
Description
Summary
A tool result larger than 1 MiB can never reach a client on an HTTP transport. The client opens every SSE stream with httpx2's default DEFAULT_MAX_EVENT_SIZE_BYTES = 1024 * 1024:
- in
mcp/client/sse.py, throughclient.sse(url); - in
mcp/client/streamable_http.py, throughEventSource(response)in_handle_sse_response, the path a POST's response (and so atools/callresult) takes.
Neither sse_client nor streamable_http_client takes a size parameter. A custom http_client cannot change it either, because the size is a per-call argument of client.sse(...) / EventSource(...), not client configuration. The same result is delivered intact over stdio.
The failures also differ by transport:
- SSE: the call fails with
MCPError(-32000, 'Connection closed'), and the transport's task group then dies withSSEError('Server-sent event exceeded the 1048576 byte limit.'), so the whole session is lost. - Streamable HTTP: the call fails with
MCPError(-32000, 'SSE stream ended without a response'), which does not mention the size limit; the session survives.
Reproducer (self-contained: an MCPServer on loopback and the SDK clients)
import asyncio
import socket
import threading
import time
import uvicorn
from mcp import ClientSession
from mcp.client.sse import sse_client
from mcp.client.streamable_http import streamable_http_client
from mcp.server.mcpserver import MCPServer
server = MCPServer(name="big-result")
@server.tool()
async def big(megabytes: int) -> str:
"""Return `megabytes` MiB of text."""
return "x" * (megabytes * 1024 * 1024)
def serve(app) -> int:
with socket.socket() as sock:
sock.bind(("127.0.0.1", 0))
port = sock.getsockname()[1]
uv = uvicorn.Server(uvicorn.Config(app, host="127.0.0.1", port=port, log_level="error"))
threading.Thread(target=uv.run, daemon=True).start()
while not uv.started:
time.sleep(0.05)
return port
async def call(label: str, transport_cm) -> None:
try:
async with transport_cm as streams, ClientSession(streams[0], streams[1]) as session:
await session.initialize()
for mb in (0, 2):
try:
result = await asyncio.wait_for(session.call_tool("big", {"megabytes": mb}), 30)
print(f" {label} {mb} MiB: ok, is_error={result.is_error}")
except BaseException as exc:
print(f" {label} {mb} MiB: {type(exc).__name__}: {exc!r:.160}")
except BaseException as exc:
print(f" {label} session exit: {type(exc).__name__}: {exc!r:.200}")
async def main() -> None:
sse_port = serve(server.sse_app())
http_port = serve(server.streamable_http_app())
await call("sse", sse_client(f"http://127.0.0.1:{sse_port}/sse"))
await call("streamable-http", streamable_http_client(f"http://127.0.0.1:{http_port}/mcp"))
asyncio.run(main())Output:
sse 0 MiB: ok, is_error=False
sse 2 MiB: MCPError: MCPError(-32000, 'Connection closed', None)
sse session exit: ExceptionGroup: ExceptionGroup('unhandled errors in a TaskGroup', [SSEError('Server-sent event exceeded the 1048576 byte limit.')])
streamable-http 0 MiB: ok, is_error=False
streamable-http 2 MiB: MCPError: MCPError(-32000, 'SSE stream ended without a response')
Expected vs actual
| Expected | Actual | |
|---|---|---|
| Large results | delivered up to a size the caller can configure (for example max_event_size on sse_client / streamable_http_client, passed through to client.sse(...) and EventSource(...)) |
hard 1 MiB cap per SSE event, with no way to change it |
| When the cap is hit | the call fails with an error that names the limit; the session survives | SSE: the session dies; streamable HTTP: a generic "stream ended" error with no mention of size |
Servers that return documents, graph results or large search results routinely exceed 1 MiB.
Environment
mcp2.0.0,httpx22.13.0,anyio4.14.2,uvicorn(from the SDK's dependency set)- CPython 3.14.10
- Windows 11. Linux not tried; the limit comes from
httpx2's default and is platform-independent.
Workaround
None at the transport level. Downstream, the result-size limit is now an explicit host setting: oversized or failed calls are turned into a structured tool error naming the failure class, and each session is isolated so a transport failure cannot cancel the caller.
Activity
Shanmukh-l33t commentedon Nov 4, 2026
Half of this is already fixed upstream — the remaining gap is the legacy SSE transport, and I have a tested fix ready.
What landed since this report: the Streamable HTTP half shipped in #3600 (merged 2026-10-01, released in v2.3.0 on 2026-10-02):
streamable_http_client(url, max_sse_event_size=...)andStreamableHttpParameters.max_sse_event_size, default unchanged at 1 MiB,Nonedisables. The tested version above (2.0.0, 2026-07-28) predates it. On currentmain(af4c6f4) the reproducer's streamable-http leg passes 2 MiB fine with the limit raised, and with the default the one oversized call fails without killing the session.What is still broken (the SSE leg of the repro):
mcp/client/sse.pyhas no size parameter at all —sse_within_originhardcodes the 1 MiB default (mcp/shared/_httpx_utils.py), so a >1 MiB result still fails withMCPError(-32000, 'Connection closed')and takes the whole session with it. Prior art for the shape: #3338 covered every client SSE reader but was closed by its author after #3600 landed (it wasn't a maintainer rejection — the legacy path was just left out of scope of #3600).Fix, tested, on my fork:
fix/sse-client-max-event-size(99e6d2d4):sse_client(..., max_sse_event_size: int | None = DEFAULT_MAX_SSE_EVENT_SIZE)— same name, default andNonesemantics asstreamable_http_client; nonpositive values raiseValueError("max_sse_event_size must be positive or None")before any request, matchingStreamableHTTPTransport. Passed throughsse_within_originto theEventSource.DEFAULT_MAX_SSE_EVENT_SIZEmoves tomcp.shared._httpx_utilsas the single definition both transports share (streamable_httpkeeps re-exporting it).docs/client/transports.mdnotes the option onsse_client.Testing evidence:
TypeError: sse_client() got an unexpected keyword argument 'max_sse_event_size') and delivers intact with the limit raised (sabotage run without the src change: 3 failed / 3 passed — the 3 seam guards pass by design). Seam tests atsse_within_originpin the unchanged default (oversized event raiseshttpx2.SSEError, never truncated), a raised limit, andNone, plus theValueErrorcases.test_permission_error, which fails identically on pristinemainin a root environment (unrelated).coverage report: 100.00%, 0 partial branches (fail_under = 100passes).strict-no-coverclean.ruff check/ruff format --checkandpyrightclean.One observation from the repro: on the SSE death path the transport leaks its internal memory streams (unclosed
MemoryObjectSendStream/MemoryObjectReceiveStreamwarnings at GC time) — consistent with "the whole session is lost" being unclean teardown. Worth folding into whoever takes the error-semantics half (the report's ask that the error name the limit is still open; the streamable side already prefixesSSE stream failed:and lets httpx2's message name the limit).I'm not opening a PR here since unassigned-contributor PRs get auto-closed by the repo policy — the branch is ready for a maintainer to take as-is, or I'm happy to open a PR if invited.
AI disclosure: investigation, fix and tests were produced with AI assistance and reviewed and run by me.
media-ctrl commentedon Nov 4, 2026
lennardm commentedon Nov 4, 2026
Same here on mcp 2.2.0 / httpx2 2.12.0 (Windows 11, Python 3.13): a ~1.19 MB
tools/callresult from a remote streamable-HTTP MCP server failed deterministically withSSE stream ended without a response. A raw HTTP capture showed the server sent one complete, valid event; theSSEErroronly shows up withmcpdebug logging on.We work around it by wrapping
mcp.client.streamable_http.EventSourceso it defaults tomax_event_size=32 * 1024 * 1024. Amax_sse_event_sizeoption onstreamable_http_client(and surfacing theSSEErrortext in the synthesized error) would let us drop that monkeypatch.Shanmukh-l33t commentedon Nov 4, 2026
@lennardm both of your asks are already on
mainsince 2.2.0 — I diffedv2.2.0againstmainto be sure:streamable_http_client(..., max_sse_event_size=DEFAULT_MAX_SSE_EVENT_SIZE)(src/mcp/client/streamable_http.py:718onmain;Nonedisables the limit) is threaded into everyclient.sse(...)/EventSource(...)call in the transport, so theEventSourcemonkeypatch can go as soon as you're past 2.2.0.mainhas anexcept httpx2.SSEError as exc:branch synthesizing"SSE stream failed: {exc}"(:503-506), so the waiter learns "Server-sent event exceeded the 1048576 byte limit." Inv2.2.0there is no SSEError branch at all — the stream falls through to the generic handler and the waiter gets the bare"SSE stream ended without a response"(:499there), which is the confusing failure your capture shows. That matches why it only appeared with debug logging on.What's genuinely still open matches @media-ctrl's split:
sse_client(src/mcp/client/sse.py:36) still has no event-size knob onmain— that's what my branch adds (fix/sse-client-max-event-sizeat99e6d2d4933697942796bdf83118fd9e09eaea2a, compare: main...Shanmukh-l33t:python-sdk:fix/sse-client-max-event-size): the same parameter threaded intoclient.sse(...), sharingDEFAULT_MAX_SSE_EVENT_SIZE, so both transports accept the same event sizes. Thesse_clientside kills the session on overflow rather than failing one call, which is the asymmetry worth closing.SSEErrortext, and the same overflow manifests differently per transport.(Written with AI assistance; the version diff and line references were re-verified against
mainandv2.2.0today.)SalyyS1 commentedon Nov 11, 2026
While
streamable_http_client(..., max_sse_event_size=...)landed onmain(andsse_clientstill needs the same parameter threaded throughmcp/client/sse.py), it is worth noting what happens one layer up when atools/callresponse actually exceeds1 MiB:A
1.19 MBJSON-RPCtools/callpayload corresponds to roughly 280,000 to 320,000 tokens, which will immediately overflow the context window of most LLM providers (128k to 200k tokens) right after the SSE transport delivers it. In practice, payloads over 1 MiB almost always come from pretty-printed JSON arrays with repetitivenull/""/[]fields, noisy hypermedia URLs, or un-truncated log output.If you are connecting to an MCP server whose tool responses occasionally spike above
1 MiB(or if you are stuck onmcp <= 2.2.0/ legacy SSE), you can placemcp-slimin front of the server command:mcp-slim'sOutputSlimmerinterceptstools/callresponses on the wire, strips empty/null keys and hypermedia noise, minifies JSON/JSONL/Markdown tables, flattens verbose resource wrappers, and applies head+tail elision on oversized string fields—typically shrinking multi-megabyte JSON tool outputs well below the1048576-byte SSE event cap while cutting LLM context token consumption by 43% to 75%.area51tazz commentedon Nov 17, 2026
Confirming the SSE half on a real deployment, plus measurements on 2.3.0 and
main, in case they help.Where we hit it. An agent host on mcp 2.3.0 / httpx2 2.12.0 (CPython 3.14, Linux) talks to a crawl4ai MCP server over
transport: ssethrough a reverse proxy. Atools/callthat converted a ~4.3 MB page to markdown failed withhttpx2.SSEError: Server-sent event exceeded the 1048576 byte limit., the session was lost, and an immediate retry failed the same way. The server logged a completed fetch both times. Calls in the same deployment returning 323,134 and 645,823 characters succeeded. The host has no way to raise the limit, becausesse_client()doesn't take one.Measured locally (loopback
MCPServer, one fresh session per probe):structured_output=False), SSE and streamable HTTPstrtool, SSE and streamable HTTPmain(77001c9).sse_clientonmainstill has no size parameter.strtool sends the payload twice (text content plusstructuredContent), so its effective ceiling is about 512 KiB, not 1 MiB. That may be worth noting in the docs whatever happens to this issue._sse.py:90). Framing costs 109 bytes for a text-only result and 144 for the structured one.Connection closed). Streamable HTTP keeps the session, and on 2.3.0 its error now names the limit (SSE stream failed: Server-sent event exceeded the 1048576 byte limit.).max_sse_event_size=8 << 20(orNone) delivers a 4 MiB result on 2.3.0.#3832 fixes the SSE half. I applied its diff to
main(77001c9), unchanged.sse_client(url, max_sse_event_size=8 << 20)and=Noneboth deliver a 4 MiB result, and the default boundary is unchanged (1,048,467 passes, 1,048,468 fails).tests/shared/test_sse.pyandtests/client/test_session_group.pypass (43, against 40 onmain). The change is small becausesse_within_origin()already acceptsmax_event_size.sse_clientjust never passes it (client/sse.py:70).Repro (loopback only, mcp ≥ 2.3.0 + uvicorn; the last line prints whether
sse_clienthas the parameter):Output on 2.3.0:
On
mainwith #3832 applied, the last line becomessse, max=8 MiB text 4,194,304: ok (4,194,304 chars), and every other line is the same.Not verified: the byte size of our real failing result (our logs record the limit and the failure, not the size).
Disclosure: the diagnosis, measurements and this comment were prepared with AI assistance (Claude).
MrGaziz commentedon Nov 18, 2026
Hi, we're hitting the SSE half of this in production too (mcp 2.3.0).
Our stdio MCP servers are exposed over SSE through supergateway, so any tool result over ~1 MiB fails and the session is lost.
We've worked around it by patching
mcp.client.sse.sse_within_originwith a largermax_event_size, but we'd much rather use a supported option.Would a maintainer be open to adding
max_sse_event_sizetosse_client, the same asstreamable_http_clientgot in #3600?There's already a tested change for it (#3832, auto-closed because nobody was assigned).
Happy to help test it.
Thanks for all the work on v2!