feat: add idle timeout for StreamableHTTP sessions

Add a session_idle_timeout parameter to StreamableHTTPSessionManager that
enables automatic cleanup of idle sessions, fixing the memory leak
described in #1283.

Each session with idle timeout configured starts a per-session watcher
task that sleeps until the deadline and calls terminate() when idle.
Incoming requests push back the deadline. No central background reaper
is needed — each session manages its own lifecycle.

- Per-session idle watcher runs alongside app.run in a task group
- Effective timeout accounts for retry_interval to avoid premature
  reaping of SSE polling sessions
- terminate() on the transport is now idempotent
- Default is None (no timeout, fully backwards compatible)

Github-Issue: #1283

Author: felixweinberger

src/mcp/server/streamable_http.py

@@ -180,6 +180,8 @@ def __init__(
         ] = {}
         self._sse_stream_writers: dict[RequestId, MemoryObjectSendStream[dict[str, str]]] = {}
         self._terminated = False
+        # Idle timeout deadline (monotonic time); managed by the session manager.
+        self.idle_deadline: float | None = None
 
     @property
     def is_terminated(self) -> bool:
@@ -773,8 +775,12 @@ async def terminate(self) -> None:
         """Terminate the current session, closing all streams.
 
         Once terminated, all requests with this session ID will receive 404 Not Found.
+        Calling this method multiple times is safe (idempotent).
         """
 
+        if self._terminated:
+            return
+
         self._terminated = True
         logger.info(f"Terminating session: {self.mcp_session_id}")
 

src/mcp/server/streamable_http_manager.py

@@ -10,6 +10,7 @@
 from uuid import uuid4
 
 import anyio
+import anyio.abc
 from anyio.abc import TaskStatus
 from starlette.requests import Request
 from starlette.responses import Response
@@ -38,6 +39,7 @@ class StreamableHTTPSessionManager:
     2. Resumability via an optional event store
     3. Connection management and lifecycle
     4. Request handling and transport setup
+    5. Idle session cleanup via optional timeout
 
     Important: Only one StreamableHTTPSessionManager instance should be created
     per application. The instance cannot be reused after its run() context has
@@ -55,6 +57,22 @@ class StreamableHTTPSessionManager:
         security_settings: Optional transport security settings.
         retry_interval: Retry interval in milliseconds to suggest to clients in SSE
                        retry field. Used for SSE polling behavior.
+        session_idle_timeout: Optional idle timeout in seconds for stateful sessions.
+                            If set, sessions that receive no HTTP requests for this
+                            duration will be automatically terminated and removed.
+                            When retry_interval is also set, the effective idle
+                            threshold is at least ``retry_interval / 1000 * 3`` to
+                            avoid prematurely reaping sessions that are simply
+                            waiting for SSE polling reconnections. Default is None
+                            (no timeout). A value of 1800 (30 minutes) is
+                            recommended for most deployments.
+
+                            Note: The idle timer is based on incoming HTTP requests
+                            (POST, GET, DELETE), not on whether SSE connections are
+                            open. If clients maintain long-lived GET SSE streams
+                            without sending other requests, set this value higher
+                            than the longest expected SSE connection lifetime to
+                            avoid premature reaping.
     """
 
     def __init__(
@@ -65,13 +83,20 @@ def __init__(
         stateless: bool = False,
         security_settings: TransportSecuritySettings | None = None,
         retry_interval: int | None = None,
+        session_idle_timeout: float | None = None,
     ):
+        if session_idle_timeout is not None and session_idle_timeout <= 0:
+            raise ValueError("session_idle_timeout must be a positive number of seconds")
+        if stateless and session_idle_timeout is not None:
+            raise ValueError("session_idle_timeout is not supported in stateless mode")
+
         self.app = app
         self.event_store = event_store
         self.json_response = json_response
         self.stateless = stateless
         self.security_settings = security_settings
         self.retry_interval = retry_interval
+        self.session_idle_timeout = session_idle_timeout
 
         # Session tracking (only used if not stateless)
         self._session_creation_lock = anyio.Lock()
@@ -114,6 +139,7 @@ async def lifespan(app: Starlette) -> AsyncIterator[None]:
             # Store the task group for later use
             self._task_group = tg
             logger.info("StreamableHTTP session manager started")
+
             try:
                 yield  # Let the application run
             finally:
@@ -219,6 +245,9 @@ async def _handle_stateful_request(
         if request_mcp_session_id is not None and request_mcp_session_id in self._server_instances:  # pragma: no cover
             transport = self._server_instances[request_mcp_session_id]
             logger.debug("Session already exists, handling request directly")
+            # Push back idle deadline on activity
+            if transport.idle_deadline is not None:
+                transport.idle_deadline = anyio.current_time() + self._effective_idle_timeout()
             await transport.handle_request(scope, receive, send)
             return
 
@@ -245,12 +274,35 @@ async def run_server(*, task_status: TaskStatus[None] = anyio.TASK_STATUS_IGNORE
                         read_stream, write_stream = streams
                         task_status.started()
                         try:
-                            await self.app.run(
-                                read_stream,
-                                write_stream,
-                                self.app.create_initialization_options(),
-                                stateless=False,  # Stateful mode
-                            )
+                            # If idle timeout is configured, run app.run and idle
+                            # watcher concurrently — the watcher terminates the
+                            # transport when it goes idle, which causes app.run
+                            # to return via the closed read stream.
+                            if self.session_idle_timeout is not None:
+                                timeout = self._effective_idle_timeout()
+                                http_transport.idle_deadline = anyio.current_time() + timeout
+                                async with anyio.create_task_group() as session_tg:
+                                    session_tg.start_soon(
+                                        self._idle_watcher,
+                                        http_transport,
+                                        session_tg,
+                                    )
+                                    await self.app.run(
+                                        read_stream,
+                                        write_stream,
+                                        self.app.create_initialization_options(),
+                                        stateless=False,
+                                    )
+                                    # app.run returned normally (e.g. client sent
+                                    # a clean shutdown) — cancel the watcher.
+                                    session_tg.cancel_scope.cancel()  # pragma: no cover
+                            else:
+                                await self.app.run(
+                                    read_stream,
+                                    write_stream,
+                                    self.app.create_initialization_options(),
+                                    stateless=False,  # Stateful mode
+                                )
                         except Exception as e:
                             logger.error(
                                 f"Session {http_transport.mcp_session_id} crashed: {e}",
@@ -295,3 +347,41 @@ async def run_server(*, task_status: TaskStatus[None] = anyio.TASK_STATUS_IGNORE
                 media_type="application/json",
             )
             await response(scope, receive, send)
+
+    def _effective_idle_timeout(self) -> float:
+        """Compute the effective idle timeout, accounting for retry_interval.
+
+        When SSE polling is configured via ``retry_interval`` (milliseconds),
+        the client may legitimately go quiet between polls.  The idle threshold
+        must be large enough so that normal polling gaps don't cause premature
+        session reaping.
+        """
+        assert self.session_idle_timeout is not None
+        timeout = self.session_idle_timeout
+        if self.retry_interval is not None:
+            retry_seconds = self.retry_interval / 1000.0
+            timeout = max(timeout, retry_seconds * 3)
+        return timeout
+
+    async def _idle_watcher(
+        self,
+        transport: StreamableHTTPServerTransport,
+        task_group: anyio.abc.TaskGroup,
+    ) -> None:
+        """Per-session task that terminates the transport when it goes idle."""
+        while not transport.is_terminated:  # pragma: no branch
+            assert transport.idle_deadline is not None
+            now = anyio.current_time()
+            remaining = transport.idle_deadline - now
+            if remaining > 0:
+                await anyio.sleep(remaining)
+                continue
+
+            # Deadline passed — terminate
+            session_id = transport.mcp_session_id
+            logger.info(f"Terminating idle session {session_id}")
+            self._server_instances.pop(session_id, None)  # type: ignore[arg-type]
+            await transport.terminate()
+            # Cancel the session task group so app.run exits
+            task_group.cancel_scope.cancel()
+            return