Skip to content

The fastest, litest AI Gateway. Rust core with Python SDK. Call 100+ LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]

fix(mcp): surface upstream HTTP status when a failed POST closes the session (#47569)

Yassin Kortam6bc1b2b3e5b8
diff --git a/litellm/experimental_mcp_client/client.py b/litellm/experimental_mcp_client/client.py
index ed6d89397a0..85075b52b71 100644
--- a/litellm/experimental_mcp_client/client.py
+++ b/litellm/experimental_mcp_client/client.py
@@ -292,6 +292,7 @@ class _MCPResponseStream(httpx2.AsyncByteStream):
class _MCPHTTPClient(httpx2.AsyncClient):
cleanup_scope: anyio.CancelScope | None = None
cleanup_errors: tuple[Exception, ...] = ()
+ post_failure: asyncio.Future[Exception] | None = None
def _record_cleanup_error(self, error: Exception) -> None:
if self.cleanup_scope is not None and self.cleanup_scope.shield:
@@ -319,7 +320,12 @@ class _MCPHTTPClient(httpx2.AsyncClient):
response: Final = await super().send(request, stream=stream, auth=auth, follow_redirects=follow_redirects)
if request.method == "POST" and response.is_error and response.status_code != 404:
await response.aclose()
- response.raise_for_status()
+ try:
+ response.raise_for_status()
+ except httpx2.HTTPStatusError as error:
+ if self.post_failure is not None and not self.post_failure.done():
+ self.post_failure.set_result(error)
+ raise
if stream:
response.stream = _MCPResponseStream(
cast(httpx2.AsyncByteStream, response.stream), self._record_cleanup_error
@@ -757,6 +763,8 @@ class MCPClient:
read_stream: Final = transport[0]
write_stream: Final = transport[1]
stream_error: Final[asyncio.Future[Exception]] = asyncio.get_running_loop().create_future()
+ if isinstance(http_client, _MCPHTTPClient):
+ http_client.post_failure = stream_error # rebind-ok: operation-scoped stream error
_notify_stream_error(on_stream_error, stream_error)
session_kwargs: Final = (
@@ -823,6 +831,7 @@ class MCPClient:
if isinstance(http_client, _MCPHTTPClient):
http_client.cleanup_errors = ()
http_client.cleanup_scope = None
+ http_client.post_failure = None # rebind-ok: clear operation-scoped stream error
await anyio.lowlevel.checkpoint_if_cancelled()
if cleanup_scope.cancel_called:
raise (
diff --git a/tests/unit/experimental_mcp_client/test_mcp_client.py b/tests/unit/experimental_mcp_client/test_mcp_client.py
index 6ea76a0a8a7..ba7786f8cd5 100644
--- a/tests/unit/experimental_mcp_client/test_mcp_client.py
+++ b/tests/unit/experimental_mcp_client/test_mcp_client.py
@@ -34,6 +34,7 @@ from mcp.types import (
InitializeResult,
JSONRPCError,
JSONRPCMessage,
+ JSONRPCNotification,
JSONRPCRequest,
JSONRPCResponse,
LoggingMessageNotificationParams,
@@ -61,8 +62,10 @@ from litellm.experimental_mcp_client.client import (
strip_auth_scheme,
)
from litellm.proxy._experimental.mcp_server.faults.list_outcomes import (
+ ServerListFault,
classify_list_exception,
list_fault_http_status,
+ upstream_rate_limit,
)
from litellm.proxy._experimental.mcp_server.mcp_server_manager import (
_format_byok_openapi_auth_header,
@@ -305,6 +308,36 @@ class _MockTransportClient(MCPClient):
return streamable_http_client(self.server_url, http_client=http_client), http_client
+def _post_status_responder(failure_method: str, status_code: int) -> Callable[[httpx2.Request], httpx2.Response]:
+ def respond(request: httpx2.Request) -> httpx2.Response:
+ if request.method != "POST":
+ return httpx2.Response(200)
+ payload: Final = _JSONRPC_MESSAGE_ADAPTER.validate_json(request.content)
+ assert isinstance(payload, (JSONRPCRequest, JSONRPCNotification))
+ if payload.method == "initialize":
+ assert isinstance(payload, JSONRPCRequest)
+ return httpx2.Response(
+ 200,
+ json={
+ "jsonrpc": "2.0",
+ "id": payload.id,
+ "result": {
+ "protocolVersion": LATEST_HANDSHAKE_VERSION,
+ "capabilities": {"tools": {}},
+ "serverInfo": {"name": "status", "version": "1"},
+ },
+ },
+ )
+ if payload.method == failure_method:
+ return httpx2.Response(status_code, headers={"Retry-After": "7"})
+ if payload.method == "tools/list":
+ assert isinstance(payload, JSONRPCRequest)
+ return httpx2.Response(200, json={"jsonrpc": "2.0", "id": payload.id, "result": {"tools": []}})
+ return httpx2.Response(202)
+
+ return respond
+
+
class _FakeExceptionGroup(Exception):
"""Duck-typed stand-in for an anyio/builtin ExceptionGroup.
@@ -1862,6 +1895,32 @@ async def test_http_response_handler_preserves_success_and_http_errors(status_co
assert caught.value.response.status_code == status_code
+ "failure_method,status_code",
+ [
+ ("notifications/initialized", 429),
+ ("notifications/initialized", 503),
+ ("tools/list", 429),
+ ],
+)
+async def test_list_tools_classifies_upstream_status_for_post_failures(failure_method: str, status_code: int) -> None:
+ client: Final = _MockTransportClient(
+ _post_status_responder(failure_method, status_code),
+ server_url="https://example.com/mcp",
+ )
+ with pytest.raises(httpx2.HTTPStatusError) as caught:
+ await client.list_tools(raise_on_error=True)
+
+ assert classify_list_exception(caught.value) == ServerListFault(tag="upstream_error", status_code=status_code)
+ rate_limit: Final = upstream_rate_limit(caught.value)
+ if status_code == 429:
+ assert rate_limit is not None
+ assert rate_limit.retry_after_seconds == 7
+ else:
+ assert rate_limit is None
+
+
@pytest.mark.asyncio
async def test_http_status_check_allows_auth_refresh_before_rejecting() -> None:
from litellm.proxy._experimental.mcp_server.outbound_credentials.client_credentials import (
@@ -4388,6 +4447,35 @@ async def test_persistent_tool_call_preserves_upstream_http_status_error() -> No
await asyncio.wait_for(session.wait_closed(), 5)
[email protected]("status_code", [429, 503])
+async def test_persistent_tool_call_classifies_initialized_notification_status(status_code: int) -> None:
+ client: Final = _MockTransportClient(
+ _post_status_responder("notifications/initialized", status_code),
+ server_url="https://example.com/mcp",
+ )
+ session: Final = client.open_persistent_session()
+ try:
+ with pytest.raises(httpx2.HTTPStatusError) as caught:
+ await client.call_tool(
+ CallToolRequestParams(name="protected_tool", arguments={}),
+ raise_on_error=True,
+ persistent_session=session,
+ )
+
+ assert classify_list_exception(caught.value) == ServerListFault(tag="upstream_error", status_code=status_code)
+ rate_limit: Final = upstream_rate_limit(caught.value)
+ if status_code == 429:
+ assert rate_limit is not None
+ assert rate_limit.retry_after_seconds == 7
+ else:
+ assert rate_limit is None
+ finally:
+ if not session.closed:
+ session.close()
+ await asyncio.wait_for(session.wait_closed(), 5)
+
+
@pytest.mark.asyncio
async def test_persistent_session_remaps_stream_error_over_mcp_error() -> None:
app: Final = _stateful_upstream()