Skip to content

πŸš€ 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.mdx
index 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.py
index 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_timeout
super().__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 idle
before 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 support
diff --git a/fastmcp_slim/fastmcp/server/mixins/transport.py b/fastmcp_slim/fastmcp/server/mixins/transport.py
index 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-HTTP
session 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 transport
diff --git a/fastmcp_slim/fastmcp/settings.py b/fastmcp_slim/fastmcp/settings.py
index 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 = None
http_allowed_origins: list[str] | None = None
http_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 remain
idle 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 v
mounted_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.py
index 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 StreamableHTTPSessionManager
from starlette.testclient import TestClient
from fastmcp.server import FastMCP
@@ -15,6 +18,7 @@ from fastmcp.server.http import (
StreamableHTTPASGIApp,
create_streamable_http_app,
)
+from fastmcp.utilities.tests import temporary_settings
INITIALIZE_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 == 200
diff --git a/tests/test_settings.py b/tests/test_settings.py
index 09d014a66..0a1357d25 100644
--- a/tests/test_settings.py
+++ b/tests/test_settings.py
@@ -1,4 +1,5 @@
import pytest
+from pydantic import ValidationError
from 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)