Skip to content

Commit 5c03112

Browse files
committed
Stop a non-MCP response from looking like a silent server
The report was that connecting GitHub's MCP server timed out after 60s with "it accepted the connection and then went quiet", while the gateway log showed the POST completing normally. Both were true: the POST completed because it returned the timeout, and the timeout was wrong about what had happened. Two things were missing, and the first one hid the second. Every MCP test ran over stdio. The HTTP branch of _open_transport — the one GitHub, DeepWiki, Context7, Sentry and Stripe all use — had never been executed by any test, so "does the platform connect to an HTTP MCP server" had no answer in the suite, and for some servers the answer was no. tests/test_mcp_http.py now runs against two real servers: FastMCP over streamable HTTP, and a hand-written one shaped like GitHub's, which refuses the optional server-to-client GET stream with 405. FastMCP always offers that stream, so it could never have caught this alone. A response that is not MCP hung forever. Against a server answering 200 OK with text/html, the old code gave the same message and the same 15s as a genuinely silent server — and it was wrong, because that server replied instantly. The mechanism is in the client library: an unusable content type is reported by sending a ValueError into the read stream, and ClientSession's default message handler is a no-op checkpoint that drops it. The pending initialize() is never answered and never fails; it waits. A proxy's login page was therefore indistinguishable from silence. A message_handler that fails the connection turns it into an immediate, accurate error naming the content type. Also split the handshake from the tool listing, each with its own share of one budget, because a stall in the second is a known upstream defect (modelcontextprotocol/python-sdk#1941: servers that decline the GET stream can stall the client on the next request) and a stall in the first is not. Those deserve opposite advice — "your URL is wrong" versus "your setup is fine, raise CWAP_MCP_TIMEOUT". We are on the latest SDK, 1.28.1, so there is no fixed release to take. A phase error is raised inside anyio's task group and comes back boxed, so the old wrapper re-explained it and named the URL twice. _failure now unwraps what we already said rather than saying something vaguer on top of it. Not run: the PostgreSQL parity suite — Postgres is not up in this container and process control is unavailable. This diff touches mcp_connect, tests and docs, and no SQL. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_014wARiGvLpL9UaHJADdbAjF
1 parent b72cd71 commit 5c03112

8 files changed

Lines changed: 718 additions & 23 deletions

File tree

‎.env.example‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -134,9 +134,14 @@
134134
# CWAP_MCP_CONNECT_TIMEOUT=10 reaching the host at all. Exceeding this means
135135
# the URL is wrong or this deployment has no
136136
# egress — waiting longer will not help.
137-
# CWAP_MCP_TIMEOUT=60 the handshake, once the host has answered.
138-
# Raise it for a server behind a TLS-inspecting
139-
# proxy, or one that cold-starts.
137+
# CWAP_MCP_TIMEOUT=60 the handshake and the tool listing, once the
138+
# host has answered. Raise it for a server behind
139+
# a TLS-inspecting proxy, one that cold-starts, or
140+
# one that declines the optional server-to-client
141+
# stream — GitHub's does, and that can stall the
142+
# MCP client library after the handshake
143+
# (modelcontextprotocol/python-sdk#1941). The
144+
# error names which of the two stalled.
140145
# CWAP_MCP_CALL_TIMEOUT=120 one tool call. A search across a large
141146
# organisation is not a hung server.
142147

‎README.md‎

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -347,12 +347,28 @@ node does and passes the same two-phase gate, so a redelivered step cannot open
347347
two pull requests. Tools a server marks read-only are exempt — reading a
348348
repository is not a side effect.
349349

350-
**When a connection fails, the error says which kind of failure it was.**
351-
Reaching the host is bounded separately (`CWAP_MCP_CONNECT_TIMEOUT`, 10s) from
352-
waiting for it to answer (`CWAP_MCP_TIMEOUT`, 60s), because those have different
353-
remedies: an unreachable host means the URL is wrong or the deployment has no
354-
egress, and waiting longer will never help; a server that accepted the
355-
connection and went quiet is the one worth waiting for.
350+
**When a connection fails, the error says which kind of failure it was.** One
351+
timeout covering everything reported four different problems with one sentence,
352+
and none of the four remedies is the same:
353+
354+
| What happened | What it says | What to do |
355+
| --- | --- | --- |
356+
| The host never answers a SYN | *could not reach the host* (10s) | Fix the URL, or the deployment's egress |
357+
| It answers with a page, not MCP | *that URL answered, but not with MCP* | It is a login page, a proxy, or the wrong URL |
358+
| The handshake stalls | *stopped responding while completing the MCP handshake* | Probably not an MCP endpoint; or raise `CWAP_MCP_TIMEOUT` |
359+
| The handshake works, listing stalls | *stopped responding while listing its tools* | Your setup is fine — see below |
360+
361+
That last row is a known defect in the MCP client library rather than anything
362+
about your server ([python-sdk#1941](https://github.com/modelcontextprotocol/python-sdk/issues/1941)):
363+
a server that declines the *optional* server-to-client stream — GitHub's does,
364+
with a `405` — can stall the client on the request after the handshake. Raising
365+
`CWAP_MCP_TIMEOUT` is the workaround, and the error says so rather than leaving
366+
someone re-checking a URL that was never wrong.
367+
368+
An endpoint that replies `200 OK` with an HTML page is worth calling out
369+
separately: the client library reports that by posting an error into a stream
370+
nobody reads, so the request waits forever without ever failing. That is why a
371+
proxy's login page used to look exactly like a server that had gone silent.
356372

357373
---
358374

‎docs/architecture.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -546,6 +546,51 @@ deployment reach" as well as an allow-list does, in a reviewed file rather than
546546
in a text box. An HTTP *node* gets no exemption at all, an unlisted MCP host is
547547
gated exactly as before, and `CWAP_MCP_DIRECTORY=off` removes the exemption.
548548

549+
### An MCP connection fails in four distinguishable ways
550+
551+
`mcp_connect/client.py` bounds a connection with more than one deadline, which
552+
is worth explaining because a single one looks simpler and was actively
553+
misleading.
554+
555+
```
556+
reach the host REACH_TIMEOUT (10s) → could not reach the host
557+
│ (URL, DNS, or egress)
558+
▼
559+
answer with MCP (no deadline — it → that URL answered, but not
560+
│ either does or does with MCP (login page? proxy?)
561+
│ not)
562+
▼
563+
handshake ┐ → stopped responding while
564+
│ ├ CONNECT_TIMEOUT (60s) completing the handshake
565+
▼ │ shared between them
566+
list tools ┘ → stopped responding while
567+
listing its tools
568+
```
569+
570+
Every deadline sits strictly inside the next one out. When the outer wall was
571+
equal to the SDK's own 30s default, the two fired together and the vaguer
572+
message won — so a host that could not be reached and a server that had gone
573+
quiet produced the same sentence after the same thirty seconds.
574+
575+
The two content faults are the interesting ones, because neither is a timeout:
576+
577+
* **Not MCP at all.** The SDK reports an unusable content type by *sending a
578+
`ValueError` into the read stream*, and `ClientSession`'s default message
579+
handler discards it. The pending request is never answered and never fails —
580+
it waits. Passing a `message_handler` that fails the connection is what turns
581+
that permanent wait into an immediate, accurate error.
582+
* **A stall after the handshake.** A server may decline the optional
583+
server-to-client GET stream; GitHub's answers `405`. That is spec-legal, and
584+
it can stall the client library on the *next* request
585+
([python-sdk#1941](https://github.com/modelcontextprotocol/python-sdk/issues/1941)).
586+
The platform cannot fix the library, but it can tell the difference between
587+
"your URL is wrong" and "your setup is fine and this is a known upstream
588+
defect" — which are opposite instructions to give somebody.
589+
590+
`tests/test_mcp_http.py` runs against two real servers for this: one that offers
591+
the GET stream and one that refuses it. Until it existed, every MCP test used
592+
stdio, so the transport every hosted server actually uses had no coverage at all.
593+
549594
### Schema growth
550595

551596
`create_all` only creates whole tables, so a release that adds a column to an

‎services/mcp_connect/client.py‎

Lines changed: 160 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -60,13 +60,22 @@ def _seconds(name: str, default: float) -> float:
6060
#: going to.
6161
REACH_TIMEOUT = _seconds("CWAP_MCP_CONNECT_TIMEOUT", 10.0)
6262

63-
#: Added to the transport's own deadline to get the outer one. The outer wall
64-
#: must fire *after* the transport, or it pre-empts a specific, actionable error
65-
#: ("the connection timed out") with a generic one ("did not respond") — which
66-
#: is precisely what a blanket timeout equal to the SDK's default did.
63+
#: Added to an inner deadline to get the outer one. Every wall in this module
64+
#: must fire *after* the thing it is backstopping, or it pre-empts a specific,
65+
#: actionable error with a generic one — which is precisely what a blanket
66+
#: timeout equal to the SDK's own default did.
6767
GRACE = 10.0
6868

6969

70+
def connect_wall() -> float:
71+
"""The outer deadline for opening a connection.
72+
73+
Above `CONNECT_TIMEOUT`, which is what the two phases inside share, so a
74+
phase that stalls gets to say which phase it was before this fires.
75+
"""
76+
return CONNECT_TIMEOUT + GRACE
77+
78+
7079
class MCPError(RuntimeError):
7180
"""A server could not be reached, or a tool call failed."""
7281

@@ -90,6 +99,60 @@ class MCPError(RuntimeError):
9099
}
91100

92101

102+
#: Faults the transport describes in its own vocabulary, and what they mean to
103+
#: whoever typed the URL. Matched as substrings of the SDK's own message, and
104+
#: the SDK's wording is kept inside the explanation rather than replaced — a
105+
#: user pasting an error into a search engine should still find the library.
106+
_INTERPRETATIONS: tuple[tuple[str, str], ...] = (
107+
(
108+
"unexpected content type",
109+
"that URL answered, but not with MCP ({detail}). An MCP endpoint replies "
110+
"as JSON or as an event stream; HTML usually means a login page, a proxy "
111+
"sitting in front of the host, or simply a URL that is not an MCP endpoint",
112+
),
113+
(
114+
"session terminated",
115+
"the server rejected the session for that URL. Check the path — this is "
116+
"what a 404 looks like once the protocol has started",
117+
),
118+
)
119+
120+
121+
def _interpret(error: BaseException) -> str:
122+
"""Say what one fault means, keeping whatever the transport said about it.
123+
124+
The single place a raw exception becomes a sentence, whether it arrived by
125+
being raised or by being posted into the read stream. Those are two routes
126+
for the same faults, and giving them two vocabularies would mean a 404
127+
reading one way during the handshake and another way afterwards.
128+
"""
129+
name = type(error).__name__
130+
detail = str(error).strip() or _SILENT_FAULTS.get(name) or name
131+
lowered = detail.lower()
132+
for marker, template in _INTERPRETATIONS:
133+
if marker in lowered:
134+
return template.format(detail=detail)
135+
return detail
136+
137+
138+
def already_explained(exc: BaseException) -> MCPError | None:
139+
"""An `MCPError` this module raised, dug back out of whatever boxed it.
140+
141+
A phase timeout is raised inside the transport's anyio task group, so what
142+
reaches the caller is an ExceptionGroup rather than the error. Wrapping that
143+
in "could not connect to <url>: ..." produced a message naming the URL
144+
twice and burying the sentence that mattered. If we already said something
145+
useful, that is the message.
146+
"""
147+
if isinstance(exc, MCPError):
148+
return exc
149+
for inner in getattr(exc, "exceptions", None) or ():
150+
found = already_explained(inner)
151+
if found is not None:
152+
return found
153+
return None
154+
155+
93156
def explain(exc: BaseException) -> str:
94157
"""A message a person can act on, out of whatever the SDK raised.
95158
@@ -108,8 +171,7 @@ def walk(error: BaseException) -> None:
108171
for sub in inner:
109172
walk(sub)
110173
return
111-
name = type(error).__name__
112-
text = str(error).strip() or _SILENT_FAULTS.get(name) or name
174+
text = _interpret(error)
113175
if text not in leaves:
114176
leaves.append(text)
115177

@@ -118,6 +180,13 @@ def walk(error: BaseException) -> None:
118180
return "; ".join(leaves[:3]) or f"{type(exc).__name__}"
119181

120182

183+
def _failure(exc: BaseException, config: MCPServerConfig) -> MCPError:
184+
"""The error to hand back after a connection attempt has come apart."""
185+
return already_explained(exc) or MCPError(
186+
f"could not connect to {_target(config)}: {explain(exc)}"
187+
)
188+
189+
121190
def _target(config: MCPServerConfig) -> str:
122191
"""What was being reached, for an error a person has to act on.
123192
@@ -241,11 +310,11 @@ def probe(self, config: MCPServerConfig, credentials: dict) -> list[MCPTool]:
241310
"""Connect, list tools, disconnect. Used to verify a server before saving."""
242311
assert_permitted(config)
243312
try:
244-
return _thread.submit(_probe(config, credentials), CONNECT_TIMEOUT)
313+
return _thread.submit(_probe(config, credentials), connect_wall())
245314
except (MCPError, MCPPolicyError):
246315
raise
247316
except BaseException as exc: # noqa: BLE001 - includes ExceptionGroup
248-
raise MCPError(f"could not connect to {_target(config)}: {explain(exc)}") from exc
317+
raise _failure(exc, config) from exc
249318

250319
def disconnect(self, server_id: str) -> None:
251320
with self._lock:
@@ -274,11 +343,11 @@ def _session_for(
274343

275344
assert_permitted(config)
276345
try:
277-
entry = _thread.submit(_connect(config, credentials), CONNECT_TIMEOUT)
346+
entry = _thread.submit(_connect(config, credentials), connect_wall())
278347
except MCPError:
279348
raise
280349
except BaseException as exc: # noqa: BLE001 - includes ExceptionGroup
281-
raise MCPError(f"could not connect to {_target(config)}: {explain(exc)}") from exc
350+
raise _failure(exc, config) from exc
282351

283352
with self._lock:
284353
# Another thread may have connected while this one was waiting; keep
@@ -290,6 +359,46 @@ def _session_for(
290359
return winner
291360

292361

362+
#: The two phases of opening a connection, and what a stall in each one means.
363+
#:
364+
#: Splitting them is not tidiness. A server that never completes the handshake
365+
#: and a server that completes it and then stalls listing its tools are
366+
#: different problems with different causes, and reporting both as "the MCP
367+
#: server did not respond" told a user neither which one they had nor that the
368+
#: second is a known defect in the client library rather than in their setup.
369+
HANDSHAKE = (
370+
"completing the MCP handshake",
371+
"The host answered, so the URL and the network are fine. A handshake that "
372+
"then stalls usually means the endpoint is not an MCP server, or a proxy is "
373+
"sitting between this deployment and it. If the server is merely slow, "
374+
"raise CWAP_MCP_TIMEOUT.",
375+
)
376+
LISTING = (
377+
"listing its tools",
378+
"The handshake succeeded, so the URL and the credential are both good. "
379+
"Servers that decline the optional server-to-client stream — GitHub's is "
380+
"one — can stall the MCP client library on the request after the handshake "
381+
"(modelcontextprotocol/python-sdk#1941). Raising CWAP_MCP_TIMEOUT gives it "
382+
"longer to get through.",
383+
)
384+
385+
386+
async def _phase(
387+
phase: tuple[str, str],
388+
awaitable: Any,
389+
budget: float,
390+
config: MCPServerConfig,
391+
) -> Any:
392+
"""Run one phase of the connection under its own share of the budget."""
393+
what, why = phase
394+
try:
395+
return await asyncio.wait_for(awaitable, max(budget, 1.0))
396+
except (TimeoutError, asyncio.TimeoutError) as exc:
397+
raise MCPError(
398+
f"{_target(config)} stopped responding while {what}. {why}"
399+
) from exc
400+
401+
293402
async def _own_connection(
294403
config: MCPServerConfig,
295404
credentials: dict,
@@ -304,12 +413,50 @@ async def _own_connection(
304413
"""
305414
from mcp import ClientSession # noqa: PLC0415
306415

416+
async def transport_fault(message: Any) -> None:
417+
"""Fail the connection when the transport reports a fault as a message.
418+
419+
The SDK does not raise for everything that goes wrong. A response with
420+
an unusable content type — an HTML login page, a proxy's error page,
421+
a URL that is not an MCP endpoint at all — is reported by *sending a
422+
ValueError into the read stream*, which the default message handler
423+
drops on the floor. The `initialize()` call is still waiting for its
424+
response, and no response is ever coming, so the connection hangs until
425+
something outside kills it.
426+
427+
That is what "the MCP server did not respond" was hiding: a server that
428+
answered instantly with the wrong thing, described as one that said
429+
nothing at all. The information was there and nobody was listening.
430+
"""
431+
if not isinstance(message, Exception):
432+
return
433+
434+
detail = _interpret(message)
435+
logger.warning("MCP transport fault from %s: %s", _target(config), detail)
436+
if not ready.done():
437+
ready.set_exception(MCPError(detail))
438+
# Mid-session rather than during the handshake: the connection is no
439+
# longer trustworthy, so drop it and let the next call reconnect.
440+
stop.set()
441+
307442
try:
308443
async with AsyncExitStack() as stack:
309444
read, write = await _open_transport(stack, config, credentials)
310-
session = await stack.enter_async_context(ClientSession(read, write))
311-
await session.initialize()
312-
listing = await session.list_tools()
445+
session = await stack.enter_async_context(
446+
ClientSession(read, write, message_handler=transport_fault)
447+
)
448+
449+
# One budget for the whole connection, spent across two phases that
450+
# are timed separately. Which of the two stalled is the single most
451+
# useful thing an error can say here — see `_phase`.
452+
loop = asyncio.get_running_loop()
453+
deadline = loop.time() + CONNECT_TIMEOUT
454+
455+
await _phase(HANDSHAKE, session.initialize(), deadline - loop.time(), config)
456+
listing = await _phase(
457+
LISTING, session.list_tools(), deadline - loop.time(), config
458+
)
459+
313460
if not ready.done():
314461
ready.set_result((session, _to_tools(listing)))
315462
await stop.wait()

‎tests/mcp_fixture_http_server.py‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
"""The same fixture server, over streamable HTTP instead of stdio.
2+
3+
Every MCP test the platform had ran over stdio, so `_open_transport`'s HTTP
4+
branch — the one every hosted server in the directory actually uses — was
5+
never executed by anything. A user reporting that GitHub's server hung had no
6+
test that could confirm or deny the platform's side of it.
7+
8+
Launched as a subprocess on a port the caller picks, so a test can talk to a
9+
real streamable-HTTP MCP server: real handshake, real session id, real
10+
`tools/list` over the wire.
11+
"""
12+
13+
from __future__ import annotations
14+
15+
import sys
16+
17+
from mcp.server.fastmcp import FastMCP
18+
19+
20+
def build(slow_tool_seconds: float = 0.0) -> FastMCP:
21+
server = FastMCP("fixture-http-host")
22+
23+
@server.tool(annotations={"readOnlyHint": True})
24+
def read_file(path: str) -> str:
25+
"""Read a file from the repository."""
26+
return f"contents of {path}"
27+
28+
@server.tool()
29+
def create_pull_request(title: str, body: str) -> str:
30+
"""Open a pull request."""
31+
return f"opened '{title}'"
32+
33+
return server
34+
35+
36+
if __name__ == "__main__":
37+
port = int(sys.argv[1])
38+
app = build()
39+
app.settings.host = "127.0.0.1"
40+
app.settings.port = port
41+
# `log_level` down so a failing test's output is the assertion, not uvicorn.
42+
app.settings.log_level = "warning"
43+
app.run(transport="streamable-http")

0 commit comments

Comments
 (0)