Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/everything-evict-idle-sessions.md
Original file line number Diff line number Diff line change
@@ -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](https://github.com/Pierpaolo1223) for the report and the measurements in [#5558](https://github.com/modelcontextprotocol/servers/issues/5558).
3 changes: 3 additions & 0 deletions src/everything/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,9 @@ Both HTTP transports (Streamable HTTP and HTTP+SSE) listen on the loopback inter
| --- | --- | --- |
| `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.

Expand Down
180 changes: 180 additions & 0 deletions src/everything/__tests__/idle-sessions.test.ts
Original file line number Diff line number Diff line change
@@ -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();
});
});
157 changes: 157 additions & 0 deletions src/everything/__tests__/streamable-http.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down Expand Up @@ -604,6 +611,156 @@ 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, and evicts it at a later look", 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,
),
);
// 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 () => {
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");
Expand Down
1 change: 1 addition & 0 deletions src/everything/docs/startup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
5 changes: 5 additions & 0 deletions src/everything/docs/structure.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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`
Expand All @@ -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.
Loading
Loading