Skip to content

Commit 0bf4ff3

Browse files
fix(mcp): keep the Streamable HTTP session usable after a 5xx
With MCP Python SDK v2, the response hook that `MCPServerStreamableHttp` installs on its HTTP client called `raise_for_status()` for every 5xx. The hook runs inside the MCP transport task group, so a single transient 5xx on any request tore down the shared transport. Every later `call_tool()` and `list_tools()` then failed with `MCPError: Connection closed` until `cleanup()` and `connect()`. A 5xx on the `notifications/initialized` notification to a legacy-protocol server did the same while `connect()` still reported success. The hook now skips the raise only for a post-handshake MCP transport message, meaning a request body that is a JSON-RPC message other than `server/discover` and `initialize`. MCP v2 fails such a message on its own, so the session stays usable and `max_retry_attempts` retries on it. Every other response keeps the existing HTTP error mapping. A handshake 5xx still fails `connect()` with the HTTP status, so a failed discovery probe is not mistaken for a legacy server. OAuth auth-flow sub-requests such as token and registration requests are not transport messages, so their failures also stay on that path instead of reaching MCP's OAuth exceptions, which carry the authorization server's response body.
1 parent d59fdb8 commit 0bf4ff3

2 files changed

Lines changed: 255 additions & 21 deletions

File tree

‎src/agents/mcp/server.py‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -355,15 +355,29 @@ def create_client(
355355
return create_client
356356

357357

358-
def _jsonrpc_request_method(request: Any) -> str | None:
358+
def _jsonrpc_message_payload(request: Any) -> dict[str, Any] | None:
359+
"""Return the JSON-RPC message this request carries, or `None` for any other request."""
359360
try:
360361
payload = json.loads(request.content)
361362
except (TypeError, ValueError, UnicodeDecodeError):
362363
return None
363-
if not isinstance(payload, dict):
364+
if not isinstance(payload, dict) or "jsonrpc" not in payload:
364365
return None
366+
return payload
367+
368+
369+
_V2_HANDSHAKE_REQUEST_METHODS = frozenset({"server/discover", "initialize"})
370+
371+
372+
def _is_v2_post_handshake_message(payload: dict[str, Any] | None) -> bool:
373+
"""Whether MCP v2 owns the failure handling for this transport message."""
374+
if payload is None:
375+
return False
365376
method = payload.get("method")
366-
return method if isinstance(method, str) else None
377+
if method is None:
378+
# A response the client sends for a server-initiated request.
379+
return True
380+
return isinstance(method, str) and method not in _V2_HANDSHAKE_REQUEST_METHODS
367381

368382

369383
def _configure_v2_session_id_hook(
@@ -372,12 +386,17 @@ def _configure_v2_session_id_hook(
372386
on_session_id: Callable[[str], None] | None,
373387
) -> None:
374388
async def handle_response(response: Any) -> None:
375-
if response.status_code >= 500:
389+
payload = _jsonrpc_message_payload(response.request)
390+
if response.status_code >= 500 and not _is_v2_post_handshake_message(payload):
391+
# MCP v2 fails a post-handshake transport message on its own, so raising here would
392+
# tear down the transport that every later request shares. Every other response keeps
393+
# the existing HTTP error mapping: a handshake 5xx must fail the connection instead of
394+
# looking like a legacy server, and OAuth sub-request failures stay on that path too.
376395
response.raise_for_status()
377-
method = _jsonrpc_request_method(response.request)
378396
if (
379397
on_session_id is not None
380-
and method == "initialize"
398+
and payload is not None
399+
and payload.get("method") == "initialize"
381400
and 200 <= response.status_code < 300
382401
):
383402
session_id = response.headers.get("mcp-session-id")

‎tests/mcp/test_mcp_v2_http.py‎

Lines changed: 230 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
import asyncio
44
import json
55
import socket
6+
import traceback
67
from typing import Any
78

89
import httpx
@@ -14,7 +15,7 @@
1415

1516
from agents.exceptions import UserError
1617
from agents.mcp import MCPServerStreamableHttp
17-
from agents.mcp._compat import MCP_V2, create_v2_client
18+
from agents.mcp._compat import MCP_V2, MCPError, create_v2_client
1819
from agents.mcp.server import (
1920
_configure_v2_session_id_hook,
2021
_create_default_streamable_http_client,
@@ -103,6 +104,30 @@ def handle_request(request):
103104
await client.aclose()
104105

105106

107+
@pytest.mark.asyncio
108+
async def test_v2_response_hook_raises_5xx_for_a_request_that_is_not_a_transport_message():
109+
def handle_request(request):
110+
return httpx2.Response(503, request=request)
111+
112+
client = httpx2.AsyncClient(transport=httpx2.MockTransport(handle_request))
113+
_configure_v2_session_id_hook(client, on_session_id=None)
114+
115+
# An OAuth dynamic client registration body is JSON, but it is not a transport message, so
116+
# its failures stay on the HTTP error path instead of MCP's body-bearing OAuth exceptions.
117+
with pytest.raises(httpx2.HTTPStatusError):
118+
await client.post(
119+
"https://example.test/register",
120+
content=json.dumps(
121+
{
122+
"client_name": "example",
123+
"redirect_uris": ["https://example.test/callback"],
124+
}
125+
),
126+
)
127+
128+
await client.aclose()
129+
130+
106131
def test_v2_rejects_initialized_notification_tolerance_before_connecting():
107132
server = MCPServerStreamableHttp(
108133
params={
@@ -261,34 +286,68 @@ async def handler(request):
261286
assert all(client.is_closed for client in clients)
262287

263288

264-
@pytest.mark.asyncio
265-
async def test_v2_streamable_http_retries_5xx_on_isolated_session():
266-
clients: list[Any] = []
267-
observed_statuses: list[int] = []
289+
def _first_tool_call_returns_503_factory(clients: list[Any], tool_call_statuses: list[int]):
290+
"""Build clients whose server answers only the first `tools/call` with HTTP 503."""
268291

269292
def factory(headers=None, timeout=None, auth=None):
270-
tool_status_code = 503 if not clients else None
271-
272293
async def handler(request):
273-
return _v2_response_for_request(request, tool_status_code=tool_status_code)
274-
275-
async def observe_response(response):
276-
observed_statuses.append(response.status_code)
294+
payload = json.loads(request.content) if request.content else {}
295+
if payload.get("method") == "tools/call":
296+
status_code = 503 if not tool_call_statuses else 200
297+
tool_call_statuses.append(status_code)
298+
if status_code == 503:
299+
return _v2_response_for_request(request, tool_status_code=503)
300+
return _v2_response_for_request(request)
277301

278302
client = httpx2.AsyncClient(
279303
transport=httpx2.MockTransport(handler),
280304
headers=headers,
281305
timeout=timeout,
282306
auth=auth,
283-
event_hooks={"response": [observe_response]},
284307
)
285308
clients.append(client)
286309
return client
287310

311+
return factory
312+
313+
314+
@pytest.mark.asyncio
315+
async def test_v2_streamable_http_5xx_fails_only_that_request():
316+
clients: list[Any] = []
317+
tool_call_statuses: list[int] = []
288318
server = MCPServerStreamableHttp(
289319
params={
290320
"url": "https://example.test/mcp",
291-
"httpx_client_factory": factory,
321+
"httpx_client_factory": _first_tool_call_returns_503_factory(
322+
clients, tool_call_statuses
323+
),
324+
},
325+
)
326+
327+
async with server:
328+
with pytest.raises(MCPError):
329+
await asyncio.wait_for(server.call_tool("test", {}), timeout=2)
330+
result = await asyncio.wait_for(server.call_tool("test", {}), timeout=2)
331+
tools = await asyncio.wait_for(server.list_tools(), timeout=2)
332+
333+
assert isinstance(result.content[0], TextContent)
334+
assert result.content[0].text == "ok"
335+
assert [tool.name for tool in tools] == ["test"]
336+
assert tool_call_statuses == [503, 200]
337+
assert len(clients) == 1
338+
assert all(client.is_closed for client in clients)
339+
340+
341+
@pytest.mark.asyncio
342+
async def test_v2_streamable_http_retries_5xx_on_shared_session():
343+
clients: list[Any] = []
344+
tool_call_statuses: list[int] = []
345+
server = MCPServerStreamableHttp(
346+
params={
347+
"url": "https://example.test/mcp",
348+
"httpx_client_factory": _first_tool_call_returns_503_factory(
349+
clients, tool_call_statuses
350+
),
292351
},
293352
max_retry_attempts=1,
294353
retry_backoff_seconds_base=0,
@@ -299,11 +358,167 @@ async def observe_response(response):
299358

300359
assert isinstance(result.content[0], TextContent)
301360
assert result.content[0].text == "ok"
302-
assert len(clients) == 2
303-
assert 503 in observed_statuses
361+
assert tool_call_statuses == [503, 200]
362+
assert len(clients) == 1
304363
assert all(client.is_closed for client in clients)
305364

306365

366+
@pytest.mark.asyncio
367+
async def test_v2_streamable_http_initialized_notification_5xx_keeps_session_usable():
368+
clients: list[Any] = []
369+
370+
def factory(headers=None, timeout=None, auth=None):
371+
async def handler(request):
372+
payload = json.loads(request.content) if request.content else {}
373+
if payload.get("method") == "notifications/initialized":
374+
return httpx2.Response(503, request=request)
375+
return _v2_response_for_request(request)
376+
377+
client = httpx2.AsyncClient(
378+
transport=httpx2.MockTransport(handler),
379+
headers=headers,
380+
timeout=timeout,
381+
auth=auth,
382+
)
383+
clients.append(client)
384+
return client
385+
386+
server = MCPServerStreamableHttp(
387+
params={
388+
"url": "https://example.test/mcp",
389+
"httpx_client_factory": factory,
390+
},
391+
)
392+
393+
async with server:
394+
result = await asyncio.wait_for(server.call_tool("test", {}), timeout=2)
395+
tools = await asyncio.wait_for(server.list_tools(), timeout=2)
396+
397+
assert isinstance(result.content[0], TextContent)
398+
assert result.content[0].text == "ok"
399+
assert [tool.name for tool in tools] == ["test"]
400+
assert len(clients) == 1
401+
402+
403+
@pytest.mark.asyncio
404+
async def test_v2_streamable_http_handshake_5xx_fails_connect_without_legacy_fallback():
405+
methods: list[str | None] = []
406+
407+
def factory(headers=None, timeout=None, auth=None):
408+
async def handler(request):
409+
payload = json.loads(request.content) if request.content else {}
410+
methods.append(payload.get("method"))
411+
if payload.get("method") == "server/discover":
412+
return httpx2.Response(503, request=request)
413+
return _v2_response_for_request(request)
414+
415+
return httpx2.AsyncClient(
416+
transport=httpx2.MockTransport(handler),
417+
headers=headers,
418+
timeout=timeout,
419+
auth=auth,
420+
)
421+
422+
server = MCPServerStreamableHttp(
423+
params={
424+
"url": "https://example.test/mcp",
425+
"httpx_client_factory": factory,
426+
},
427+
)
428+
429+
with pytest.raises(UserError, match="HTTP error 503"):
430+
await server.connect()
431+
432+
assert methods == ["server/discover"]
433+
assert server.session is None
434+
435+
436+
@pytest.mark.asyncio
437+
async def test_v2_streamable_http_oauth_subrequest_5xx_keeps_http_error_mapping():
438+
from mcp.client.auth.extensions.client_credentials import ClientCredentialsOAuthProvider
439+
440+
response_body_marker = "synthetic-authorization-server-body"
441+
442+
class _UnauthenticatedStorage:
443+
async def get_tokens(self):
444+
return None
445+
446+
async def set_tokens(self, tokens):
447+
return None
448+
449+
async def get_client_info(self):
450+
return None
451+
452+
async def set_client_info(self, client_information):
453+
return None
454+
455+
def factory(headers=None, timeout=None, auth=None):
456+
async def handler(request):
457+
path = request.url.path
458+
if path == "/token":
459+
return httpx2.Response(503, text=response_body_marker, request=request)
460+
if path.startswith("/.well-known/oauth-protected-resource"):
461+
return httpx2.Response(
462+
200,
463+
json={
464+
"resource": "https://example.test/mcp",
465+
"authorization_servers": ["https://example.test"],
466+
},
467+
request=request,
468+
)
469+
if path.startswith("/.well-known/oauth-authorization-server"):
470+
return httpx2.Response(
471+
200,
472+
json={
473+
"issuer": "https://example.test",
474+
"authorization_endpoint": "https://example.test/authorize",
475+
"token_endpoint": "https://example.test/token",
476+
"response_types_supported": ["code"],
477+
},
478+
request=request,
479+
)
480+
if "authorization" not in request.headers:
481+
return httpx2.Response(
482+
401,
483+
headers={
484+
"www-authenticate": (
485+
"Bearer resource_metadata="
486+
'"https://example.test/.well-known/oauth-protected-resource/mcp"'
487+
)
488+
},
489+
request=request,
490+
)
491+
return _v2_response_for_request(request)
492+
493+
return httpx2.AsyncClient(
494+
transport=httpx2.MockTransport(handler),
495+
headers=headers,
496+
timeout=timeout,
497+
auth=auth,
498+
)
499+
500+
server = MCPServerStreamableHttp(
501+
params={
502+
"url": "https://example.test/mcp",
503+
"auth": ClientCredentialsOAuthProvider(
504+
server_url="https://example.test/mcp",
505+
storage=_UnauthenticatedStorage(),
506+
client_id="placeholder-client-id",
507+
client_secret="placeholder-client-secret",
508+
),
509+
"httpx_client_factory": factory,
510+
},
511+
)
512+
513+
with pytest.raises(UserError, match="HTTP error 503") as exc_info:
514+
await server.connect()
515+
516+
error = exc_info.value
517+
rendered = "".join(traceback.format_exception(type(error), error, error.__traceback__))
518+
assert response_body_marker not in rendered
519+
assert server.session is None
520+
521+
307522
@pytest.mark.asyncio
308523
async def test_v2_connect_cancellation_stops_pending_client_owner(monkeypatch):
309524
client_entered = asyncio.Event()

0 commit comments

Comments
 (0)