π The fast, Pythonic way to build MCP servers and clients.
fix(http): preserve the SDK's default session idle timeout (#5229)
astsa35b88bba365
diff --git a/docs/more/settings.mdx b/docs/more/settings.mdxindex 0c6a53fb5..b3bf5450c 100644--- a/docs/more/settings.mdx+++ b/docs/more/settings.mdx@@ -46,9 +46,14 @@ These control how the server listens when running with an HTTP transport.| `FASTMCP_HTTP_HOST_ORIGIN_PROTECTION` | `bool \| "auto"` | `false` | Validate `Host` and browser `Origin` headers for Streamable HTTP and SSE requests. `auto` protects localhost-bound servers and explicit host/origin allowlists. `false` disables this guard and FastMCP's DNS-rebinding protection for the endpoint. || `FASTMCP_HTTP_ALLOWED_HOSTS` | `list[str] \| null` | `null` | Additional trusted hostnames when Host and Origin protection is enabled. Use a JSON array, such as `["mcp.example.com"]`. || `FASTMCP_HTTP_ALLOWED_ORIGINS` | `list[str] \| null` | `null` | Browser origins trusted when Host and Origin protection is enabled. Configure CORS separately for cross-origin browser reads. Use a JSON array, such as `["https://app.example.com"]`. |-| `FASTMCP_HTTP_SESSION_IDLE_TIMEOUT` | `float \| null` | `null` | Seconds a Streamable HTTP session may remain idle before it is terminated. The deadline resets on every request. When `null`, sessions never expire from inactivity. Not supported in stateless mode. |+| `FASTMCP_HTTP_SESSION_IDLE_TIMEOUT` | `float \| "auto" \| "none"` | `"auto"` | Seconds a stateful Streamable HTTP session may remain idle before it is terminated. `"auto"` uses the MCP SDK's default: 1800 seconds (30 minutes) in SDK 2.2, no timeout in earlier versions. Set a positive number to override it, or `none` to disable it. || `FASTMCP_DEBUG` | `bool` | `false` | Enable debug mode. |+MCP SDK 2.2 also limits concurrent stateful HTTP sessions to 10,000. Keeping+the default idle timeout lets abandoned sessions expire and frees capacity for+new connections. Disabling it means clients must explicitly close their sessions+to release that capacity. Stateless HTTP does not use the session pool.+## Error Handling| Environment Variable | Type | Default | Description |diff --git a/fastmcp_slim/fastmcp/server/http.py b/fastmcp_slim/fastmcp/server/http.pyindex d78c48bd1..8a31201ea 100644--- a/fastmcp_slim/fastmcp/server/http.py+++ b/fastmcp_slim/fastmcp/server/http.py@@ -52,9 +52,12 @@ class FastMCPStreamableHTTPSessionManager(StreamableHTTPSessionManager):stateless: bool = False,security_settings: TransportSecuritySettings | None = None,retry_interval: int | None = None,- session_idle_timeout: float | None = None,+ session_idle_timeout: float | Literal["auto"] | None = "auto",) -> None:self._shared_event_store: EventStore | None = None+ session_options: dict[str, Any] = {}+ if session_idle_timeout != "auto":+ session_options["session_idle_timeout"] = session_idle_timeoutsuper().__init__(app=app,event_store=event_store,@@ -62,7 +65,7 @@ class FastMCPStreamableHTTPSessionManager(StreamableHTTPSessionManager):stateless=stateless,security_settings=security_settings,retry_interval=retry_interval,- session_idle_timeout=session_idle_timeout,+ **session_options,)@property@@ -632,7 +635,7 @@ def create_streamable_http_app(host_origin_protection: HostOriginProtection = False,allowed_hosts: Sequence[str] | None = None,allowed_origins: Sequence[str] | None = None,- session_idle_timeout: float | None = None,+ session_idle_timeout: float | Literal["auto"] | None = "auto",) -> StarletteWithLifespan:"""Return an instance of the StreamableHTTP server app.@@ -659,8 +662,9 @@ def create_streamable_http_app(cross-origin responses.session_idle_timeout: Maximum time in seconds a session may remain idlebefore it is terminated. The deadline is pushed forward on every- request. When None, sessions never expire from inactivity. Not- supported in stateless mode.+ request. Defaults to "auto", which uses the MCP SDK's default+ (1800 seconds as of SDK 2.2). When None, sessions never expire+ from inactivity. Only applies to stateful HTTP sessions.Returns:A Starlette application with StreamableHTTP supportdiff --git a/fastmcp_slim/fastmcp/server/mixins/transport.py b/fastmcp_slim/fastmcp/server/mixins/transport.pyindex 75483d1b6..4f7e5a37a 100644--- a/fastmcp_slim/fastmcp/server/mixins/transport.py+++ b/fastmcp_slim/fastmcp/server/mixins/transport.py@@ -376,7 +376,7 @@ class TransportMixin:host_origin_protection: HostOriginProtection | None = None,allowed_hosts: list[str] | None = None,allowed_origins: list[str] | None = None,- session_idle_timeout: float | None = None,+ session_idle_timeout: float | Literal["auto"] | None = None,) -> StarletteWithLifespan:"""Create a Starlette app using the specified HTTP transport.@@ -403,7 +403,9 @@ class TransportMixin:cross-origin responses.session_idle_timeout: Maximum time in seconds a streamable-HTTPsession may remain idle before it is terminated. When None,- falls back to the ``http_session_idle_timeout`` setting.+ falls back to the `http_session_idle_timeout` setting.+ "auto" uses the MCP SDK's default. To disable the timeout,+ set `FASTMCP_HTTP_SESSION_IDLE_TIMEOUT=none`.Returns:A Starlette application configured with the specified transportdiff --git a/fastmcp_slim/fastmcp/settings.py b/fastmcp_slim/fastmcp/settings.pyindex 8b62d6d70..e58a28bf5 100644--- a/fastmcp_slim/fastmcp/settings.py+++ b/fastmcp_slim/fastmcp/settings.py@@ -283,20 +283,28 @@ class Settings(BaseSettings):http_allowed_hosts: list[str] | None = Nonehttp_allowed_origins: list[str] | None = Nonehttp_session_idle_timeout: Annotated[- float | None,+ Annotated[float, Field(gt=0)] | Literal["auto"] | None,Field(description=inspect.cleandoc("""Maximum time in seconds a streamable-HTTP session may remainidle before it is terminated. A session's deadline is pushed- forward on every request. When None (default), sessions never- expire from inactivity. Not supported in stateless HTTP mode.- Must be a positive number of seconds when set.+ forward on every request. Defaults to "auto", which uses the+ MCP SDK's default (1800 seconds as of SDK 2.2). When None,+ sessions never expire from inactivity. Only applies to stateful+ HTTP sessions.+ Explicit durations must be a positive number of seconds."""),- gt=0,),- ] = None+ ] = "auto"++ @field_validator("http_session_idle_timeout", mode="before")+ @classmethod+ def parse_disabled_session_idle_timeout(cls, v):+ if isinstance(v, str) and v.lower() == "none":+ return None+ return vmounted_components_raise_on_load_error: Annotated[bool,diff --git a/tests/server/http/test_session_idle_timeout.py b/tests/server/http/test_session_idle_timeout.pyindex f7adad149..3199e0254 100644--- a/tests/server/http/test_session_idle_timeout.py+++ b/tests/server/http/test_session_idle_timeout.py@@ -6,7 +6,10 @@ behavior, surfaced through FastMCP's ``http_session_idle_timeout`` setting."""import time+from typing import Any+import pytest+from mcp.server.streamable_http_manager import StreamableHTTPSessionManagerfrom starlette.testclient import TestClientfrom fastmcp.server import FastMCP@@ -15,6 +18,7 @@ from fastmcp.server.http import (StreamableHTTPASGIApp,create_streamable_http_app,)+from fastmcp.utilities.tests import temporary_settingsINITIALIZE_REQUEST = {"jsonrpc": "2.0",@@ -38,14 +42,133 @@ def _find_session_manager(app: StarletteWithLifespan):return None-def test_idle_session_is_terminated_after_timeout():- server = FastMCP(name="IdleTimeoutServer")- app = create_streamable_http_app(- server=server,- streamable_http_path="/mcp",- session_idle_timeout=0.1,[email protected]("use_http_app", [True, False])+def test_default_timeout_reaches_session_manager(use_http_app: bool):+ server = FastMCP(name="DefaultTimeoutServer")+ app = (+ server.http_app(path="/mcp")+ if use_http_app+ else create_streamable_http_app(server, "/mcp")+ )++ with TestClient(app, base_url="http://127.0.0.1") as client:+ response = client.post("/mcp", headers=MCP_HEADERS, json=INITIALIZE_REQUEST)+ assert response.status_code == 200+ sm = _find_session_manager(app)+ assert sm is not None+ assert (+ sm.session_idle_timeout+ == StreamableHTTPSessionManager(server._mcp_server).session_idle_timeout+ )++[email protected]("use_http_app", [True, False])+def test_idle_timeout_can_be_disabled(use_http_app: bool):+ server = FastMCP(name="NoIdleTimeoutServer")+ with temporary_settings(http_session_idle_timeout=None):+ app = (+ server.http_app(path="/mcp")+ if use_http_app+ else create_streamable_http_app(server, "/mcp", session_idle_timeout=None)+ )++ with TestClient(app, base_url="http://127.0.0.1") as client:+ response = client.post("/mcp", headers=MCP_HEADERS, json=INITIALIZE_REQUEST)+ assert response.status_code == 200+ sm = _find_session_manager(app)+ assert sm is not None+ assert sm.session_idle_timeout is None+ assert response.headers["mcp-session-id"] in sm._server_instances++[email protected]("use_http_app", [True, False])+def test_default_timeout_supports_stateless_app(use_http_app: bool):+ server = FastMCP(name="StatelessServer")+ with temporary_settings(stateless_http=True):+ app = (+ server.http_app(path="/mcp")+ if use_http_app+ else create_streamable_http_app(server, "/mcp", stateless_http=True)+ )++ with TestClient(app, base_url="http://127.0.0.1") as client:+ response = client.post("/mcp", headers=MCP_HEADERS, json=INITIALIZE_REQUEST)+ assert response.status_code == 200+ assert "mcp-session-id" not in response.headers+ sm = _find_session_manager(app)+ assert sm is not None+ assert not sm._server_instances+++def test_http_app_timeout_overrides_setting():+ with temporary_settings(http_session_idle_timeout=1800):+ app = FastMCP(name="TimeoutOverrideServer").http_app(session_idle_timeout=60)++ with TestClient(app):+ sm = _find_session_manager(app)+ assert sm is not None+ assert sm.session_idle_timeout == 60++[email protected]("use_http_app", [True, False])+def test_default_timeout_frees_session_capacity(use_http_app: bool, monkeypatch):+ server = FastMCP(name="SessionCapacityServer")+ if not hasattr(StreamableHTTPSessionManager(server._mcp_server), "max_sessions"):+ pytest.skip("The session capacity limit was added in MCP SDK 2.2")++ sdk_init = StreamableHTTPSessionManager.__init__++ def small_session_pool(+ self, *args: Any, session_idle_timeout: float | None = 0.5, **kwargs: Any+ ):+ # Shorten only the SDK default, preserving an explicit None from FastMCP.+ sdk_init(+ self,+ *args,+ session_idle_timeout=session_idle_timeout,+ **{**kwargs, "max_sessions": 1},+ )++ monkeypatch.setattr(StreamableHTTPSessionManager, "__init__", small_session_pool)+ app = (+ server.http_app(path="/mcp")+ if use_http_app+ else create_streamable_http_app(server, "/mcp"))+ with TestClient(app, base_url="http://127.0.0.1") as client:+ response = client.post("/mcp", headers=MCP_HEADERS, json=INITIALIZE_REQUEST)+ assert response.status_code == 200+ session_id = response.headers["mcp-session-id"]+ response = client.post("/mcp", headers=MCP_HEADERS, json=INITIALIZE_REQUEST)+ assert response.status_code == 503++ sm = _find_session_manager(app)+ assert sm is not None+ deadline = time.monotonic() + 3.0+ while session_id in sm._server_instances and time.monotonic() < deadline:+ time.sleep(0.02)+ assert session_id not in sm._server_instances++ response = client.post("/mcp", headers=MCP_HEADERS, json=INITIALIZE_REQUEST)+ assert response.status_code == 200+ assert response.headers["mcp-session-id"] != session_id++[email protected]("use_http_app", [True, False])+def test_idle_session_is_terminated_after_timeout(use_http_app: bool):+ server = FastMCP(name="IdleTimeoutServer")+ with temporary_settings(http_session_idle_timeout=0.1):+ app = (+ server.http_app(path="/mcp")+ if use_http_app+ else create_streamable_http_app(+ server=server,+ streamable_http_path="/mcp",+ session_idle_timeout=0.1,+ )+ )+with TestClient(app, base_url="http://127.0.0.1") as client:response = client.post("/mcp", headers=MCP_HEADERS, json=INITIALIZE_REQUEST)assert response.status_code == 200diff --git a/tests/test_settings.py b/tests/test_settings.pyindex 09d014a66..0a1357d25 100644--- a/tests/test_settings.py+++ b/tests/test_settings.py@@ -1,4 +1,5 @@import pytest+from pydantic import ValidationErrorfrom fastmcp.settings import Settings@@ -19,3 +20,29 @@ def test_http_host_origin_protection_env_var(value, expected, monkeypatch):monkeypatch.setenv("FASTMCP_HTTP_HOST_ORIGIN_PROTECTION", value)assert Settings().http_host_origin_protection == expected+++def test_http_session_idle_timeout_defaults_to_auto():+ assert Settings().http_session_idle_timeout == "auto"++[email protected]("value", ["auto", "60", "0.5"])+def test_http_session_idle_timeout_env_var(value, monkeypatch):+ monkeypatch.setenv("FASTMCP_HTTP_SESSION_IDLE_TIMEOUT", value)+ expected = "auto" if value == "auto" else float(value)+ assert Settings().http_session_idle_timeout == expected+++def test_http_session_idle_timeout_can_be_disabled():+ assert Settings(http_session_idle_timeout=None).http_session_idle_timeout is None+++def test_http_session_idle_timeout_env_var_none_disables(monkeypatch):+ monkeypatch.setenv("FASTMCP_HTTP_SESSION_IDLE_TIMEOUT", "none")+ assert Settings().http_session_idle_timeout is None++[email protected]("value", [0, -1, "invalid"])+def test_http_session_idle_timeout_rejects_invalid_values(value):+ with pytest.raises(ValidationError):+ Settings(http_session_idle_timeout=value)