From a1137b8e3be028baa193e4c03d396c6e78ec78ef Mon Sep 17 00:00:00 2001 From: cliffhall Date: Wed, 18 Nov 2026 13:02:15 -0500 Subject: [PATCH 1/3] feat(everything): evict idle Streamable HTTP sessions A 2025-era Streamable HTTP session holds a server instance, a transport and an event store until its client sends a DELETE. A client that initializes and goes away never does, so each abandoned session stayed in memory for the life of the process: about 90 KiB of heap apiece, with no bound. A session with no request in flight and no stream open for SESSION_IDLE_TIMEOUT_MILLIS (30 minutes by default; 0 disables it) is now closed by the server, which runs the same onclose path as a DELETE, so it is removed and its cleanup() runs. Its next request is answered 404 "Session not found", the spec's signal for the client to initialize again. A request counts as activity until its response closes, so a session with an open SSE stream or a running tool call is never evicted. The HTTP+SSE transport is unchanged: its session is its GET /sse stream, and it is already cleaned up when that stream's socket closes. 2026-07-28 requests have no sessions. Reported, with measurements, by Pierpaolo1223 on the issue. Closes #5558 Co-Authored-By: Claude Fable 5.2 Signed-off-by: cliffhall --- .changeset/everything-evict-idle-sessions.md | 5 + src/everything/README.md | 23 ++- .../__tests__/idle-sessions.test.ts | 180 ++++++++++++++++++ .../__tests__/streamable-http.test.ts | 144 ++++++++++++++ src/everything/docs/startup.md | 1 + src/everything/docs/structure.md | 5 + src/everything/transports/idle-sessions.ts | 128 +++++++++++++ src/everything/transports/streamableHttp.ts | 52 ++++- 8 files changed, 525 insertions(+), 13 deletions(-) create mode 100644 .changeset/everything-evict-idle-sessions.md create mode 100644 src/everything/__tests__/idle-sessions.test.ts create mode 100644 src/everything/transports/idle-sessions.ts diff --git a/.changeset/everything-evict-idle-sessions.md b/.changeset/everything-evict-idle-sessions.md new file mode 100644 index 0000000000..384480dff1 --- /dev/null +++ b/.changeset/everything-evict-idle-sessions.md @@ -0,0 +1,5 @@ +--- +"@modelcontextprotocol/server-everything": minor +--- + +The Streamable HTTP transport now evicts a 2025-era session that has been idle for 30 minutes: one with no request in flight and no stream open. Until now a session whose client never sent a DELETE stayed in memory, with its server instance, for the life of the process. An evicted session's next request is answered `404 Session not found`, the spec's signal for the client to initialize again. Set the new `SESSION_IDLE_TIMEOUT_MILLIS` environment variable to change the timeout, or to `0` to keep sessions until their client ends them. 2026-07-28 clients have no sessions and are unaffected. Thanks to @Pierpaolo1223 for the report and the measurements in [#5558](https://github.com/modelcontextprotocol/servers/issues/5558). diff --git a/src/everything/README.md b/src/everything/README.md index 0d597af143..cf16741774 100644 --- a/src/everything/README.md +++ b/src/everything/README.md @@ -32,12 +32,12 @@ Roots, sampling and logging are deprecated as of 2026-07-28 and stay available, The `gzip-file-as-resource` tool fetches the URL it is given, so these environment variables limit what it will fetch: -| Variable | Default | Effect | -| --- | --- | --- | -| `GZIP_MAX_FETCH_SIZE` | 10 MiB | The largest response, in bytes, it reads | -| `GZIP_MAX_FETCH_TIME_MILLIS` | 30000 | How long a fetch may take, redirects included | -| `GZIP_ALLOWED_DOMAINS` | empty (any name) | Comma-separated host names; a host must be one of them or a subdomain of one. Checked on the caller's URL and on every redirect hop | -| `GZIP_ALLOW_PRIVATE_IPS` | off | Set to `1` or `true` to allow loopback, private (RFC 1918), CGNAT, link-local (cloud metadata) and other non-public addresses | +| Variable | Default | Effect | +| ---------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `GZIP_MAX_FETCH_SIZE` | 10 MiB | The largest response, in bytes, it reads | +| `GZIP_MAX_FETCH_TIME_MILLIS` | 30000 | How long a fetch may take, redirects included | +| `GZIP_ALLOWED_DOMAINS` | empty (any name) | Comma-separated host names; a host must be one of them or a subdomain of one. Checked on the caller's URL and on every redirect hop | +| `GZIP_ALLOW_PRIVATE_IPS` | off | Set to `1` or `true` to allow loopback, private (RFC 1918), CGNAT, link-local (cloud metadata) and other non-public addresses | By default the tool refuses a URL whose host resolves to a non-public address, and follows at most five redirects, checking each hop the same way. An IPv6 address that wraps an IPv4 one (IPv4-mapped, IPv4-translated, or in the NAT64 prefix `64:ff9b::/96`) is judged by that IPv4, and any other IPv6 address outside global unicast (`2000::/3`) is refused. `GZIP_ALLOWED_DOMAINS` filters names, not addresses: a listed name that resolves to a private address is still refused unless `GZIP_ALLOW_PRIVATE_IPS` is set. The address is checked before the request and resolved again when it is made, so a DNS answer that changes in between (DNS rebinding) is not caught. `data:` URLs are not fetched, so neither check applies to them. @@ -129,10 +129,13 @@ The endpoint is `http://localhost:3001/mcp` (`PORT` overrides the port). It serv Both HTTP transports (Streamable HTTP and HTTP+SSE) listen on the loopback interface, `127.0.0.1`, by default, so only clients on the same machine can reach them. Set `HOST` to bind another address: `HOST=0.0.0.0` listens on every interface, which exposes the server's tools to every host that can reach the machine, so set it only on a network you trust. The listening line the server prints names the address and port it bound, such as `127.0.0.1:3001`. -| Variable | Default | Effect | -| --- | --- | --- | -| `PORT` | `3001` | The port the HTTP transport listens on | -| `HOST` | `127.0.0.1` | The address it binds; `0.0.0.0` (or `::`) for every interface | +| Variable | Default | Effect | +| ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------ | +| `PORT` | `3001` | The port the HTTP transport listens on | +| `HOST` | `127.0.0.1` | The address it binds; `0.0.0.0` (or `::`) for every interface | +| `SESSION_IDLE_TIMEOUT_MILLIS` | `1800000` (30 minutes) | Streamable HTTP only: how long a 2025-era session may sit idle before the server ends it; `0` never ends one | + +A 2025-era Streamable HTTP session normally ends when its client sends a `DELETE`. One whose client goes away without doing so is ended by the server once it has been idle for `SESSION_IDLE_TIMEOUT_MILLIS`: its server instance is closed and its timers and subscriptions are released. Idle means no request in flight and no stream open, so a client that keeps its `GET` stream open, or is waiting on a long tool call, is never timed out; the clock starts when the session's last response closes, and idle sessions are looked for every tenth of the timeout (no less than a second and no more than a minute apart), so one is ended that much late at most. A request for a session the server has ended is answered `404 Not Found` (`Session not found`), which is the [specification's signal](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) for the client to start a new session with a fresh `initialize`. Set a short timeout to exercise that path in a client under test, or `0` to keep every session until its client ends it. A value that is not a non-negative number is ignored in favor of the default. 2026-07-28 clients have no sessions, and an HTTP+SSE session ends when its stream's connection closes, so neither is affected. Both HTTP transports (Streamable HTTP and HTTP+SSE) accept browser requests only from a localhost origin: an `Origin` header whose host is `localhost`, `127.0.0.1` or `[::1]`, on any port, such as the MCP Inspector's. A request carrying any other `Origin` is refused with `403 Forbidden`. Clients that send no `Origin` header, which is every non-browser client, are unaffected. diff --git a/src/everything/__tests__/idle-sessions.test.ts b/src/everything/__tests__/idle-sessions.test.ts new file mode 100644 index 0000000000..b4729891ef --- /dev/null +++ b/src/everything/__tests__/idle-sessions.test.ts @@ -0,0 +1,180 @@ +/** + * The timing of idle-session eviction (#5558), with fake timers and no HTTP: + * what `SESSION_IDLE_TIMEOUT_MILLIS` is read as, that a session is evicted + * once, only after it has had no open response for the timeout, and that a + * timeout of 0 and `stop()` both end the watching. A response is an + * `EventEmitter` here, since "close" is all the module listens for. What + * eviction does to a real session is in `streamable-http.test.ts`. + */ +import { EventEmitter } from "node:events"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { + DEFAULT_SESSION_IDLE_TIMEOUT_MILLIS, + sessionIdleTimeoutMillis, + watchIdleSessions, +} from "../transports/idle-sessions.js"; + +describe("sessionIdleTimeoutMillis", () => { + afterEach(() => { + vi.unstubAllEnvs(); + }); + + it("defaults to 30 minutes", () => { + expect(DEFAULT_SESSION_IDLE_TIMEOUT_MILLIS).toBe(1_800_000); + expect(sessionIdleTimeoutMillis(undefined)).toBe(1_800_000); + }); + + it("reads SESSION_IDLE_TIMEOUT_MILLIS from the environment", () => { + vi.stubEnv("SESSION_IDLE_TIMEOUT_MILLIS", "5000"); + expect(sessionIdleTimeoutMillis()).toBe(5000); + }); + + it("takes a number of milliseconds, and 0 as disabled", () => { + expect(sessionIdleTimeoutMillis("60000")).toBe(60_000); + expect(sessionIdleTimeoutMillis(" 250 ")).toBe(250); + expect(sessionIdleTimeoutMillis("0")).toBe(0); + }); + + it.each(["", " ", "-1", "soon", "Infinity"])( + "falls back to the default for %j", + (value) => { + expect(sessionIdleTimeoutMillis(value)).toBe( + DEFAULT_SESSION_IDLE_TIMEOUT_MILLIS, + ); + }, + ); +}); + +describe("watchIdleSessions", () => { + beforeEach(() => { + vi.useFakeTimers(); + }); + + afterEach(() => { + vi.useRealTimers(); + }); + + it("evicts a session once, after it has been idle for the timeout", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(5000, evict); + idle.add("a"); + vi.advanceTimersByTime(4999); + expect(evict).not.toHaveBeenCalled(); + vi.advanceTimersByTime(1); + expect(evict).toHaveBeenCalledExactlyOnceWith("a"); + vi.advanceTimersByTime(60_000); + expect(evict).toHaveBeenCalledOnce(); + idle.stop(); + }); + + it("keeps a session with an open response, and times it from when the response closes", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(5000, evict); + idle.add("active"); + idle.add("abandoned"); + const stream = new EventEmitter(); + const call = new EventEmitter(); + idle.hold("active", stream); + idle.hold("active", call); + vi.advanceTimersByTime(5000); + expect(evict).toHaveBeenCalledExactlyOnceWith("abandoned"); + + // One of two responses closing leaves the session in use. + call.emit("close"); + vi.advanceTimersByTime(60_000); + expect(evict).toHaveBeenCalledOnce(); + + // The clock starts when the last one closes, not when it opened. + stream.emit("close"); + vi.advanceTimersByTime(4999); + expect(evict).toHaveBeenCalledOnce(); + vi.advanceTimersByTime(1); + expect(evict).toHaveBeenLastCalledWith("active"); + expect(evict).toHaveBeenCalledTimes(2); + idle.stop(); + }); + + it("restarts a session's clock on each request", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(5000, evict); + idle.add("a"); + for (let i = 0; i < 4; i++) { + vi.advanceTimersByTime(4000); + const res = new EventEmitter(); + idle.hold("a", res); + res.emit("close"); + } + expect(evict).not.toHaveBeenCalled(); + idle.stop(); + }); + + it("does not evict a session that was removed, or hold one it does not watch", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(5000, evict); + idle.add("ended"); + idle.remove("ended"); + const res = new EventEmitter(); + idle.hold("unknown", res); + expect(res.listenerCount("close")).toBe(0); + vi.advanceTimersByTime(60_000); + expect(evict).not.toHaveBeenCalled(); + idle.stop(); + }); + + it("looks for idle sessions every tenth of the timeout", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(50_000, evict); + // Idle from 2 s in: past the timeout at 52 s, and seen at the 55 s look. + vi.advanceTimersByTime(2000); + idle.add("a"); + vi.advanceTimersByTime(52_999); + expect(evict).not.toHaveBeenCalled(); + vi.advanceTimersByTime(1); + expect(evict).toHaveBeenCalledExactlyOnceWith("a"); + idle.stop(); + }); + + it("looks at least every minute, however long the timeout", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(30 * 60_000, evict); + vi.advanceTimersByTime(60_000); + idle.add("a"); + // Idle from 1:00, so past the timeout at 31:00, the next look. + vi.advanceTimersByTime(30 * 60_000 - 1); + expect(evict).not.toHaveBeenCalled(); + vi.advanceTimersByTime(1); + expect(evict).toHaveBeenCalledExactlyOnceWith("a"); + idle.stop(); + }); + + it("looks no more often than once a second when the timeout is shorter", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(10, evict); + idle.add("a"); + vi.advanceTimersByTime(999); + expect(evict).not.toHaveBeenCalled(); + vi.advanceTimersByTime(1); + expect(evict).toHaveBeenCalledExactlyOnceWith("a"); + idle.stop(); + }); + + it("never evicts, and runs no timer, when the timeout is 0", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(0, evict); + expect(vi.getTimerCount()).toBe(0); + idle.add("a"); + vi.advanceTimersByTime(24 * 60 * 60 * 1000); + expect(evict).not.toHaveBeenCalled(); + idle.stop(); + }); + + it("stops looking once stopped", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(5000, evict); + idle.add("a"); + idle.stop(); + expect(vi.getTimerCount()).toBe(0); + vi.advanceTimersByTime(60_000); + expect(evict).not.toHaveBeenCalled(); + }); +}); diff --git a/src/everything/__tests__/streamable-http.test.ts b/src/everything/__tests__/streamable-http.test.ts index 7a4043654a..b20e8cfc6a 100644 --- a/src/everything/__tests__/streamable-http.test.ts +++ b/src/everything/__tests__/streamable-http.test.ts @@ -18,6 +18,13 @@ * A browser request is served only from a localhost origin: the tests pin * that a foreign `Origin` is refused with a 403 and no CORS grant at every * route, preflights included, and that a localhost one is served. + * + * A 2025-era session left idle is evicted (#5558): the "idle sessions" block + * serves an app with a five-second idle timeout and moves a fake clock past + * it (only `setInterval` and `Date` are faked, so the HTTP round trips stay + * real), pinning that the abandoned session is closed, cleaned up and then + * answered 404 while one with an open stream is left alone. The timing rules + * themselves are in `idle-sessions.test.ts`. */ import type { Server } from "node:http"; import { once } from "node:events"; @@ -604,6 +611,143 @@ describe("shutdown", () => { }); }); +describe("idle sessions (#5558)", () => { + const IDLE = 5000; + const ping = { jsonrpc: "2.0", id: 7, method: "ping" }; + + /** Replace the default app with one whose sessions idle out after `timeout`. */ + async function serveWithIdleTimeout(timeout: number) { + await new Promise((resolve) => http.close(resolve)); + vi.useFakeTimers({ toFake: ["setInterval", "clearInterval", "Date"] }); + app = createApp({ sessionIdleTimeoutMillis: timeout }); + http = app.app.listen(0, "127.0.0.1"); + await once(http, "listening"); + const address = http.address(); + if (address === null || typeof address === "string") + throw new Error("no port"); + mcp = `http://127.0.0.1:${address.port}/mcp`; + } + + afterEach(() => { + vi.useRealTimers(); + }); + + it("evicts an abandoned session and releases what it held, leaving one with an open stream alone", async () => { + await serveWithIdleTimeout(IDLE); + const timers = vi.getTimerCount(); + + // The abandoned session starts a timer of its own, then goes quiet. + const abandoned = await rawInitialize(); + const toggled = await post( + { + jsonrpc: "2.0", + id: 2, + method: "tools/call", + params: { name: "toggle-simulated-logging", arguments: {} }, + }, + abandoned.sessionId, + ); + await toggled.text(); + expect(vi.getTimerCount()).toBe(timers + 1); + + // The active session keeps its standalone stream open and sends nothing. + const active = await rawInitialize(); + const controller = new AbortController(); + const stream = await fetch(mcp, { + headers: { + accept: "text/event-stream", + "mcp-session-id": active.sessionId, + "mcp-protocol-version": "2025-11-25", + }, + signal: controller.signal, + }); + expect(stream.status).toBe(200); + const timersBeforeEviction = vi.getTimerCount(); + + vi.advanceTimersByTime(IDLE); + await vi.waitFor(() => + expect(log).toHaveBeenCalledWith( + `Transport closed for session ${abandoned.sessionId}, removing from transports map`, + ), + ); + expect(log).toHaveBeenCalledWith( + `Session ${abandoned.sessionId} idle for ${IDLE} ms, closing it`, + ); + // Its cleanup ran: the simulated-logging timer is gone. + expect(vi.getTimerCount()).toBe(timersBeforeEviction - 1); + const evicted = await post(ping, abandoned.sessionId); + expect(evicted.status).toBe(404); + expect(await evicted.json()).toEqual({ ...SESSION_NOT_FOUND, id: 7 }); + + // The session with the open stream was idle just as long, and is served. + const kept = await post(ping, active.sessionId); + expect(kept.status).toBe(200); + await kept.text(); + expect(log).not.toHaveBeenCalledWith( + `Session ${active.sessionId} idle for ${IDLE} ms, closing it`, + ); + + // Once its stream closes it is idle too, and is evicted in its turn. + controller.abort(); + await vi.waitFor(() => { + vi.advanceTimersByTime(IDLE); + expect(log).toHaveBeenCalledWith( + `Transport closed for session ${active.sessionId}, removing from transports map`, + ); + }); + expect((await post(ping, active.sessionId)).status).toBe(404); + }); + + it("keeps a session that is still being used", async () => { + await serveWithIdleTimeout(IDLE); + const { sessionId } = await rawInitialize(); + for (let i = 0; i < 3; i++) { + vi.advanceTimersByTime(IDLE - 1000); + const response = await post(ping, sessionId); + expect(response.status).toBe(200); + await response.text(); + } + expect(log).not.toHaveBeenCalledWith( + `Session ${sessionId} idle for ${IDLE} ms, closing it`, + ); + }); + + it("evicts nothing when the timeout is 0", async () => { + await serveWithIdleTimeout(0); + expect(vi.getTimerCount()).toBe(0); + const { sessionId } = await rawInitialize(); + vi.advanceTimersByTime(24 * 60 * 60 * 1000); + const response = await post(ping, sessionId); + expect(response.status).toBe(200); + await response.text(); + }); + + it("logs an idle session that fails to close", async () => { + await serveWithIdleTimeout(IDLE); + const { sessionId } = await rawInitialize(); + const failure = new Error("close failed"); + vi.spyOn( + NodeStreamableHTTPServerTransport.prototype, + "close", + ).mockRejectedValueOnce(failure); + vi.advanceTimersByTime(IDLE); + await vi.waitFor(() => + expect(log).toHaveBeenCalledWith( + `Error closing idle session ${sessionId}:`, + failure, + ), + ); + }); + + it("stops looking for idle sessions on shutdown", async () => { + vi.spyOn(process, "exit").mockImplementation(() => undefined as never); + await serveWithIdleTimeout(IDLE); + expect(vi.getTimerCount()).toBe(1); + await app.shutdown(); + expect(vi.getTimerCount()).toBe(0); + }); +}); + describe("startStreamableHttpServer", () => { afterEach(() => { vi.doUnmock("../transports/listen.js"); diff --git a/src/everything/docs/startup.md b/src/everything/docs/startup.md index e93a85577b..bc0f6ba40a 100644 --- a/src/everything/docs/startup.md +++ b/src/everything/docs/startup.md @@ -34,6 +34,7 @@ - **Streamable HTTP**: one `/mcp` endpoint for both eras. - **2026-07-28**: a session-less **POST** carrying the per-request `_meta` envelope is served by the SDK's `createMcpHandler`, which builds a fresh server per request with `createServer({ era: "modern", publish })`. There are no sessions. Change notifications are published on the handler's subscription bus (`publish`), which reaches every open `subscriptions/listen` stream. - **2025 era**: everything else, classified by the SDK's `isLegacyRequest`, keeps the sessionful wiring: a server per session, created on the `initialize` **POST**, with **GET** for the standalone SSE stream and **DELETE** to end the session. Transports are stored by `sessionId`, an event store makes streams resumable, and the session's `cleanup()` runs when it closes. Sessionful serving keeps the server-to-client channel the legacy shim needs for elicitation, sampling and roots. + - A 2025-era session with no request in flight and no stream open for `SESSION_IDLE_TIMEOUT_MILLIS` (default 30 minutes; `0` disables it) is closed by the server, as if its client had sent the DELETE; its next request is answered `404`. - A session-less POST's body is parsed once (up to 4 MiB) to classify it and serve it. - **SSE** and **Streamable HTTP** bind their port (`PORT`, default `3001`) through `listenOrExit()` in `transports/listen.ts`. - The listening line is printed only once the port is bound. diff --git a/src/everything/docs/structure.md b/src/everything/docs/structure.md index 440702593f..a8a3601f4e 100644 --- a/src/everything/docs/structure.md +++ b/src/everything/docs/structure.md @@ -68,6 +68,7 @@ src/everything │ ├── trigger-sampling-request.ts │ └── trigger-url-elicitation.ts └── transports + ├── idle-sessions.ts ├── in-memory-event-store.ts ├── listen.ts ├── sse.ts @@ -228,6 +229,9 @@ src/everything ### `transports/` +- `idle-sessions.ts` + - `watchIdleSessions(timeoutMillis, evict)`: decides when a 2025-era Streamable HTTP session has been idle too long. A request counts as activity until its response closes, so an open stream or a running call keeps its session; `evict` is called once for a session with no open response for the timeout. + - `sessionIdleTimeoutMillis()`: reads `SESSION_IDLE_TIMEOUT_MILLIS` (default 30 minutes; `0` disables eviction). - `in-memory-event-store.ts` - `InMemoryEventStore`: the Streamable HTTP transport's event store for resumability. Replays only the events of the stream a `Last-Event-ID` belongs to, and reports an unknown event ID as having no stream, so the SDK refuses the resume. - `listen.ts` @@ -250,4 +254,5 @@ src/everything - 2025 era: POST (JSON‑RPC), GET (SSE stream), and DELETE (session termination) using `NodeStreamableHTTPServerTransport` from `@modelcontextprotocol/node`. - Uses an `InMemoryEventStore` for resumable sessions and tracks transports by `sessionId`. - Answers a request for an unknown or ended `Mcp-Session-Id` with `404 Not Found`, and closes every open session on `SIGINT`. + - Closes a session that has been idle for `SESSION_IDLE_TIMEOUT_MILLIS` (`idle-sessions.ts`), which removes it and runs its `cleanup()` as a DELETE does. - Connects a fresh server instance on initialization POST and reuses the transport for subsequent requests. diff --git a/src/everything/transports/idle-sessions.ts b/src/everything/transports/idle-sessions.ts new file mode 100644 index 0000000000..930455a61e --- /dev/null +++ b/src/everything/transports/idle-sessions.ts @@ -0,0 +1,128 @@ +// Idle-session eviction for the Streamable HTTP transport's 2025-era sessions +// (#5558). +// +// A 2025-era session holds a server instance, a transport and an event store +// until its client ends it with a DELETE. A client that initializes and then +// goes away never does, so without this every abandoned session stayed in +// memory for the life of the process. The spec lets a server end a session at +// any time, after which it answers that session id with 404 and the client +// starts a new one, so an idle session is closed after a timeout. +// +// "Idle" means no request in flight and no stream open: every request served +// for a session is held as activity until its response closes, so a session +// with an open SSE stream, or a tool call still running, is never evicted +// however long it has been quiet. The clock starts when the last response +// closes. +// +// This module only decides when; the transport manager supplies what evicting +// means (closing the session's transport). It is kept apart from +// `streamableHttp.ts` so the timing can be tested with fake timers and no +// HTTP. The HTTP+SSE transport needs none of this: its session is its +// `GET /sse` stream, and it is cleaned up when that stream's socket closes. + +/** How long a session may sit idle before it is evicted, by default: 30 minutes. */ +export const DEFAULT_SESSION_IDLE_TIMEOUT_MILLIS = 30 * 60 * 1000; + +/** + * Idle sessions are looked for every tenth of the timeout, so one is evicted + * at most a tenth late, but no less often than this ... + */ +const MAX_SWEEP_INTERVAL_MILLIS = 60 * 1000; + +/** ... and no more often than this, however short the timeout. */ +const MIN_SWEEP_INTERVAL_MILLIS = 1000; + +/** + * The idle timeout `SESSION_IDLE_TIMEOUT_MILLIS` asks for, in milliseconds: + * `0` disables eviction, and anything that is not a non-negative number + * (unset, empty, negative, not a number) means the default. + */ +export function sessionIdleTimeoutMillis( + value: string | undefined = process.env.SESSION_IDLE_TIMEOUT_MILLIS, +): number { + const millis = Number(value?.trim() || NaN); + return Number.isFinite(millis) && millis >= 0 + ? millis + : DEFAULT_SESSION_IDLE_TIMEOUT_MILLIS; +} + +/** The part of a response this module needs: to learn when it has closed. */ +export type ClosableResponse = { + once(event: "close", listener: () => void): unknown; +}; + +/** The sessions being watched for idleness. */ +export type IdleSessions = { + /** Start watching a session; it is idle from now. */ + add(sessionId: string): void; + /** Count a request as the session's activity until its response closes. */ + hold(sessionId: string, res: ClosableResponse): void; + /** Stop watching a session that has ended. */ + remove(sessionId: string): void; + /** Stop looking for idle sessions, for shutdown. */ + stop(): void; +}; + +type Activity = { + /** Requests whose responses are still open. */ + open: number; + /** When `open` last reached zero. */ + idleSince: number; +}; + +/** + * Watch sessions for idleness, calling `evict` once for each session that has + * had no open response for `timeoutMillis`. A session is checked on a timer + * (unref'd, so it never keeps the process alive) that fires every tenth of + * the timeout, kept between a second and a minute, so it is evicted within + * one such interval after its timeout. A `timeoutMillis` of `0` disables + * eviction: no timer runs and nothing is ever evicted. + */ +export function watchIdleSessions( + timeoutMillis: number, + evict: (sessionId: string) => void, +): IdleSessions { + const sessions = new Map(); + + const sweep = () => { + const now = Date.now(); + for (const [sessionId, activity] of [...sessions]) { + if (activity.open === 0 && now - activity.idleSince >= timeoutMillis) { + sessions.delete(sessionId); + evict(sessionId); + } + } + }; + + const timer = + timeoutMillis > 0 + ? setInterval( + sweep, + Math.max( + MIN_SWEEP_INTERVAL_MILLIS, + Math.min(timeoutMillis / 10, MAX_SWEEP_INTERVAL_MILLIS), + ), + ).unref() + : undefined; + + return { + add(sessionId) { + sessions.set(sessionId, { open: 0, idleSince: Date.now() }); + }, + hold(sessionId, res) { + const activity = sessions.get(sessionId); + if (!activity) return; + activity.open++; + res.once("close", () => { + activity.open--; + activity.idleSince = Date.now(); + }); + }, + remove(sessionId) { + sessions.delete(sessionId); + }, + stop() { + clearInterval(timer); + }, + }; +} diff --git a/src/everything/transports/streamableHttp.ts b/src/everything/transports/streamableHttp.ts index d5b9ac9510..5dc16e082e 100644 --- a/src/everything/transports/streamableHttp.ts +++ b/src/everything/transports/streamableHttp.ts @@ -20,6 +20,10 @@ // classified by the SDK's own `isLegacyRequest`, from a body parsed once and // handed to whichever side serves it. // +// A 2025-era session whose client never ends it is evicted once it has been +// idle for `SESSION_IDLE_TIMEOUT_MILLIS` (#5558); `idle-sessions.ts` holds the +// reasoning and decides when, and this file closes the transport. +// // `createApp()` builds the Express app without binding a port or installing a // signal handler (#4854), so a test can serve it on a free port, drive it with // a real client, and call its shutdown handler directly; each app has its own @@ -44,6 +48,10 @@ import { randomUUID } from "node:crypto"; import cors from "cors"; import { bindHost, hostAndPort, listenOrExit } from "./listen.js"; import { InMemoryEventStore } from "./in-memory-event-store.js"; +import { + sessionIdleTimeoutMillis, + watchIdleSessions, +} from "./idle-sessions.js"; /** The most bytes of a refused POST's body read to find its request id. */ const MAX_ID_BODY_BYTES = 64 * 1024; @@ -126,6 +134,16 @@ function bodyError( } } +/** What `createApp()` can be told; the launcher passes nothing. */ +export type StreamableHttpAppOptions = { + /** + * How long a 2025-era session may sit idle before it is evicted, in + * milliseconds; `0` disables eviction. Defaults to what + * `SESSION_IDLE_TIMEOUT_MILLIS` asks for. + */ + sessionIdleTimeoutMillis?: number; +}; + /** The Streamable HTTP app, and the handler the launcher installs for SIGINT. */ export type StreamableHttpApp = { app: Express; @@ -135,10 +153,12 @@ export type StreamableHttpApp = { /** * Build the Streamable HTTP transport's Express app: Origin validation, CORS, * the `/mcp` POST, GET and DELETE routes, the map from session id to - * transport that they share, the 2026-07-28 handler, and the shutdown handler - * that closes them. + * transport that they share, the eviction of idle sessions from it, the + * 2026-07-28 handler, and the shutdown handler that closes them. */ -export function createApp(): StreamableHttpApp { +export function createApp( + options: StreamableHttpAppOptions = {}, +): StreamableHttpApp { const app = express(); // A browser page may reach this server only from a localhost origin. The // SDK's guard answers any other Origin with a 403 before a route or the @@ -191,6 +211,23 @@ export function createApp(): StreamableHttpApp { NodeStreamableHTTPServerTransport >(); + // A session nobody has used for the idle timeout is closed, which runs its + // onclose below, so it is removed and cleaned up as a DELETE would have. + // Its next request is answered 404, the client's signal to initialize again. + const idleTimeoutMillis = + options.sessionIdleTimeoutMillis ?? sessionIdleTimeoutMillis(); + const idle = watchIdleSessions(idleTimeoutMillis, (sessionId) => { + console.log( + `Session ${sessionId} idle for ${idleTimeoutMillis} ms, closing it`, + ); + transports + .get(sessionId) + ?.close() + .catch((error: unknown) => + console.log(`Error closing idle session ${sessionId}:`, error), + ); + }); + // A session-less POST's body is parsed once, to classify it and serve it. // A POST with a session id is a 2025-era session's, and its transport reads // the body itself. @@ -236,6 +273,7 @@ export function createApp(): StreamableHttpApp { // This avoids race conditions where requests might come in before the session is stored console.log(`Session initialized with ID: ${sessionId}`); transports.set(sessionId, transport); + idle.add(sessionId); }, }); @@ -247,6 +285,7 @@ export function createApp(): StreamableHttpApp { `Transport closed for session ${sid}, removing from transports map`, ); transports.delete(sid); + idle.remove(sid); cleanup(); } }; @@ -264,6 +303,8 @@ export function createApp(): StreamableHttpApp { // Handle the request with existing transport - no need to reconnect // The existing transport is already connected to the server + // (a request in flight keeps its session from being evicted as idle) + idle.hold(sessionId, res); await transport.handleRequest(req, res); } catch (error) { console.log("Error handling MCP request:", error); @@ -309,6 +350,8 @@ export function createApp(): StreamableHttpApp { console.log(`Establishing new SSE stream for session ${sessionId}`); } + // The session is in use for as long as this stream stays open + idle.hold(sessionId, res); const transport = transports.get(sessionId); await transport!.handleRequest(req, res); }); @@ -359,6 +402,9 @@ export function createApp(): StreamableHttpApp { const shutdown = async () => { console.log("Shutting down server..."); + // Stop looking for idle sessions: every session is closed below + idle.stop(); + // End the 2026-07-28 requests and subscription streams in flight await modern.close(); From 780f0c97abcd7ceae70d238ff02cdecd7dec1a9f Mon Sep 17 00:00:00 2001 From: cliffhall Date: Wed, 18 Nov 2026 14:40:51 -0500 Subject: [PATCH 2/3] docs(everything): keep the README tables' form and link the reporter without a mention The idle-session change had re-aligned both environment-variable tables in the README, which Markdown is not formatted for in this repo, so the diff touched the unrelated GZIP table. The tables are back in their existing form, with only the SESSION_IDLE_TIMEOUT_MILLIS row added. The changeset credits the reporter with a profile link rather than a bare mention, which would notify them from the changelog and from every regeneration of the Version Packages PR. Part of #5558 Co-Authored-By: Claude Fable 5.2 Signed-off-by: cliffhall --- .changeset/everything-evict-idle-sessions.md | 2 +- src/everything/README.md | 20 ++++++++++---------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.changeset/everything-evict-idle-sessions.md b/.changeset/everything-evict-idle-sessions.md index 384480dff1..e8fca08a5c 100644 --- a/.changeset/everything-evict-idle-sessions.md +++ b/.changeset/everything-evict-idle-sessions.md @@ -2,4 +2,4 @@ "@modelcontextprotocol/server-everything": minor --- -The Streamable HTTP transport now evicts a 2025-era session that has been idle for 30 minutes: one with no request in flight and no stream open. Until now a session whose client never sent a DELETE stayed in memory, with its server instance, for the life of the process. An evicted session's next request is answered `404 Session not found`, the spec's signal for the client to initialize again. Set the new `SESSION_IDLE_TIMEOUT_MILLIS` environment variable to change the timeout, or to `0` to keep sessions until their client ends them. 2026-07-28 clients have no sessions and are unaffected. Thanks to @Pierpaolo1223 for the report and the measurements in [#5558](https://github.com/modelcontextprotocol/servers/issues/5558). +The Streamable HTTP transport now evicts a 2025-era session that has been idle for 30 minutes: one with no request in flight and no stream open. Until now a session whose client never sent a DELETE stayed in memory, with its server instance, for the life of the process. An evicted session's next request is answered `404 Session not found`, the spec's signal for the client to initialize again. Set the new `SESSION_IDLE_TIMEOUT_MILLIS` environment variable to change the timeout, or to `0` to keep sessions until their client ends them. 2026-07-28 clients have no sessions and are unaffected. Thanks to [Pierpaolo1223](https://github.com/Pierpaolo1223) for the report and the measurements in [#5558](https://github.com/modelcontextprotocol/servers/issues/5558). diff --git a/src/everything/README.md b/src/everything/README.md index cf16741774..2258954702 100644 --- a/src/everything/README.md +++ b/src/everything/README.md @@ -32,12 +32,12 @@ Roots, sampling and logging are deprecated as of 2026-07-28 and stay available, The `gzip-file-as-resource` tool fetches the URL it is given, so these environment variables limit what it will fetch: -| Variable | Default | Effect | -| ---------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `GZIP_MAX_FETCH_SIZE` | 10 MiB | The largest response, in bytes, it reads | -| `GZIP_MAX_FETCH_TIME_MILLIS` | 30000 | How long a fetch may take, redirects included | -| `GZIP_ALLOWED_DOMAINS` | empty (any name) | Comma-separated host names; a host must be one of them or a subdomain of one. Checked on the caller's URL and on every redirect hop | -| `GZIP_ALLOW_PRIVATE_IPS` | off | Set to `1` or `true` to allow loopback, private (RFC 1918), CGNAT, link-local (cloud metadata) and other non-public addresses | +| Variable | Default | Effect | +| --- | --- | --- | +| `GZIP_MAX_FETCH_SIZE` | 10 MiB | The largest response, in bytes, it reads | +| `GZIP_MAX_FETCH_TIME_MILLIS` | 30000 | How long a fetch may take, redirects included | +| `GZIP_ALLOWED_DOMAINS` | empty (any name) | Comma-separated host names; a host must be one of them or a subdomain of one. Checked on the caller's URL and on every redirect hop | +| `GZIP_ALLOW_PRIVATE_IPS` | off | Set to `1` or `true` to allow loopback, private (RFC 1918), CGNAT, link-local (cloud metadata) and other non-public addresses | By default the tool refuses a URL whose host resolves to a non-public address, and follows at most five redirects, checking each hop the same way. An IPv6 address that wraps an IPv4 one (IPv4-mapped, IPv4-translated, or in the NAT64 prefix `64:ff9b::/96`) is judged by that IPv4, and any other IPv6 address outside global unicast (`2000::/3`) is refused. `GZIP_ALLOWED_DOMAINS` filters names, not addresses: a listed name that resolves to a private address is still refused unless `GZIP_ALLOW_PRIVATE_IPS` is set. The address is checked before the request and resolved again when it is made, so a DNS answer that changes in between (DNS rebinding) is not caught. `data:` URLs are not fetched, so neither check applies to them. @@ -129,10 +129,10 @@ The endpoint is `http://localhost:3001/mcp` (`PORT` overrides the port). It serv Both HTTP transports (Streamable HTTP and HTTP+SSE) listen on the loopback interface, `127.0.0.1`, by default, so only clients on the same machine can reach them. Set `HOST` to bind another address: `HOST=0.0.0.0` listens on every interface, which exposes the server's tools to every host that can reach the machine, so set it only on a network you trust. The listening line the server prints names the address and port it bound, such as `127.0.0.1:3001`. -| Variable | Default | Effect | -| ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------ | -| `PORT` | `3001` | The port the HTTP transport listens on | -| `HOST` | `127.0.0.1` | The address it binds; `0.0.0.0` (or `::`) for every interface | +| Variable | Default | Effect | +| --- | --- | --- | +| `PORT` | `3001` | The port the HTTP transport listens on | +| `HOST` | `127.0.0.1` | The address it binds; `0.0.0.0` (or `::`) for every interface | | `SESSION_IDLE_TIMEOUT_MILLIS` | `1800000` (30 minutes) | Streamable HTTP only: how long a 2025-era session may sit idle before the server ends it; `0` never ends one | A 2025-era Streamable HTTP session normally ends when its client sends a `DELETE`. One whose client goes away without doing so is ended by the server once it has been idle for `SESSION_IDLE_TIMEOUT_MILLIS`: its server instance is closed and its timers and subscriptions are released. Idle means no request in flight and no stream open, so a client that keeps its `GET` stream open, or is waiting on a long tool call, is never timed out; the clock starts when the session's last response closes, and idle sessions are looked for every tenth of the timeout (no less than a second and no more than a minute apart), so one is ended that much late at most. A request for a session the server has ended is answered `404 Not Found` (`Session not found`), which is the [specification's signal](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) for the client to start a new session with a fresh `initialize`. Set a short timeout to exercise that path in a client under test, or `0` to keep every session until its client ends it. A value that is not a non-negative number is ignored in favor of the default. 2026-07-28 clients have no sessions, and an HTTP+SSE session ends when its stream's connection closes, so neither is affected. From c8e998e9872a9f21208e543c5044abc70ef07cba Mon Sep 17 00:00:00 2001 From: cliffhall Date: Wed, 18 Nov 2026 15:13:11 -0500 Subject: [PATCH 3/3] fix(everything): retry an idle session whose close failed When closing an idle session's transport rejected, the session stayed in the transport map but was no longer watched, so no later look tried it again and it was kept until a DELETE or shutdown: the retention this change removes. The session is now watched again after a failed close, so it is tried again after another idle timeout. The test for the failure now also checks that the session is still served, and is evicted at the next timeout. Part of #5558 Co-Authored-By: Claude Fable 5.2 Signed-off-by: cliffhall --- src/everything/__tests__/streamable-http.test.ts | 15 ++++++++++++++- src/everything/transports/streamableHttp.ts | 10 +++++++--- 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/src/everything/__tests__/streamable-http.test.ts b/src/everything/__tests__/streamable-http.test.ts index b20e8cfc6a..61bd68f883 100644 --- a/src/everything/__tests__/streamable-http.test.ts +++ b/src/everything/__tests__/streamable-http.test.ts @@ -722,7 +722,7 @@ describe("idle sessions (#5558)", () => { await response.text(); }); - it("logs an idle session that fails to close", async () => { + it("logs an idle session that fails to close, and evicts it at a later look", async () => { await serveWithIdleTimeout(IDLE); const { sessionId } = await rawInitialize(); const failure = new Error("close failed"); @@ -737,6 +737,19 @@ describe("idle sessions (#5558)", () => { failure, ), ); + // The failed close left the session in place, and still served. + const held = await post(ping, sessionId); + expect(held.status).toBe(200); + await held.text(); + + // It is watched again, so the next timeout closes it for real. + await vi.waitFor(() => { + vi.advanceTimersByTime(IDLE); + expect(log).toHaveBeenCalledWith( + `Transport closed for session ${sessionId}, removing from transports map`, + ); + }); + expect((await post(ping, sessionId)).status).toBe(404); }); it("stops looking for idle sessions on shutdown", async () => { diff --git a/src/everything/transports/streamableHttp.ts b/src/everything/transports/streamableHttp.ts index 5dc16e082e..003f4b9cae 100644 --- a/src/everything/transports/streamableHttp.ts +++ b/src/everything/transports/streamableHttp.ts @@ -223,9 +223,13 @@ export function createApp( transports .get(sessionId) ?.close() - .catch((error: unknown) => - console.log(`Error closing idle session ${sessionId}:`, error), - ); + .catch((error: unknown) => { + console.log(`Error closing idle session ${sessionId}:`, error); + // The session is still held, so watch it again: it is tried again + // after another timeout rather than kept for good. (If it did end, + // that later look finds no transport and just forgets it.) + idle.add(sessionId); + }); }); // A session-less POST's body is parsed once, to classify it and serve it.