Skip to content

Commit 4e21acb

Browse files
pete-buildsclaude
andcommitted
feat(session-reaper): give streamable-http sessions an idle timeout
Stateful streamable-http registers a transport session per client and never reaps it. The MCP SDK added session_idle_timeout to fix this and recommends 1800s, but FastMCP neither passes nor exposes the parameter: >>> mcp.http_app(session_idle_timeout=1800) TypeError: TransportMixin.http_app() got an unexpected keyword argument So sessions accumulated for the life of the process on every server, and a client that disconnected without DELETE leaked one every time. enable_session_reaper() patches the SDK manager to supply a default, and run_server installs it on the streamable-http path. It never overrides an explicit caller, skips stateless mode (the SDK rejects the parameter there), and warns rather than failing on an SDK too old to support it. Verified end to end against a live FastMCP server at a 3s timeout: 25 probe requests created 25 sessions, and _server_instances returned to 0 within 4s. tests/conftest.py restores the patched __init__ around every test, since run_server now installs a global patch that would otherwise leak across the suite. Workaround for PrefectHQ/fastmcp#3443; remove this module once that lands. Upstream detail in modelcontextprotocol/python-sdk#3228 and #2455. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 6bf0ceb commit 4e21acb

7 files changed

Lines changed: 346 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,36 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
77

88
## [Unreleased]
99

10+
### Added
11+
12+
- **Session reaping for streamable-http.** The MCP SDK registers a transport
13+
session per client and never reaps it; the SDK's own `session_idle_timeout`
14+
fixes this, but FastMCP neither passes nor exposes the parameter, so
15+
`mcp.http_app(session_idle_timeout=1800)` raises `TypeError`. Sessions
16+
therefore accumulated for the life of the process on every server, and a
17+
client that disconnects without `DELETE` leaked one each time.
18+
19+
New `pete_mcp_core.session_reaper.enable_session_reaper()` patches the SDK
20+
manager to supply a default, and `run_server` installs it automatically on
21+
the streamable-http path. Default 1800s, matching the SDK's own
22+
recommendation; tune or disable with `MCP_SESSION_IDLE_TIMEOUT`. Never
23+
overrides an explicit caller, skips stateless mode (where the SDK rejects the
24+
parameter), and warns instead of failing on an SDK too old to support it.
25+
26+
Verified end to end against a live FastMCP server at a 3s timeout: **25 probe
27+
requests created 25 sessions, and `_server_instances` returned to 0 within
28+
4s.**
29+
30+
This is a workaround for [PrefectHQ/fastmcp#3443](https://github.com/PrefectHQ/fastmcp/pull/3443).
31+
Remove `session_reaper.py` once that PR lands. Upstream detail in
32+
[python-sdk#3228](https://github.com/modelcontextprotocol/python-sdk/issues/3228)
33+
and [#2455](https://github.com/modelcontextprotocol/python-sdk/issues/2455).
34+
35+
Known residual: a session terminated by an explicit `DELETE` still leaves its
36+
entry in `_server_instances`, because the SDK skips that cleanup when the
37+
transport is already terminated. A few KB per session rather than the ~40 KB
38+
an orphaned session holds.
39+
1040
### Fixed
1141

1242
- **Memory leak: the healthcheck no longer probes the MCP transport endpoint.**

‎README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ implicit; every module is under 200 lines.
1818
| `pete_mcp_core.serve` | `run_server(mcp, *, default_port)` — stdio + streamable-http switch, `FASTMCP_HOST` / `MCP_HOST` env fallback. |
1919
| `pete_mcp_core.errors` | `@tool_errors(logger, *, catch)` decorator + shared `format_response(data)` helper. |
2020
| `pete_mcp_core.settings` | `BaseCoreSettings` — `mcp_transport`, `mcp_host`, `mcp_port`, `log_level`, `log_format`, `auth_token`, `auth_required`. |
21+
| `pete_mcp_core.session_reaper` | `enable_session_reaper(timeout)` gives streamable-http sessions an idle timeout the SDK will honor. Installed automatically by `run_server`; see [Session reaping](#session-reaping). |
2122
| `pete_mcp_core.auth` | `build_auth_provider(token, *, client_id, required)` returning a FastMCP `StaticTokenVerifier` or `None`. |
2223

2324
## Install
@@ -113,6 +114,41 @@ route's status codes differ from the defaults. Servers still on
113114
`DELETE` session reaping (measured 38.3 KB → 2.9 KB per probe, a 92% cut) —
114115
damage control, not a fix. Unset it.
115116

117+
## Session reaping
118+
119+
In stateful streamable-http (the default), the MCP SDK registers a transport
120+
session and never reaps it. The SDK added `session_idle_timeout` to fix that,
121+
and its own docstring recommends 1800 seconds, but FastMCP neither passes nor
122+
exposes it:
123+
124+
```python
125+
>>> mcp.http_app(session_idle_timeout=1800)
126+
TypeError: TransportMixin.http_app() got an unexpected keyword argument 'session_idle_timeout'
127+
```
128+
129+
So sessions accumulate for the life of the process on every server. A client
130+
that disconnects without sending `DELETE` leaks one every time.
131+
132+
`run_server` closes that gap by patching the SDK manager to supply a default,
133+
which is exactly what FastMCP will do natively once
134+
[PrefectHQ/fastmcp#3443](https://github.com/PrefectHQ/fastmcp/pull/3443) lands.
135+
Delete `session_reaper.py` when it does.
136+
137+
| Env var | Default | Purpose |
138+
|---|---|---|
139+
| `MCP_SESSION_IDLE_TIMEOUT` | `1800` | Seconds of inactivity before a session is reaped. Set to `off` to disable. |
140+
141+
Verified end to end against a live FastMCP server at a 3s timeout: 25 probe
142+
requests created 25 sessions, and `_server_instances` was back to 0 within 4s.
143+
144+
Two caveats. Keep the timeout comfortably above any SSE polling gap, because
145+
the SDK's timeout can cancel a session while a request is in flight
146+
([python-sdk#2455](https://github.com/modelcontextprotocol/python-sdk/issues/2455)).
147+
And a session terminated by an explicit `DELETE` still leaves its registry
148+
entry behind, which this does not address; that costs a few KB rather than the
149+
~40 KB an orphaned session holds
150+
([python-sdk#3228](https://github.com/modelcontextprotocol/python-sdk/issues/3228)).
151+
116152
## Design notes
117153

118154
- **What this library does not do:** wrap FastMCP. Tool registration,

‎src/pete_mcp_core/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
from pete_mcp_core.healthcheck import check
88
from pete_mcp_core.logging_setup import JsonFormatter, configure_logging
99
from pete_mcp_core.serve import run_server
10+
from pete_mcp_core.session_reaper import enable_session_reaper
1011
from pete_mcp_core.settings import BaseCoreSettings
1112

1213
__version__ = "0.1.0"
@@ -18,6 +19,7 @@
1819
"build_auth_provider",
1920
"check",
2021
"configure_logging",
22+
"enable_session_reaper",
2123
"format_response",
2224
"run_server",
2325
"tool_errors",

‎src/pete_mcp_core/serve.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@
2121
import os
2222
from typing import TYPE_CHECKING
2323

24+
from pete_mcp_core.session_reaper import enable_session_reaper
25+
2426
if TYPE_CHECKING:
2527
from fastmcp import FastMCP
2628

@@ -80,6 +82,9 @@ def run_server(
8082

8183
host = _resolve_host(default_host)
8284
port = _resolve_port(default_port)
85+
# Stateful streamable-http sessions are never reaped without this; see
86+
# session_reaper for why FastMCP cannot reach the SDK's own timeout yet.
87+
enable_session_reaper()
8388
os.environ["FASTMCP_HOST"] = host
8489
os.environ["FASTMCP_PORT"] = str(port)
8590
logger.info("Starting MCP server on %s:%d (transport=streamable-http)", host, port)
Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
"""Idle-session reaper for the streamable-http transport.
2+
3+
Why this exists: in stateful streamable-http (the default), the MCP SDK's
4+
``StreamableHTTPSessionManager`` registers a transport session and never reaps
5+
it. The SDK added ``session_idle_timeout`` to fix that, and its own docstring
6+
recommends 1800 seconds, but FastMCP neither passes nor exposes the parameter,
7+
so ``mcp.http_app(session_idle_timeout=1800)`` raises ``TypeError``. Sessions
8+
therefore accumulate for the life of the process on every server we run.
9+
10+
This patches the SDK manager's ``__init__`` to supply a default when the caller
11+
did not, which is exactly what FastMCP will do natively once
12+
`PrefectHQ/fastmcp#3443 <https://github.com/PrefectHQ/fastmcp/pull/3443>`_
13+
lands. Delete this module when it does.
14+
15+
Upstream context and measurements:
16+
``docs/audits/2026-08-13-fastmcp-session-leak-upstream.md`` in ai-cli-workspace,
17+
`modelcontextprotocol/python-sdk#3228 <https://github.com/modelcontextprotocol/python-sdk/issues/3228>`_,
18+
and `#2455 <https://github.com/modelcontextprotocol/python-sdk/issues/2455>`_.
19+
20+
Known residual: a session terminated by an explicit ``DELETE`` still leaves its
21+
entry in ``_server_instances`` (the SDK skips that cleanup when the transport is
22+
already terminated). This reaper does not address that; it costs a few KB per
23+
session rather than the ~40 KB an orphaned session holds.
24+
25+
Tuning: set ``MCP_SESSION_IDLE_TIMEOUT`` to a number of seconds, or to ``off``
26+
to disable. Keep it comfortably above any SSE polling gap, since the SDK's
27+
timeout can cancel a session while a long request is in flight
28+
(`python-sdk#2455 <https://github.com/modelcontextprotocol/python-sdk/issues/2455>`_).
29+
"""
30+
31+
from __future__ import annotations
32+
33+
import functools
34+
import inspect
35+
import logging
36+
import os
37+
38+
logger = logging.getLogger(__name__)
39+
40+
#: Seconds of inactivity before a stateful session is reaped. Matches the value
41+
#: the SDK docstring recommends for most deployments.
42+
DEFAULT_IDLE_TIMEOUT = 1800.0
43+
44+
_ENV_VAR = "MCP_SESSION_IDLE_TIMEOUT"
45+
_PATCH_FLAG = "_pete_mcp_core_idle_patch"
46+
_DISABLE_VALUES = {"0", "off", "none", "no", "false", "disabled"}
47+
48+
49+
def _resolve_timeout(explicit: float | None) -> float | None:
50+
"""Resolve the idle timeout from an explicit value or the environment.
51+
52+
Returns None when the reaper should stay off.
53+
"""
54+
if explicit is not None:
55+
return explicit if explicit > 0 else None
56+
57+
raw = os.getenv(_ENV_VAR)
58+
if raw is None or not raw.strip():
59+
return DEFAULT_IDLE_TIMEOUT
60+
61+
value = raw.strip().lower()
62+
if value in _DISABLE_VALUES:
63+
return None
64+
try:
65+
parsed = float(value)
66+
except ValueError as exc:
67+
raise ValueError(f"{_ENV_VAR} must be a number of seconds or 'off', got {raw!r}") from exc
68+
return parsed if parsed > 0 else None
69+
70+
71+
def enable_session_reaper(timeout_seconds: float | None = None) -> float | None:
72+
"""Give streamable-http sessions an idle timeout the SDK will honor.
73+
74+
Safe to call more than once; the patch is installed at most once. Never
75+
overrides a caller that passes ``session_idle_timeout`` itself, and never
76+
applies in stateless mode, where the SDK rejects the parameter outright.
77+
78+
Args:
79+
timeout_seconds: Idle timeout to apply. Falls back to
80+
``MCP_SESSION_IDLE_TIMEOUT``, then to :data:`DEFAULT_IDLE_TIMEOUT`.
81+
A non-positive value disables the reaper.
82+
83+
Returns:
84+
The timeout that was installed, or None if the reaper stayed off.
85+
"""
86+
timeout = _resolve_timeout(timeout_seconds)
87+
if timeout is None:
88+
logger.info(
89+
"Session idle reaper disabled; streamable-http sessions will persist "
90+
"for the life of the process"
91+
)
92+
return None
93+
94+
try:
95+
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
96+
except ImportError: # pragma: no cover - mcp is a hard dependency of fastmcp
97+
logger.warning("Could not import StreamableHTTPSessionManager; reaper not installed")
98+
return None
99+
100+
original = StreamableHTTPSessionManager.__init__
101+
if getattr(original, _PATCH_FLAG, False):
102+
return timeout
103+
104+
signature = inspect.signature(original)
105+
if "session_idle_timeout" not in signature.parameters:
106+
logger.warning(
107+
"Installed mcp SDK does not accept session_idle_timeout; "
108+
"streamable-http sessions will accumulate for the life of the process. "
109+
"Upgrade to mcp>=1.27 to enable the reaper."
110+
)
111+
return None
112+
113+
@functools.wraps(original)
114+
def patched(self, *args, **kwargs): # type: ignore[no-untyped-def]
115+
bound = signature.bind_partial(self, *args, **kwargs)
116+
already_set = "session_idle_timeout" in bound.arguments
117+
# The SDK raises if a stateless manager is given an idle timeout, and a
118+
# stateless transport is torn down per request anyway.
119+
stateless = bool(bound.arguments.get("stateless", False))
120+
if not already_set and not stateless:
121+
kwargs["session_idle_timeout"] = timeout
122+
return original(self, *args, **kwargs)
123+
124+
patched.__dict__[_PATCH_FLAG] = True
125+
StreamableHTTPSessionManager.__init__ = patched # type: ignore[method-assign]
126+
logger.info(
127+
"Session idle reaper enabled at %.0fs (workaround for PrefectHQ/fastmcp#3443)",
128+
timeout,
129+
)
130+
return timeout

‎tests/conftest.py‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
"""Shared pytest fixtures."""
2+
3+
from __future__ import annotations
4+
5+
import pytest
6+
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
7+
8+
9+
@pytest.fixture(autouse=True)
10+
def _isolate_session_reaper_patch():
11+
"""Keep the session-reaper monkeypatch from leaking between tests.
12+
13+
``enable_session_reaper`` patches a class on the installed SDK, so any test
14+
that calls ``run_server`` would otherwise leave every later test running
15+
against a patched manager. Restore the pristine ``__init__`` around each
16+
test, unwrapping first in case a previous test already installed the patch.
17+
"""
18+
current = StreamableHTTPSessionManager.__init__
19+
pristine = getattr(current, "__wrapped__", current)
20+
StreamableHTTPSessionManager.__init__ = pristine
21+
try:
22+
yield
23+
finally:
24+
StreamableHTTPSessionManager.__init__ = pristine

‎tests/test_session_reaper.py‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
"""Tests for pete_mcp_core.session_reaper."""
2+
3+
from __future__ import annotations
4+
5+
import logging
6+
7+
import pytest
8+
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
9+
10+
from pete_mcp_core.session_reaper import (
11+
DEFAULT_IDLE_TIMEOUT,
12+
_resolve_timeout,
13+
enable_session_reaper,
14+
)
15+
16+
17+
@pytest.fixture(autouse=True)
18+
def _clear_env(monkeypatch: pytest.MonkeyPatch) -> None:
19+
monkeypatch.delenv("MCP_SESSION_IDLE_TIMEOUT", raising=False)
20+
21+
22+
class TestResolveTimeout:
23+
def test_defaults_when_env_missing(self) -> None:
24+
assert _resolve_timeout(None) == DEFAULT_IDLE_TIMEOUT
25+
26+
def test_explicit_wins_over_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
27+
monkeypatch.setenv("MCP_SESSION_IDLE_TIMEOUT", "900")
28+
assert _resolve_timeout(60.0) == 60.0
29+
30+
def test_reads_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
31+
monkeypatch.setenv("MCP_SESSION_IDLE_TIMEOUT", "900")
32+
assert _resolve_timeout(None) == 900.0
33+
34+
@pytest.mark.parametrize("value", ["off", "0", "none", "false", "DISABLED"])
35+
def test_disable_values(self, monkeypatch: pytest.MonkeyPatch, value: str) -> None:
36+
monkeypatch.setenv("MCP_SESSION_IDLE_TIMEOUT", value)
37+
assert _resolve_timeout(None) is None
38+
39+
def test_blank_env_falls_back_to_default(self, monkeypatch: pytest.MonkeyPatch) -> None:
40+
monkeypatch.setenv("MCP_SESSION_IDLE_TIMEOUT", " ")
41+
assert _resolve_timeout(None) == DEFAULT_IDLE_TIMEOUT
42+
43+
def test_rejects_garbage(self, monkeypatch: pytest.MonkeyPatch) -> None:
44+
monkeypatch.setenv("MCP_SESSION_IDLE_TIMEOUT", "half an hour")
45+
with pytest.raises(ValueError, match="MCP_SESSION_IDLE_TIMEOUT"):
46+
_resolve_timeout(None)
47+
48+
def test_negative_explicit_disables(self) -> None:
49+
assert _resolve_timeout(-1.0) is None
50+
51+
52+
class TestEnableSessionReaper:
53+
def test_sdk_supports_the_parameter(self) -> None:
54+
"""Positive control: if this fails the workaround is moot, not broken."""
55+
import inspect
56+
57+
params = inspect.signature(StreamableHTTPSessionManager.__init__).parameters
58+
assert "session_idle_timeout" in params
59+
60+
def test_injects_default_timeout(self) -> None:
61+
enable_session_reaper()
62+
manager = StreamableHTTPSessionManager(app=object())
63+
assert manager.session_idle_timeout == DEFAULT_IDLE_TIMEOUT
64+
65+
def test_unpatched_manager_has_no_timeout(self) -> None:
66+
"""Negative control: without the patch the SDK default really is None."""
67+
manager = StreamableHTTPSessionManager(app=object())
68+
assert manager.session_idle_timeout is None
69+
70+
def test_explicit_timeout_wins(self) -> None:
71+
enable_session_reaper(60.0)
72+
manager = StreamableHTTPSessionManager(app=object())
73+
assert manager.session_idle_timeout == 60.0
74+
75+
def test_never_overrides_an_explicit_caller(self) -> None:
76+
enable_session_reaper()
77+
manager = StreamableHTTPSessionManager(app=object(), session_idle_timeout=30.0)
78+
assert manager.session_idle_timeout == 30.0
79+
80+
def test_skips_stateless_mode(self) -> None:
81+
"""The SDK raises if a stateless manager is handed an idle timeout."""
82+
enable_session_reaper()
83+
manager = StreamableHTTPSessionManager(app=object(), stateless=True)
84+
assert manager.session_idle_timeout is None
85+
86+
def test_skips_stateless_passed_positionally(self) -> None:
87+
enable_session_reaper()
88+
manager = StreamableHTTPSessionManager(object(), None, False, True)
89+
assert manager.session_idle_timeout is None
90+
91+
def test_disabled_leaves_sdk_default(self, monkeypatch: pytest.MonkeyPatch) -> None:
92+
monkeypatch.setenv("MCP_SESSION_IDLE_TIMEOUT", "off")
93+
assert enable_session_reaper() is None
94+
manager = StreamableHTTPSessionManager(app=object())
95+
assert manager.session_idle_timeout is None
96+
97+
def test_is_idempotent(self) -> None:
98+
enable_session_reaper(120.0)
99+
first = StreamableHTTPSessionManager.__init__
100+
assert enable_session_reaper(999.0) == 999.0
101+
assert StreamableHTTPSessionManager.__init__ is first
102+
manager = StreamableHTTPSessionManager(app=object())
103+
assert manager.session_idle_timeout == 120.0
104+
105+
def test_logs_the_installed_timeout(self, caplog: pytest.LogCaptureFixture) -> None:
106+
with caplog.at_level(logging.INFO, logger="pete_mcp_core.session_reaper"):
107+
enable_session_reaper(300.0)
108+
assert any("Session idle reaper enabled" in r.getMessage() for r in caplog.records)
109+
110+
def test_warns_when_sdk_lacks_support(
111+
self, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
112+
) -> None:
113+
def legacy_init(self, app, event_store=None, json_response=False, stateless=False):
114+
self.session_idle_timeout = None
115+
116+
monkeypatch.setattr(StreamableHTTPSessionManager, "__init__", legacy_init)
117+
with caplog.at_level(logging.WARNING, logger="pete_mcp_core.session_reaper"):
118+
assert enable_session_reaper() is None
119+
assert any("does not accept session_idle_timeout" in r.getMessage() for r in caplog.records)

0 commit comments

Comments
 (0)