fix(server): settle in-flight JSON-mode requests and release their stream mappings (v1.x)

[lvyanyan]

Fixes #2559 (v1.x half — the main-branch close-settle half is drafted in #2584)

What

On v1.x, JSON response mode has two lifecycle gaps:

1. Leak: when all responses are ready, send() resolves the pending HTTP response but never runs the stream mapping's cleanup, so every completed POST leaves one _streamMapping entry behind until close(). Long-lived sessions accumulate one entry per request. (main got the equivalent fix in Implement MCP 2026-07-28 #2286; it was never carried to v1.x — as noted on the issue, this is what currently ships as 1.30.0.)
2. Hang: conversely, cleanup() only deleted the map entry without settling the Promise<Response> returned by handleRequest(). close() runs every mapping's cleanup, but for a JSON-mode POST still waiting on its handler that cleanup settled nothing — so the HTTP request hung until the client timed out.

Fix

• The JSON-ready branch of send() now calls stream.cleanup() right after resolving, mirroring main's Implement MCP 2026-07-28 #2286.
• The JSON-mode mapping's cleanup() now settles the pending POST with a 503 JSON-RPC error (-32000), aligned with the approach drafted for main in fix(server): settle in-flight JSON-mode requests on transport close #2584. On the success path send() has already resolved before cleanup() runs, and re-resolving a settled promise is a no-op, so the new resolve only fires when nothing was ever sent.

Tests

• settles an in-flight JSON-mode request when the transport closes mid-handler — the tool handler signals it has started, close() lands while it is genuinely parked, and the POST must resolve 503 with the JSON-RPC error payload instead of hanging.
• releases the JSON-mode stream mapping once the response has been sent — _streamMapping.size must be 0 after a completed JSON-mode POST (on unpatched v1.x this fails with 2: the request's mapping plus initialize's).

Both tests fail on unpatched v1.x and pass with the fix. Full suite: 1647 passed (the two unhandled stdio SyntaxErrors reproduce on pristine v1.x and are unrelated).

[changeset-bot]

🦋 Changeset detected

Latest commit: 24eae34

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@modelcontextprotocol/sdk@2747

commit: 24eae34

[claude]

Verified this locally against v1.x @ a9f6eb7 (the PR's base): with the fix, the two new tests pass (3/3 in the JSON-mode group); with src/server/webStandardStreamableHttp.ts reverted to base, both fail as described — the close-mid-handler POST hangs and _streamMapping retains 2 entries. Typecheck and ESLint are clean.

The red build check is only Prettier: .changeset/json-mode-lifecycle-v1x.md fails prettier --check .. Running npx prettier --write .changeset/json-mode-lifecycle-v1x.md and pushing should turn CI green (v1.x releases are versioned manually, so if maintainers prefer, dropping the changeset file entirely would also work).

---

Generated by Claude Code