Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions docs/client/transports.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
9 changes: 7 additions & 2 deletions src/mcp/client/streamable_http.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -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}")


Expand All @@ -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.

Expand Down Expand Up @@ -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()
131 changes: 130 additions & 1 deletion tests/client/test_streamable_http.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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."""
Expand Down
Loading