Skip to content

Commit f2f104d

Browse files
Return 405 on GET /mcp so idle SSE streams stop exhausting Cloud Run (#4181)
The hosted docs MCP server returned `429 Rate exceeded` to a customer's MCP gateway, and to every other client using the server at the time (EXP-577). The cause was server-to-client SSE streams that the server accepts but never uses. This PR makes the server refuse them with `405`, which the MCP spec defines for exactly this case. ## Cause - The 429 isn't a configured rate limit. It's Cloud Run's response when no instance has a free request slot. The service allows 3 instances at Terraform's default concurrency of 80, so 240 requests can be in flight at once, shared by every client. - Since #4055 the server runs stateless. In that mode the MCP Python SDK still accepts `GET /mcp` from clients on the 2025 protocol versions. It holds the stream open with a keepalive ping every 15 seconds and never sends anything, because a stateless server has nothing to send. - Cloud Run closes each stream at its 300-second request timeout, so every GET holds a slot for five minutes. Measured against the live server: 302.6 seconds. - In the customer's report, 286 GETs arrived in five minutes. At five minutes each, that's about 286 open streams against 240 slots. Once the slots fill, Cloud Run returns 429 to everything, including `initialize`. This is an upstream SDK bug: [modelcontextprotocol/python-sdk#2474](modelcontextprotocol/python-sdk#2474), still open, with no fix in 2.3.0. ## Changes **`scripts/mcp-server.py`** - A new `build_http_app()` builds the SDK's Starlette app with the same `stateless_http=True` and `json_response=True` settings as before. It then inserts a GET-only route ahead of the SDK's `/mcp` route, and that route returns `405` with `Allow: POST`. - Starlette matches routes in order and the new route accepts only GET and HEAD, so POST and DELETE still reach the SDK. The SDK's `custom_route()` can't do this, because it adds routes after `/mcp`. - The HTTP branch runs that app with `uvicorn.run()` instead of `server.run()`. It passes the same host, port, and log level the SDK's runner passes, and uvicorn still reads `FORWARDED_ALLOW_IPS` from the environment, so the #3704 redirect fix is unaffected. - The CUS-1340 explanation moves into the new function's docstring, which also covers EXP-577. Stdio mode is unchanged. **`scripts/test_mcp_transport.py`** - The source-inspection test, which looked for a `server.run(... stateless_http=True)` call, is replaced by functional tests that send requests to the app production serves: - GET returns `405` with `Allow: POST`, with and without a protocol-version header. - `initialize` returns a JSON result and mints no `Mcp-Session-Id`. - `tools/list` works without a session. - Starlette's `TestClient` runs as a context manager so the app's lifespan starts the SDK's session manager. Without it, every POST returns 500. **`.github/workflows/mcp-image-smoke-test.yaml`** - The `unit-test` job installs `pytest-timeout`. If the 405 route regresses, the GET opens a stream that never ends, and the test hangs instead of failing. The GET test has a 10-second timeout, and the job has no `timeout-minutes` of its own. **`scripts/smoke-test-mcp.sh`** - New Check 5 sends a GET to the built image and expects `405`. The comment that explained why the script never sends GET is updated. ## Testing - `pytest scripts/test_mcp_server.py scripts/test_mcp_transport.py scripts/test_compile_docs.py`: 48 passed. - Each new test fails when its setting is broken: - Without the 405 route, the GET tests hang, and `pytest-timeout` fails them after 10 seconds. - With `stateless_http=False`, the `initialize` and `tools/list` tests fail. - With `json_response=False`, the same two tests fail. - Built the image from this branch and from `main` with CI's placeholder artifacts. `smoke-test-mcp.sh` passes all five checks on this branch. On `main`, Check 5 fails with a 200. - Ran two real clients against the container: - Claude Code, which uses the MCP TypeScript SDK, sent one GET after `initialize`, got the 405, didn't retry, and completed a `search_docs` call. - The MCP Python SDK client lists all five tools and calls `search_docs`. It never sends a GET. - `POST /mcp/` with `X-Forwarded-Proto: https` still redirects to `https://mcp.edu.chainguard.dev/mcp`. A code review of the Envoy AI Gateway and the MCP TypeScript SDK found that both treat a 405 on GET as "no stream" and don't retry. Cursor's own client, Goose, and older TypeScript SDK versions weren't checked. ## Not in this PR - No infrastructure change. Without the idle streams, 240 slots is plenty for short tool calls. If 429s continue after the deploy, the next step is a shorter Cloud Run request timeout in `iac/`. - I haven't seen server logs or metrics, because Docs has no access to the GCP project. A log query for `httpRequest.status=429` on the `mcp-server` service for 2026-09-30, 16:17 to 16:22 UTC would confirm where the 429s came from. ## After merge The `scripts/**` push trigger redeploys the hosted server. Then a `GET` to `https://mcp.edu.chainguard.dev/mcp` with `MCP-Protocol-Version: 2025-11-25` should return `405` right away instead of holding the stream open. Refs EXP-577, CUS-1340 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- Created in collaboration with Claude Code running Opus 5.5 on 2026-10-09. Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 03c9a13 commit f2f104d

4 files changed

Lines changed: 204 additions & 80 deletions

File tree

‎.github/workflows/mcp-image-smoke-test.yaml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,10 @@ jobs:
4949
with:
5050
python-version: '3.13'
5151

52+
# pytest-timeout fails test_mcp_transport.py's GET test if it hangs, which
53+
# is how a regression of the 405 route shows up (EXP-577).
5254
- name: Install dependencies
53-
run: pip install -r scripts/mcp-requirements.txt pytest pyyaml
55+
run: pip install -r scripts/mcp-requirements.txt pytest pytest-timeout pyyaml
5456

5557
- name: Run tests
5658
run: pytest scripts/test_mcp_server.py scripts/test_mcp_transport.py scripts/test_compile_docs.py -v

‎scripts/mcp-server.py‎

Lines changed: 64 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,13 @@
2525

2626
# MCP SDK imports (2.0 high-level API)
2727
try:
28+
import uvicorn
2829
from mcp.server import MCPServer
2930
from pydantic import Field
31+
from starlette.applications import Starlette
32+
from starlette.requests import Request
33+
from starlette.responses import Response
34+
from starlette.routing import Route
3035
except ImportError:
3136
import sys
3237

@@ -690,6 +695,55 @@ def find_image_equivalent(
690695
return response
691696

692697

698+
async def refuse_sse_stream(request: Request) -> Response:
699+
"""Answer GET /mcp with 405: this server offers no server-to-client stream."""
700+
return Response(status_code=405, headers={"Allow": "POST"})
701+
702+
703+
def build_http_app(host: str) -> Starlette:
704+
"""Build the streamable-HTTP app that serves /mcp.
705+
706+
stateless_http holds no per-session state in instance memory. The service
707+
runs multiple Cloud Run instances behind a global load balancer with no
708+
session affinity, so a session minted by initialize on one instance is
709+
rejected with 404 "Session not found" when a follow-up request (e.g.
710+
notifications/initialized) lands on another (CUS-1340). The docs tools are
711+
read-only with no server-initiated notifications, so holding no shared
712+
session state has no downside. Statelessness also retires the SDK's
713+
per-session ceilings (max_sessions, session_idle_timeout); throughput is
714+
now bounded by Cloud Run per-instance concurrency instead.
715+
716+
json_response returns each POST reply as a single application/json body
717+
instead of a one-shot text/event-stream. These tools are read-only and
718+
single-response, so nothing needs SSE framing, and plain JSON is friendlier
719+
to the fronting load balancer and buffering proxies.
720+
721+
The first route answers GET (and HEAD) /mcp with 405, which the MCP spec
722+
defines as "no SSE stream offered here" and requires clients to handle.
723+
In stateless mode the SDK still accepts GET and holds the stream open,
724+
sending only keepalive pings, until Cloud Run's 300-second request
725+
timeout. Each open stream holds one of the service's Cloud Run request
726+
slots; enough of them filled every slot, and Cloud Run returned 429 to all
727+
callers (EXP-577; upstream: modelcontextprotocol/python-sdk#2474).
728+
Starlette matches routes in order and this route accepts only GET and
729+
HEAD, so it must come first; POST and DELETE fall through to the SDK's
730+
/mcp route. The SDK's custom_route() can't do this, because it adds routes
731+
after /mcp.
732+
"""
733+
# streamable_http_path defaults to "/mcp" and max_request_body_size to
734+
# 4 MiB. host is passed so the SDK applies the same transport-security
735+
# defaults it would under server.run().
736+
app = server.streamable_http_app(
737+
host=host,
738+
stateless_http=True,
739+
json_response=True,
740+
)
741+
app.router.routes.insert(
742+
0, Route("/mcp", endpoint=refuse_sse_stream, methods=["GET"])
743+
)
744+
return app
745+
746+
693747
def parse_args():
694748
"""Parse command-line arguments with env var fallbacks."""
695749
parser = argparse.ArgumentParser(
@@ -721,34 +775,20 @@ def parse_args():
721775
args = parse_args()
722776

723777
if args.transport == "http":
724-
# host must be passed explicitly: the SDK runner defaults to 127.0.0.1,
725-
# but Cloud Run requires binding 0.0.0.0. streamable_http_path defaults
726-
# to "/mcp" (matches the 1.x mount) and max_request_body_size to 4 MiB.
727-
#
728-
# stateless_http holds no per-session state in instance memory. The
729-
# service runs multiple Cloud Run instances behind a global load
730-
# balancer with no session affinity, so a session minted by initialize
731-
# on one instance is rejected with 404 "Session not found" when a
732-
# follow-up request (e.g. notifications/initialized) lands on another
733-
# (CUS-1340). The docs tools are read-only with no server-initiated
734-
# notifications, so holding no shared session state has no downside.
735-
# Statelessness also retires the SDK's per-session ceilings
736-
# (max_sessions, session_idle_timeout); throughput is now bounded by
737-
# Cloud Run per-instance concurrency instead.
738-
#
739-
# json_response returns each POST reply as a single application/json
740-
# body instead of a one-shot text/event-stream. These tools are
741-
# read-only and single-response, so nothing needs SSE framing, and plain
742-
# JSON is friendlier to the fronting load balancer and buffering proxies.
778+
# host must be passed explicitly: it defaults to 127.0.0.1, but Cloud
779+
# Run requires binding 0.0.0.0. This calls uvicorn the way the SDK's
780+
# server.run() does (host, port, log level), and uvicorn reads
781+
# FORWARDED_ALLOW_IPS from the environment (see serve-mcp-http.sh).
782+
# build_http_app() explains the transport settings.
743783
logger.info(
744-
"Starting HTTP transport with stateless_http=True, json_response=True (CUS-1340)"
784+
"Starting HTTP transport: stateless_http=True, json_response=True, "
785+
"GET /mcp returns 405 (CUS-1340, EXP-577)"
745786
)
746-
server.run(
747-
transport="streamable-http",
787+
uvicorn.run(
788+
build_http_app(args.host),
748789
host=args.host,
749790
port=args.port,
750-
stateless_http=True,
751-
json_response=True,
791+
log_level=server.settings.log_level.lower(),
752792
)
753793
else:
754794
server.run() # stdio

‎scripts/smoke-test-mcp.sh‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,11 +38,11 @@ fail() {
3838
}
3939

4040
# The MCP initialize request, reused as both the liveness probe and the
41-
# stateless assertion below. It MUST be a POST: POST /mcp is a request-response
42-
# cycle in every transport mode, whereas GET /mcp in stateless mode opens a
43-
# long-lived SSE stream that never closes and would hang curl (and this whole
44-
# script) indefinitely. --max-time bounds any unexpected stall; callers pass -f
45-
# so a non-2xx response is a failure, not a vacuous pass.
41+
# stateless assertion below. It is a POST because POST /mcp is a
42+
# request-response cycle in every transport mode. GET /mcp returns 405 (Check 5),
43+
# but before that fix it opened an SSE stream that never closed. --max-time
44+
# bounds any unexpected stall; callers pass -f so a non-2xx response is a
45+
# failure, not a vacuous pass.
4646
INIT_BODY='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'
4747

4848
post_init() { # extra curl args in "$@"
@@ -107,3 +107,19 @@ if printf '%s' "$response" | grep -qi '^content-type:[[:space:]]*application/jso
107107
else
108108
fail "expected an application/json POST reply but the Content-Type differs (json_response regressed?)"
109109
fi
110+
111+
# --- Check 5: GET /mcp is refused, not held open as a stream (EXP-577) -------
112+
# In stateless mode the SDK accepted GET /mcp and held an empty SSE stream open
113+
# until Cloud Run's request timeout, holding a request slot the whole time.
114+
# Enough of those filled every slot and Cloud Run returned 429 to all callers.
115+
# The server must answer 405. A 200 here means the stream is back; curl's
116+
# --max-time ends it, and -w still reports the status. `|| true` keeps set -e
117+
# from exiting on that timeout before fail() can report it.
118+
echo "Check 5: GET /mcp returns 405 (no SSE stream)"
119+
status=$(curl -s --max-time 5 -o /dev/null -w '%{http_code}' \
120+
-H "Accept: text/event-stream" \
121+
-H "MCP-Protocol-Version: 2025-06-18" \
122+
"http://127.0.0.1:$HOST_PORT/mcp") || true
123+
[ "$status" = "405" ] \
124+
|| fail "GET /mcp returned $status, expected 405 (a 200 means the server opened an SSE stream: EXP-577)"
125+
echo " OK: GET /mcp returned 405"

‎scripts/test_mcp_transport.py‎

Lines changed: 116 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,126 @@
11
#!/usr/bin/env python3
2-
"""Regression coverage for the docs MCP server's HTTP transport (CUS-1340).
2+
"""Regression coverage for the docs MCP server's HTTP transport.
33
4-
The hosted server runs several Cloud Run instances behind a global load
5-
balancer with no session affinity. A stateful streamable-HTTP transport keys
6-
each session to the instance that handled `initialize`, so a follow-up request
7-
(for example `notifications/initialized`) landing on another instance was
8-
rejected with 404 "Session not found". Running the transport with
9-
`stateless_http=True` makes every request self-contained, which is safe here
10-
because the docs tools are read-only and the server sends no server-initiated
11-
notifications.
4+
These tests send real HTTP requests to the app that production serves, built
5+
by build_http_app() in mcp-server.py, and guard three settings:
126
13-
This asserts the production invocation keeps that flag. It reads the source
14-
rather than importing, because the `server.run(...)` call lives under
15-
`if __name__ == "__main__"` and would block on uvicorn if executed.
7+
- Stateless (CUS-1340). The hosted server runs several Cloud Run instances
8+
behind a global load balancer with no session affinity. A stateful transport
9+
keys each session to the instance that handled `initialize`, so a follow-up
10+
request landing on another instance was rejected with 404 "Session not
11+
found". A stateless server mints no Mcp-Session-Id.
12+
- JSON responses. Each POST reply is a single application/json body, not a
13+
one-shot text/event-stream.
14+
- No SSE stream (EXP-577). In stateless mode the SDK accepts GET /mcp and
15+
holds an empty stream open until Cloud Run's 300-second request timeout,
16+
holding one of the service's request slots the whole time. Enough of those
17+
filled every slot, and Cloud Run returned 429 to all callers. The server
18+
must answer GET with 405 instead.
19+
20+
TestClient is used as a context manager so it runs the app's lifespan, which
21+
starts the SDK's session manager; without it every POST fails with 500.
1622
1723
Run with:
1824
pytest scripts/test_mcp_transport.py -v
1925
"""
2026

21-
import ast
27+
import importlib.util
28+
import os
2229
from pathlib import Path
2330

24-
SERVER = Path(__file__).parent / "mcp-server.py"
25-
26-
27-
def streamable_http_run_calls(tree):
28-
"""Every `.run(transport="streamable-http", ...)` call in the module."""
29-
calls = []
30-
for node in ast.walk(tree):
31-
if not isinstance(node, ast.Call):
32-
continue
33-
transport = next(
34-
(kw.value for kw in node.keywords if kw.arg == "transport"), None
35-
)
36-
if isinstance(transport, ast.Constant) and transport.value == "streamable-http":
37-
calls.append(node)
38-
return calls
39-
40-
41-
def test_http_transport_runs_stateless():
42-
"""The streamable-HTTP server must run stateless, or CUS-1340 regresses."""
43-
tree = ast.parse(SERVER.read_text(encoding="utf-8"))
44-
calls = streamable_http_run_calls(tree)
45-
assert calls, "expected a streamable-http server.run() call"
46-
for call in calls:
47-
flag = next(
48-
(kw.value for kw in call.keywords if kw.arg == "stateless_http"), None
49-
)
50-
assert flag is not None, (
51-
"stateless_http kwarg missing from the streamable-http run() call "
52-
"(CUS-1340): stateful sessions break across unaffinitized Cloud "
53-
"Run instances"
54-
)
55-
# `is True` is deliberate: it rejects truthy-but-not-True literals such
56-
# as stateless_http=1, which the SDK would not treat as the boolean flag.
57-
assert isinstance(flag, ast.Constant) and flag.value is True, (
58-
"stateless_http must be the literal True, not a falsy or non-True "
59-
"value (CUS-1340)"
60-
)
31+
import pytest
32+
from starlette.testclient import TestClient
33+
34+
35+
def load_server_module():
36+
"""Import scripts/mcp-server.py, whose filename is not a valid module name.
37+
38+
The module indexes DOCS_PATH at import time. Point it at paths that do not
39+
exist so the import stays cheap; these tests need no documentation content.
40+
"""
41+
os.environ["DOCS_PATH"] = "/nonexistent/docs.md"
42+
os.environ["CATALOG_PATH"] = "/nonexistent/catalog.json"
43+
44+
spec = importlib.util.spec_from_file_location(
45+
"mcp_server_transport_under_test", Path(__file__).parent / "mcp-server.py"
46+
)
47+
module = importlib.util.module_from_spec(spec)
48+
spec.loader.exec_module(module)
49+
return module
50+
51+
52+
mcp_server = load_server_module()
53+
54+
# The Envoy AI Gateway sends this protocol version, and clients on any 2025
55+
# version reach the SDK path that opened the stream.
56+
PROTOCOL_VERSION = "2025-06-18"
57+
58+
POST_HEADERS = {
59+
"Accept": "application/json, text/event-stream",
60+
"Content-Type": "application/json",
61+
}
62+
63+
INITIALIZE = {
64+
"jsonrpc": "2.0",
65+
"id": 1,
66+
"method": "initialize",
67+
"params": {
68+
"protocolVersion": PROTOCOL_VERSION,
69+
"capabilities": {},
70+
"clientInfo": {"name": "transport-test", "version": "0"},
71+
},
72+
}
73+
74+
75+
@pytest.fixture(scope="module")
76+
def client():
77+
# Nothing binds here. The test passes production's host so the SDK picks
78+
# the same transport-security settings; a localhost host would turn on DNS
79+
# rebinding protection, which production doesn't run with.
80+
with TestClient(mcp_server.build_http_app("0.0.0.0")) as test_client: # nosec B104
81+
yield test_client
82+
83+
84+
@pytest.mark.parametrize(
85+
"headers",
86+
[
87+
{"Accept": "text/event-stream", "MCP-Protocol-Version": PROTOCOL_VERSION},
88+
{"Accept": "text/event-stream"},
89+
],
90+
ids=["with-protocol-version", "without-protocol-version"],
91+
)
92+
# If the 405 route regresses, the GET opens a stream that never ends and
93+
# TestClient waits forever for its body. The timeout (pytest-timeout) turns
94+
# that hang into a failure.
95+
@pytest.mark.timeout(10)
96+
def test_get_is_refused_with_405(client, headers):
97+
"""GET /mcp must not open an SSE stream (EXP-577)."""
98+
response = client.get("/mcp", headers=headers)
99+
assert response.status_code == 405
100+
assert response.headers["allow"] == "POST"
101+
102+
103+
def test_initialize_is_stateless_and_json(client):
104+
"""POST initialize still works, mints no session, and replies in JSON."""
105+
response = client.post("/mcp", headers=POST_HEADERS, json=INITIALIZE)
106+
assert response.status_code == 200
107+
assert response.headers["content-type"].startswith("application/json")
108+
# A JSON-RPC error also comes back as HTTP 200, so check for a result
109+
# before trusting the absent session id.
110+
assert "result" in response.json()
111+
assert "mcp-session-id" not in response.headers, (
112+
"stateless mode expected but the server minted an Mcp-Session-Id "
113+
"(CUS-1340): stateful sessions break across unaffinitized Cloud Run "
114+
"instances"
115+
)
116+
117+
118+
def test_tools_list_works_without_a_session(client):
119+
"""A follow-up request needs no session, so any instance can serve it."""
120+
response = client.post(
121+
"/mcp",
122+
headers={**POST_HEADERS, "MCP-Protocol-Version": PROTOCOL_VERSION},
123+
json={"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
124+
)
125+
assert response.status_code == 200
126+
assert response.json()["result"]["tools"]

0 commit comments

Comments
 (0)