docs: describe session lifetime and limits in one place

The idle timeout and the session cap were explained piecemeal on three
pages. legacy-clients.md gains a "Session lifetime and limits" section
with both settings, what counts as in flight, what the client sees and
how to turn each off; the options list in run/index.md and the
troubleshooting entry now point at it instead of restating it.

Author: maxisbey

docs/run/index.md

@@ -70,12 +70,11 @@ Each transport has its own keyword arguments, all on `run()`:
 * `max_request_body_size`: largest accepted request body in bytes. Defaults to 4 MiB; larger requests
   receive HTTP 413 before parsing or session creation. Raise it only when legitimate MCP messages
   exceed that size.
-* `session_idle_timeout`: how long, in seconds, a [legacy](legacy-clients.md) (session-based)
-  client's session may sit with no request in flight before the server closes it. Defaults to 1800
-  (30 minutes); `None` keeps sessions until the client deletes them. A client with an open `GET`
-  stream or a request still being answered is never idle.
-* `max_sessions`: how many such sessions one app holds at once. Defaults to 10 000; while that many
-  are open, a request that would open another gets HTTP 503. `None` removes the limit.
+* `session_idle_timeout`: seconds a legacy session may sit with nothing in flight before the
+  server closes it. Default 1800. `None` disables it. See
+  [Session lifetime and limits](legacy-clients.md#session-lifetime-and-limits).
+* `max_sessions`: how many legacy sessions one process holds at once. Default 10 000. `None`
+  removes the limit. Covered in the same section.
 * `event_store`, `retry_interval`, `transport_security`: resumability and DNS-rebinding protection. They can wait, until you deploy somewhere other than localhost; **[Deploy & scale](deploy.md)** covers `transport_security`.
 
 !!! warning

docs/run/legacy-clients.md

@@ -56,12 +56,39 @@ On one worker that is invisible. On two, it is the whole problem: a request that
     events to a client reconnecting to the *same* session), not a session store. It never makes a
     session reachable from another process.
 
-The record is not kept forever. A client that ends its session (`DELETE`) frees it at once;
-a session that has had no request in flight for `session_idle_timeout` seconds (default 1800; an
-open `GET` stream or a request being answered counts as in flight) is closed, and its next request
-gets the same `404` a stray ID gets, so the client has to `initialize` again. Each worker process
-holds at most `max_sessions` of them (default 10 000) and answers `503` to a request that would
-open one more. Both are `run()` / `streamable_http_app()` options.
+## Session lifetime and limits
+
+A legacy session does not live forever, and one process does not hold an unlimited number of
+them. Two settings control this. Both are keyword arguments on `run()`, `streamable_http_app()`
+and `Server.streamable_http_app()`. Modern (`2026-07-28`) connections and `stateless_http=True`
+have no sessions, so neither setting applies to them.
+
+| Setting | Default | What it does | What the client sees | Turn it off |
+|---|---|---|---|---|
+| `session_idle_timeout` | `1800` (30 min) | Closes a session that has had nothing in flight for that long. | `404 Session not found`. It has to `initialize` again. | `None` |
+| `max_sessions` | `10_000` | Refuses to open a session beyond that many. Existing sessions are untouched and nothing is evicted. | `503 Too many open sessions` with JSON-RPC code `-32603`. | `None` |
+
+What counts as "in flight":
+
+* An open `GET` stream. The SDK clients keep one open, so a connected client's session never
+  expires.
+* A request that is still being answered. A tool call that runs longer than the timeout is not
+  interrupted, and the countdown only starts once it finishes.
+* Nothing else. Between requests the clock runs. Any request on the session restarts it,
+  `ping` included. Once a session has expired, nothing revives it.
+
+A client that ends its session with `DELETE` frees it immediately. So does a client whose
+opening request was refused.
+
+```python
+mcp.run(transport="streamable-http", session_idle_timeout=None, max_sessions=50_000)
+```
+
+Both events show up in the server log. An expiry is `Session <id> idle timeout` at `INFO`. A
+refused open is `Refusing to open a new session: <n> sessions are already open` at `WARNING`.
+
+The limits are per process. With four workers the ceiling is four times `max_sessions`, and each
+worker expires its own sessions.
 
 ## The one knob: `stateless_http`
 

docs/troubleshooting.md

@@ -246,7 +246,7 @@ app = Starlette(routes=[Mount("/", app=mcp.streamable_http_app())], lifespan=lif
 
 ## `MCPError: Session not found`
 
-The server does not recognise the `Mcp-Session-Id` your client sent, because the server **restarted** (or you were routed to a different instance), or because the session **expired**: a legacy session with no request in flight for `session_idle_timeout` (30 minutes by default; an open `GET` stream or a request being answered counts as in flight) is closed, as is one the client ended with `DELETE`. Sessions live in that one process's memory.
+The server does not recognise the `Mcp-Session-Id` your client sent. Either the server **restarted** (or you were routed to a different instance), or the session **expired** because nothing was in flight for `session_idle_timeout`, which is 30 minutes by default. See [Session lifetime and limits](run/legacy-clients.md#session-lifetime-and-limits). Sessions live in that one process's memory.
 
 There is no server bug to find. The HTTP response is a `404` whose body *is* JSON-RPC, so, unlike the `421` above, the python `Client` shows you this one verbatim:
 

tests/docs_src/test_legacy_clients.py

@@ -79,8 +79,8 @@ async def test_a_legacy_session_is_minted_in_process_and_a_stray_session_id_is_a
 
 
 def test_legacy_sessions_expire_and_are_capped_by_default() -> None:
-    """The cost section: a session record is dropped after 30 idle minutes and each worker process holds at most
-    10 000 of them, unless `run()` / `streamable_http_app()` say otherwise."""
+    """The session lifetime section: a session is closed after 30 idle minutes and each worker process
+    holds at most 10 000 of them, unless `run()` / `streamable_http_app()` say otherwise."""
     server = MCPServer("Bookshop")
     server.streamable_http_app()
     assert server.session_manager.session_idle_timeout == 30 * 60