Skip to content

The agent that grows with you

fix(mcp): accept SSE responses over 1 MiB on Streamable HTTP

khanaleem727-eng7daa2e75d1a2
diff --git a/hermes_cli/mcp_config.py b/hermes_cli/mcp_config.py
index 3bb246863c3..1c9463f93de 100644
--- a/hermes_cli/mcp_config.py
+++ b/hermes_cli/mcp_config.py
@@ -827,9 +827,13 @@ def _probe_failure_next_step(name: str, exc: BaseException) -> str:
return f"The server rejected the sign-in. Run: hermes mcp login {name}"
if isinstance(root, NodeAbiMismatchError):
return f"After rebuilding it under Hermes's Node as above, run: hermes mcp test {name}"
- if "missing executable" in _format_connect_error(exc):
+ reason = _format_connect_error(exc)
+ if "missing executable" in reason:
return (f"Install that command, or set mcp_servers.{name}.command in {display_hermes_home()}/config.yaml "
"to its full path.")
+ if reason.startswith("MCP response exceeded"):
+ return (f"The server is up but sent one response over that limit. If mcp_servers.{name}.transport is "
+ "sse, try removing it: Streamable HTTP accepts larger events.")
return f"Check the server is running and the URL/command in its config, then run: hermes mcp test {name}"
diff --git a/tests/tools/test_mcp_http_body_cap.py b/tests/tools/test_mcp_http_body_cap.py
index 8846366365f..593fbf93848 100644
--- a/tests/tools/test_mcp_http_body_cap.py
+++ b/tests/tools/test_mcp_http_body_cap.py
@@ -36,7 +36,7 @@ async def test_oversized_body_rejected_via_content_length():
async def handler(request):
return httpx.Response(200, content=body)
async with _client_for(handler) as client:
- with pytest.raises(httpx.ReadError, match=r"Content-Length"):
+ with pytest.raises(httpx.ReadError, match=r"exceeded \d+ bytes \(declared Content-Length"):
await client.get("http://mcp.test/rpc")
@@ -55,7 +55,7 @@ async def test_oversized_streamed_body_rejected_without_content_length():
async def handler(request):
return httpx.Response(200, stream=_Stream())
async with _client_for(handler) as client:
- with pytest.raises(httpx.ReadError, match=r"HTTP response exceeds"):
+ with pytest.raises(httpx.ReadError, match=r"exceeded \d+ bytes \(from"):
await client.get("http://mcp.test/rpc")
@@ -75,7 +75,7 @@ async def test_sse_event_over_cap_rejected():
headers={"content-type": "text/event-stream"},
)
async with _client_for(handler) as client:
- with pytest.raises(httpx.ReadError, match=r"SSE event exceeds"):
+ with pytest.raises(httpx.ReadError, match=r"exceeded \d+ bytes in one SSE event"):
async with client.stream("GET", "http://mcp.test/sse") as resp:
async for _ in resp.aiter_bytes():
pass
@@ -126,7 +126,7 @@ async def test_sse_event_split_across_chunks_counts_prefix():
headers={"content-type": "text/event-stream"},
)
async with _client_for(handler) as client:
- with pytest.raises(httpx.ReadError, match=r"SSE event exceeds"):
+ with pytest.raises(httpx.ReadError, match=r"exceeded \d+ bytes in one SSE event"):
async with client.stream("GET", "http://mcp.test/sse") as resp:
async for _ in resp.aiter_bytes():
pass
@@ -181,7 +181,7 @@ async def test_sse_crlf_split_across_chunks_inside_event_is_not_a_boundary():
# the cap would evade it.
chunks = [_EVENT1 + b"\r", b"\n" + _EVENT2 + b"\r\n\r\n"]
async with _sse_client(chunks) as client:
- with pytest.raises(httpx.ReadError, match=r"SSE event exceeds"):
+ with pytest.raises(httpx.ReadError, match=r"exceeded \d+ bytes in one SSE event"):
async with client.stream("GET", "http://mcp.test/sse") as resp:
async for _ in resp.aiter_bytes():
pass
diff --git a/tests/tools/test_mcp_large_sse_event.py b/tests/tools/test_mcp_large_sse_event.py
new file mode 100644
index 00000000000..2d7f811dc82
--- /dev/null
+++ b/tests/tools/test_mcp_large_sse_event.py
@@ -0,0 +1,119 @@
+"""One MCP response delivered as a single SSE event larger than 1 MiB.
+
+httpx2 2.12 bounds every ``EventSource`` at 1 MiB by default, and the mcp SDK's Streamable HTTP
+client inherits that bound unless the caller passes ``max_sse_event_size``. A server whose
+``tools/list`` is one ~1 MiB event (a 162-tool catalog) then failed to connect and was parked with
+0 tools, although Hermes' own wire-body cap is 10 MiB per event. Each test serves a real catalog
+from a local MCP server subprocess and drives ``hermes mcp test`` / the shared connect path.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+
+import pytest
+
+import hermes_yaml as yaml
+from hermes_constants import get_hermes_home
+from tests.waiting import wait_until
+from tools.mcp_tool_errors import _MCP_HTTP_MAX_BODY_BYTES
+
+_SERVER = """
+import asyncio, socket, sys
+import uvicorn
+from mcp.server import MCPServer
+transport, count, description_bytes, port_path = sys.argv[1], int(sys.argv[2]), int(sys.argv[3]), sys.argv[4]
+server = MCPServer("catalog")
+
+def noop() -> str:
+ return "ok"
+
+for i in range(count):
+ server.add_tool(noop, name=f"tool_{i}", description="d" * description_bytes)
+app = server.sse_app() if transport == "sse" else server.streamable_http_app()
+sock = socket.socket()
+sock.bind(("127.0.0.1", 0))
+uv = uvicorn.Server(uvicorn.Config(app, log_level="warning"))
+
+async def main():
+ task = asyncio.create_task(uv.serve(sockets=[sock]))
+ while not uv.started:
+ await asyncio.sleep(0.01)
+ open(port_path, "w", encoding="utf-8").write(str(sock.getsockname()[1]))
+ await task
+
+asyncio.run(main())
+"""
+
+_SDK_DEFAULT_EVENT_LIMIT = 1024 * 1024
+# 162 tools x 6.6 KB: the shape (and size) of a real catalog that crossed the 1 MiB default.
+_JUST_OVER_ONE_MIB = (162, 6_600)
+
+
+def catalog_server(tmp_path):
+ """Start a local MCP server ``(transport, tool_count, description_bytes)``; yields its URL."""
+ procs = []
+
+ def start(transport: str, count: int, description_bytes: int) -> str:
+ script, port_file = tmp_path / "catalog_server.py", tmp_path / f"port-{len(procs)}"
+ script.write_text(_SERVER, encoding="utf-8")
+ procs.append(subprocess.Popen([sys.executable, str(script), transport, str(count),
+ str(description_bytes), str(port_file)]))
+ wait_until(lambda: port_file.exists() and port_file.read_text(encoding="utf-8"), timeout=30,
+ what="MCP test server to bind")
+ path = "/sse" if transport == "sse" else "/mcp"
+ return f"http://127.0.0.1:{port_file.read_text(encoding='utf-8')}{path}"
+
+ yield start
+ from tools.mcp_tool_lifecycle import shutdown_mcp_servers
+ shutdown_mcp_servers()
+ for proc in procs:
+ proc.terminate()
+ proc.wait(10)
+
+
+def _mcp_test(capsys, entry: dict) -> tuple[int, str]:
+ """``hermes mcp test catalog`` against *entry*; returns (exit code, printed output)."""
+ from hermes_cli.mcp_config import cmd_mcp_test
+
+ (get_hermes_home() / "config.yaml").write_text(yaml.safe_dump({"mcp_servers": {"catalog": entry}}),
+ encoding="utf-8")
+ capsys.readouterr()
+ code = cmd_mcp_test(argparse.Namespace(name="catalog"))
+ return code, capsys.readouterr().out
+
+
+def test_streamable_http_tools_list_over_one_mib_connects(catalog_server, capsys):
+ count, description_bytes = _JUST_OVER_ONE_MIB
+ assert count * description_bytes > _SDK_DEFAULT_EVENT_LIMIT
+ url = catalog_server("http", count, description_bytes)
+
+ code, out = _mcp_test(capsys, {"url": url})
+
+ assert code == 0, out
+ assert f"Tools discovered: {count}" in out
+
+
+def test_streamable_http_event_over_hermes_cap_names_the_byte_limit(catalog_server, capsys):
+ url = catalog_server("http", 2, _MCP_HTTP_MAX_BODY_BYTES // 2 + 1024)
+
+ code, out = _mcp_test(capsys, {"url": url, "connect_timeout": 20})
+
+ assert code == 1
+ assert f"exceeded {_MCP_HTTP_MAX_BODY_BYTES} bytes" in out, out
+ assert "SSE stream ended" not in out
+
+
+def test_legacy_sse_event_over_sdk_limit_names_the_byte_limit(catalog_server, capsys):
+ # The legacy SSE client exposes no event-size knob, so its SDK default still applies; the
+ # failure must say so instead of reading as a generic dropped stream.
+ url = catalog_server("sse", *_JUST_OVER_ONE_MIB)
+
+ code, out = _mcp_test(capsys, {"url": url, "transport": "sse", "connect_timeout": 20})
+
+ assert code == 1
+ assert f"exceeded {_SDK_DEFAULT_EVENT_LIMIT} bytes" in out, out
+ assert "mcp_servers.catalog.transport" in out # the next step names the setting that lifts the limit
diff --git a/tools/mcp_tool_errors.py b/tools/mcp_tool_errors.py
index 0d48a0c941c..5e85b96b051 100644
--- a/tools/mcp_tool_errors.py
+++ b/tools/mcp_tool_errors.py
@@ -328,7 +328,9 @@ def _make_redirect_header_stripper(httpx_mod, original_url, *, strict: bool = Fa
# Finite HTTP bodies are capped at this many bytes (a larger Content-Length is rejected up front);
# each SSE *event* is capped, with the counter reset at completed event boundaries so a long-lived
# stream and its keepalives have no cumulative limit. Violations raise the SDK httpx's ReadError and
-# flow through the ordinary transport teardown/reconnect path (#66092).
+# flow through the ordinary transport teardown/reconnect path (#66092). The Streamable HTTP client
+# hands this same bound to the SDK's own per-event SSE parser (``max_sse_event_size``), so one limit
+# judges an event rather than httpx2's tighter 1 MiB default underneath it.
_MCP_HTTP_MAX_BODY_BYTES = 10 * 1024 * 1024
# An SSE event ends at a blank line: two consecutive line terminators. The spec allows CR,
# LF, or CRLF terminators and permits mixing them, so the boundary is any of \n\n, \r\r,
@@ -341,13 +343,21 @@ _SSE_BOUNDARY_CARRY = 3 # longest boundary ("\r\n\r\n") minus one byte
def _make_mcp_body_cap_transport(httpx_mod, inner_transport, limit: int = _MCP_HTTP_MAX_BODY_BYTES):
"""Wrap ``inner_transport`` so every response body is size-capped. ``httpx_mod`` must be the SDK's
own httpx module (``sdk_httpx()``): the transport is handed to that SDK's ``AsyncClient``."""
+ # An oversized event is also this httpx's SSEError (httpx2; the plain httpx of mcp 1.x has none):
+ # the SDK fails the waiting request with an SSEError's message, while any other error mid-event
+ # reads as "SSE stream ended without a response" or triggers a Last-Event-ID reconnect that
+ # fetches the same event again.
+ bases = (httpx_mod.ReadError, httpx_mod.SSEError) if hasattr(httpx_mod, "SSEError") else (httpx_mod.ReadError,)
+ event_too_large = type("MCPEventTooLarge", bases, {})
class _CappedStream(httpx_mod.AsyncByteStream):
def __init__(self, inner, is_sse: bool, url: str):
self._inner, self._is_sse, self._url = inner, is_sse, url
- def _reject(self, kind: str):
- return httpx_mod.ReadError(f"MCP {kind} exceeds {limit} bytes (from {self._url})")
+ def _reject(self):
+ if self._is_sse:
+ return event_too_large(f"MCP response exceeded {limit} bytes in one SSE event (from {self._url})")
+ return httpx_mod.ReadError(f"MCP response exceeded {limit} bytes (from {self._url})")
async def __aiter__(self):
counted = 0
@@ -365,14 +375,14 @@ def _make_mcp_body_cap_transport(httpx_mod, inner_transport, limit: int = _MCP_H
if end <= len(tail):
continue # boundary completed inside the carried suffix: already counted
if counted + end - max(pos, len(tail)) > limit:
- raise self._reject("SSE event")
+ raise self._reject()
counted, pos = 0, end
counted += len(window) - max(pos, len(tail))
tail = window[-_SSE_BOUNDARY_CARRY:]
else:
counted += len(chunk)
if counted > limit:
- raise self._reject("SSE event" if self._is_sse else "HTTP response")
+ raise self._reject()
yield chunk
async def aclose(self):
@@ -388,8 +398,8 @@ def _make_mcp_body_cap_transport(httpx_mod, inner_transport, limit: int = _MCP_H
with contextlib.suppress(ValueError): # malformed header: the streamed cap still applies
if declared is not None and int(declared) > limit:
await response.aclose()
- raise httpx_mod.ReadError(f"MCP HTTP response declares Content-Length {declared} > {limit} "
- f"bytes cap (from {request.url})")
+ raise httpx_mod.ReadError(f"MCP response exceeded {limit} bytes (declared Content-Length "
+ f"{declared}, from {request.url})")
is_sse = "text/event-stream" in response.headers.get("content-type", "").lower()
response.stream = _CappedStream(response.stream, is_sse, str(request.url))
return response
@@ -432,9 +442,30 @@ def _iter_exception_nodes(exc: BaseException) -> list[BaseException]:
return ordered
+# A response over a byte cap, in each cap's words: the wire-body cap above, and httpx2's per-event SSE
+# parser limit, which the legacy SSE client cannot raise. Matched as text because on Streamable HTTP the
+# SDK returns the failure as a JSON-RPC error message ("SSE stream failed: ..."), not an exception chain.
+_OWN_CAP_RE = re.compile(r"MCP response exceeded \d+ bytes.*")
+_SDK_EVENT_LIMIT_RE = re.compile(r"Server-sent event exceeded the (\d+) byte limit")
+
+
+def _oversized_response(nodes: list[BaseException]) -> Optional[str]:
+ """The cap a response broke, worded alike for either cap; ``None`` when no cap tripped."""
+ for node in nodes:
+ text = str(node)
+ if own := _OWN_CAP_RE.search(text):
+ return own.group(0)
+ if sdk := _SDK_EVENT_LIMIT_RE.search(text):
+ return f"MCP response exceeded {sdk.group(1)} bytes in one SSE event (the MCP SDK's per-event limit)"
+ return None
+
+
def _format_connect_error(exc: BaseException) -> str:
"""Render nested MCP connection errors into an actionable short message."""
nodes = _iter_exception_nodes(exc)
+ oversized = _oversized_response(nodes)
+ if oversized is not None: # the whole story; "SSE stream failed" / "Connection closed" add nothing
+ return _sanitize_error(oversized)
def _find_missing() -> Optional[str]:
for current in nodes:
diff --git a/tools/mcp_tool_transport.py b/tools/mcp_tool_transport.py
index dce9bde52b4..700678d618b 100644
--- a/tools/mcp_tool_transport.py
+++ b/tools/mcp_tool_transport.py
@@ -4,6 +4,7 @@ protocol negotiation and initial tool discovery. Split from tools/mcp_tool.py.""
import logging
import asyncio
+import inspect
import os
import urllib.parse
import urllib.request
@@ -12,7 +13,7 @@ from typing import Dict, Optional, Set
from utils import normalize_proxy_url
from agent.proxy_bypass import is_loopback_host, should_bypass_proxy
from agent import runtime_cwd as _runtime_cwd
-from tools.mcp_tool_errors import NonMcpEndpointError, _apply_identity_header, _describe_http_failure, _handshake_answered_with_unsupported_version, _handshake_rejected_as_modern, _is_streamable_http_rejection, _make_http_rejection_recorder, _make_mcp_body_cap_transport, _make_redirect_header_stripper, _resolve_client_cert, _unwrap_exception_group
+from tools.mcp_tool_errors import _MCP_HTTP_MAX_BODY_BYTES, NonMcpEndpointError, _apply_identity_header, _describe_http_failure, _handshake_answered_with_unsupported_version, _handshake_rejected_as_modern, _is_streamable_http_rejection, _make_http_rejection_recorder, _make_mcp_body_cap_transport, _make_redirect_header_stripper, _resolve_client_cert, _unwrap_exception_group
from tools.mcp_tool_lifecycle import _filter_mcp_children, _leader_start_time, _orphan_stdio_pid_servers, _orphan_stdio_pids, _stdio_pgids, _stdio_pids, _stdio_starttimes
from tools.mcp_tool_common import _core
from tools.mcp_tool_node_abi import node_abi_error
@@ -79,6 +80,19 @@ def _mcp_proxy_mounts(httpx_mod, url: str, ssl_verify, client_cert, server_name:
return mounts or None
+def _sse_event_limit_kwargs(client_fn) -> dict:
+ """``max_sse_event_size`` at the wire-body cap, for an SDK Streamable HTTP client that takes it.
+
+ Left unset, the SDK parses each SSE event against httpx2's 1 MiB default, a tighter second cap
+ under the wire cap: a server sending ``tools/list`` as one ~1 MiB event (a 162-tool catalog)
+ could not connect at all. Older SDKs take no such argument."""
+ try:
+ accepted = "max_sse_event_size" in inspect.signature(client_fn).parameters
+ except (TypeError, ValueError):
+ accepted = False
+ return {"max_sse_event_size": _MCP_HTTP_MAX_BODY_BYTES} if accepted else {}
+
+
def _pgroup_alive(pgid: Optional[int]) -> bool:
"""Signal 0 to the group succeeds iff any member is alive (POSIX only)."""
try:
@@ -586,10 +600,12 @@ class MCPServerTransportMixin:
**_present(mounts=_mcp_proxy_mounts(httpx, url, ssl_verify, client_cert, self.name),
auth=oauth_auth)}
+ sdk_kwargs = _sse_event_limit_kwargs(_core.streamable_http_client)
+
@asynccontextmanager
async def _owned_client_streams(): # the SDK skips cleanup when http_client is provided
async with _build_client(**client_kwargs) as http_client:
- async with _core.streamable_http_client(url, http_client=http_client) as streams:
+ async with _core.streamable_http_client(url, http_client=http_client, **sdk_kwargs) as streams:
yield streams
return _owned_client_streams()
diff --git a/website/docs/user-guide/features/mcp.md b/website/docs/user-guide/features/mcp.md
index 461f70fdb07..150c7e15d77 100644
--- a/website/docs/user-guide/features/mcp.md
+++ b/website/docs/user-guide/features/mcp.md
@@ -912,6 +912,15 @@ speaks SSE only (set `transport: sse`) or a proxy in front of it rejects the req
means the token or OAuth grant is wrong; an HTML body means the URL points at a web page, not an MCP
endpoint. `hermes logs --level debug` additionally shows the exact endpoint each connect attempt used.
+### A server's response is too large
+
+Hermes accepts up to 10 MiB in one HTTP response, or in one SSE event of a streamed response, so a
+large `tools/list` catalog or tool result fits. Anything bigger fails with
+`MCP response exceeded 10485760 bytes ...`. On the legacy SSE transport (`transport: sse`) the MCP
+SDK caps each event at 1 MiB and offers no way to raise it; that failure reads
+`MCP response exceeded 1048576 bytes in one SSE event (the MCP SDK's per-event limit)`. If the
+server also serves Streamable HTTP, remove `transport: sse` from its entry.
+
### Tools not appearing
Possible causes: