The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.pyindex 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.pyindex 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():passdiff --git a/tests/tools/test_mcp_large_sse_event.py b/tests/tools/test_mcp_large_sse_event.pynew file mode 100644index 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 limitdiff --git a/tools/mcp_tool_errors.py b/tools/mcp_tool_errors.pyindex 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 bytedef _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'sown 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_Hif end <= len(tail):continue # boundary completed inside the carried suffix: already countedif counted + end - max(pos, len(tail)) > limit:- raise self._reject("SSE event")+ raise self._reject()counted, pos = 0, endcounted += 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 chunkasync def aclose(self):@@ -388,8 +398,8 @@ def _make_mcp_body_cap_transport(httpx_mod, inner_transport, limit: int = _MCP_Hwith contextlib.suppress(ValueError): # malformed header: the streamed cap still appliesif 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.pyindex 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 loggingimport asyncio+import inspectimport osimport urllib.parseimport urllib.request@@ -12,7 +13,7 @@ from typing import Dict, Optional, Setfrom utils import normalize_proxy_urlfrom agent.proxy_bypass import is_loopback_host, should_bypass_proxyfrom 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_groupfrom tools.mcp_tool_lifecycle import _filter_mcp_children, _leader_start_time, _orphan_stdio_pid_servers, _orphan_stdio_pids, _stdio_pgids, _stdio_pids, _stdio_starttimesfrom tools.mcp_tool_common import _corefrom 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)+@asynccontextmanagerasync def _owned_client_streams(): # the SDK skips cleanup when http_client is providedasync 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 streamsreturn _owned_client_streams()diff --git a/website/docs/user-guide/features/mcp.md b/website/docs/user-guide/features/mcp.mdindex 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 reqmeans the token or OAuth grant is wrong; an HTML body means the URL points at a web page, not an MCPendpoint. `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 appearingPossible causes: