diff --git a/docs/client/transports.md b/docs/client/transports.md index b41fe51348..e165d41f4a 100644 --- a/docs/client/transports.md +++ b/docs/client/transports.md @@ -48,6 +48,15 @@ environment variables or pass an explicit `verify=ssl_context` to your `httpx2.A (background in [`httpx` and `httpx-sse` replaced by `httpx2`](../migration.md#httpx-and-httpx-sse-replaced-by-httpx2)). +### Closing a legacy session + +When a legacy server assigns a session ID, exiting the client sends a `DELETE` request by default. +The transport shields that request from caller cancellation for up to five seconds, so a cancelled +operation still has a chance to release its server session without waiting indefinitely on cleanup. +If termination fails or times out, the server may retain the session until its idle timeout expires. +Pass `terminate_on_close=False` to `streamable_http_client` to leave the session open intentionally. +Modern connections have no legacy session to terminate. + ### Larger SSE events Pass `max_sse_event_size` when a server sends a large tool result or notification in one SSE event: diff --git a/src/mcp/client/streamable_http.py b/src/mcp/client/streamable_http.py index 053f1f10a9..a75e83ad6c 100644 --- a/src/mcp/client/streamable_http.py +++ b/src/mcp/client/streamable_http.py @@ -59,6 +59,7 @@ DEFAULT_RECONNECTION_DELAY_MS = 1000 # 1 second fallback when server doesn't provide retry MAX_RECONNECTION_ATTEMPTS = 2 # Max retry attempts before giving up DEFAULT_MAX_SSE_EVENT_SIZE = 1024 * 1024 +_SESSION_TERMINATION_TIMEOUT = 5.0 class StreamableHTTPError(Exception): @@ -705,7 +706,7 @@ async def terminate_session(self, client: httpx2.AsyncClient) -> None: logger.debug("Server does not allow session termination") elif response.status_code not in (200, 204): logger.warning(f"Session termination failed: {response.status_code}") # pragma: no cover - except Exception as exc: # pragma: no cover + except Exception as exc: logger.warning(f"Session termination failed: {exc}") @@ -732,6 +733,7 @@ async def streamable_http_client( client's `follow_redirects` setting is not consulted; the SDK's OAuth providers apply the same rule to the requests they make. terminate_on_close: If True, send a DELETE request to terminate the session when the context exits. + Termination is shielded from caller cancellation and bounded to five seconds. max_sse_event_size: Maximum bytes buffered for one SSE event. None disables the limit. JSON responses are not affected. @@ -788,6 +790,9 @@ def start_get_stream() -> None: yield read_stream, write_stream finally: if transport.session_id and terminate_on_close: - await transport.terminate_session(client) + # Caller cancellation must not abort cleanup, but a stalled + # endpoint must not keep the transport alive indefinitely. + with anyio.move_on_after(_SESSION_TERMINATION_TIMEOUT, shield=True): + await transport.terminate_session(client) tg.cancel_scope.cancel() await resync_tracer() diff --git a/tests/client/test_streamable_http.py b/tests/client/test_streamable_http.py index 9087394cd6..ab2918431a 100644 --- a/tests/client/test_streamable_http.py +++ b/tests/client/test_streamable_http.py @@ -8,11 +8,12 @@ import base64 import json from collections.abc import AsyncIterator, Callable, Mapping -from typing import Any +from typing import Any, Literal import anyio import httpx2 import pytest +from anyio.lowlevel import checkpoint from inline_snapshot import snapshot from mcp_types import ( CLIENT_CAPABILITIES_META_KEY, @@ -58,6 +59,134 @@ from tests.shared.test_dispatcher import Recorder, echo_handlers +@pytest.mark.anyio +@pytest.mark.parametrize( + ("cancel", "terminate_on_close"), + [("none", False), ("before", False), ("none", True), ("before", True), ("during", True)], +) +async def test_client_exit_terminates_the_legacy_session_even_when_cancelled( + cancel: Literal["none", "before", "during"], terminate_on_close: bool +) -> None: + """SDK-defined: terminate_on_close removes a legacy session even during caller cancellation. + + A request hook supplies a cancellable I/O checkpoint before DELETE reaches the server. + """ + session_ids: list[str] = [] + deleted: list[str] = [] + delete_started = anyio.Event() + cancellation_started = anyio.Event() + + async def cancel_during_delete(scope: anyio.CancelScope) -> None: + with anyio.fail_after(5): + await delete_started.wait() + scope.cancel() + cancellation_started.set() + + async def before_request(request: httpx2.Request) -> None: + if request.method == "DELETE": + if cancel == "during": + delete_started.set() + with anyio.fail_after(5): + await cancellation_started.wait() + await checkpoint() + + async def after_response(response: httpx2.Response) -> None: + if session_id := response.headers.get("mcp-session-id"): + session_ids.append(session_id) + if response.request.method == "DELETE": + assert response.status_code == 200 + deleted.append(response.request.headers["mcp-session-id"]) + + manager = StreamableHTTPSessionManager(app=Server("cleanup"), json_response=True) + app = Starlette(routes=[Mount("/mcp", app=manager.handle_request)]) + with anyio.fail_after(5): + async with ( + manager.run(), + httpx2.AsyncClient( + transport=StreamingASGITransport(app), + event_hooks={"request": [before_request], "response": [after_response]}, + ) as http, + ): + client = Client( + streamable_http_client( + "http://localhost/mcp/", http_client=http, terminate_on_close=terminate_on_close + ), + mode="legacy", + ) + async with anyio.create_task_group() as tasks: + with anyio.CancelScope() as scope: + # coverage.py misattributes context-manager arcs on cancellation. + async with client: # pragma: no branch + assert session_ids + if cancel == "before": + scope.cancel() + elif cancel == "during": + tasks.start_soon(cancel_during_delete, scope) + + session_id = session_ids[0] + probe = await http.post( + "http://localhost/mcp/", + headers={ + "mcp-session-id": session_id, + "mcp-protocol-version": "2025-11-25", + "accept": "application/json, text/event-stream", + }, + json={"jsonrpc": "2.0", "id": 99, "method": "ping"}, + ) + assert probe.status_code == (404 if terminate_on_close else 200) + assert deleted == ([session_id] if terminate_on_close else []) + if not terminate_on_close: + await http.delete("http://localhost/mcp/", headers={"mcp-session-id": session_id}) + + +@pytest.mark.anyio +@pytest.mark.parametrize("cancel", [False, True]) +@pytest.mark.parametrize("failure", ["timeout", "connection"]) +async def test_failed_session_delete_does_not_block_or_swallow_cancellation( + monkeypatch: pytest.MonkeyPatch, + cancel: bool, + failure: Literal["timeout", "connection"], +) -> None: + """SDK-defined: a stalled cleanup request cannot indefinitely shield caller cancellation.""" + monkeypatch.setattr("mcp.client.streamable_http._SESSION_TERMINATION_TIMEOUT", 0.01) + delete_started = anyio.Event() + delete_cancelled = anyio.Event() + never = anyio.Event() + + async def before_request(request: httpx2.Request) -> None: + if request.method == "DELETE": + delete_started.set() + if failure == "connection": + raise httpx2.ConnectError("Server unavailable", request=request) + try: + with anyio.fail_after(5): + await never.wait() + except anyio.get_cancelled_exc_class(): + delete_cancelled.set() + raise + + manager = StreamableHTTPSessionManager(app=Server("stalled-cleanup"), json_response=True) + app = Starlette(routes=[Mount("/mcp", app=manager.handle_request)]) + with anyio.fail_after(5): + async with ( + manager.run(), + httpx2.AsyncClient( + transport=StreamingASGITransport(app), event_hooks={"request": [before_request]} + ) as http, + ): + # coverage.py misattributes context-manager arcs on cancellation. + with anyio.CancelScope() as scope: # pragma: no branch + async with Client( # pragma: no branch + streamable_http_client("http://localhost/mcp/", http_client=http), mode="legacy" + ): + if cancel: + scope.cancel() + + assert delete_started.is_set() + assert delete_cancelled.is_set() is (failure == "timeout") + assert scope.cancelled_caught is cancel + + @pytest.mark.anyio async def test_configured_sse_limit_accepts_a_tool_result_larger_than_one_mebibyte() -> None: """SDK-defined: a larger SSE limit accepts a large tool result sent as one POST SSE event."""