Return 404 for unknown or expired MCP session IDs

[jpr5]

Summary

An unknown or expired Mcp-Session-Id on POST, GET and DELETE /mcp now returns 404 with JSON-RPC code -32001 "Session not found", as the MCP spec requires. Before this change it returned 400 or 405. An initialize request that carries a stale header now starts a new session.

Effect: after a Railway redeploy, Claude Code now re-initializes by itself. Before, it failed and told the user to run /mcp.

Changes

• dfff5c7 Answer 404 to an unknown or expired Mcp-Session-Id on POST, GET and DELETE /mcp so clients re-initialize
• 22b77e7 Count unknown-session 404s per method and log the totals on the reaper tick and at shutdown
• 996eb0e Return {server, stop} from startServer and add an in-process test server helper
• 3e9b7f5 Add route-level tests for the /mcp unknown-session 404

Also worth calling out:

• Session lookup is own-key, so ids like constructor return 404 instead of 500.
• The POST 404 echoes the request id.
• Unknown-session 404s are counted per method and logged as one line on the 5-minute reaper tick and at shutdown, for example [mcp] 404 unknown-session-id window_s=… total=… GET=… POST=… DELETE=…. No client bytes are logged.
• DELETE with no header now says "Missing session ID".
• startServer now returns {server, stop}. The in-process route tests use this seam.

Local red-green proof

RED = base 9d6f5e4. GREEN = final HEAD 264faf571fa598a2a87583f29470276a9edaf51f. Same harness for both (Pathfinder on :3001, deploy/pathfinder-docs.yaml). Fake session id: deadbeef-0000-4000-8000-000000000000. Raw GREEN run: p1-green-final2.txt.

Rows that differ from the earlier expectation: 5c (DELETE, no sid) keeps status 400 but the body message is now "Missing session ID" (RED: "Invalid or missing session ID"). The route test mcp-unknown-session-404-routes.test.ts pins this text. All other rows match.

Case	RED observed	GREEN observed	Expected	Pass/fail
1. POST tools/list (id 1), fake sid	400 Bad Request, -32000 "Bad Request: No valid session. Send an initialize request first.", id:null	404 Not Found, {"code":-32001,"message":"Session not found"}, id:1	404 with the target body	PASS
2. POST initialize, fake sid	400 Bad Request, -32000 "Bad Request: No valid session. Send an initialize request first."	200 OK, new header mcp-session-id: 4ab724d4-4a0a-4ac8-b54f-43a9ca38abe7	200 with a new mcp-session-id response header	PASS
3. GET, fake sid	405 Method Not Allowed, -32000 "Method Not Allowed"	404 Not Found, -32001 "Session not found", id:null	404 with the target body	PASS
4. DELETE, fake sid	400 Bad Request, -32000 "Invalid or missing session ID"	404 Not Found, -32001 "Session not found", id:null	404 with the target body	PASS
5a. POST tools/list, no sid	400 Bad Request, -32000 "Bad Request: No valid session. Send an initialize request first."	same as RED	Same as RED	PASS
5b. GET, no sid	405 Method Not Allowed, -32000 "Method Not Allowed"	same as RED	Same as RED	PASS
5c. DELETE, no sid	400 Bad Request, -32000 "Invalid or missing session ID"	400 Bad Request, -32000 "Missing session ID"	Status 400	PASS on status; body text differs (pinned by route test)
6. POST server/discover (modern probe)	400 Bad Request, -32000 "Bad Request: No valid session. Send an initialize request first."	same as RED	Same as RED	PASS
7a. POST tools/list, prototype key Mcp-Session-Id: constructor	not run on RED	404, -32001 "Session not found", id:1	404 (own-key lookup, not a prototype hit)	PASS
7b. GET, Mcp-Session-Id: constructor	not run on RED	404, -32001 "Session not found"	404	PASS
7c. DELETE, Mcp-Session-Id: constructor	not run on RED	404, -32001 "Session not found"	404	PASS
8. POST tools/list with "id":42, junk sid	not run on RED (RED returned id:null for case 1)	404, -32001 "Session not found", "id":42	id echoed back	PASS
SDK v1 client (@modelcontextprotocol/sdk@1.31.0), second listTools after server restart	StreamableHTTPError code 400: Error POSTing to endpoint: {"jsonrpc":"2.0","error":{"code":-32000,"message":"Bad Request: No valid session. Send an initialize request first."},"id":null}	StreamableHTTPError code 404: Error POSTing to endpoint: {"jsonrpc":"2.0","error":{"code":-32001,"message":"Session not found"},"id":2}. The SSE reconnect GET also got 404.	Server returns 404 for the unknown session	PASS
Claude Code 2.1.287, second search-docs call after server restart	Tool result Error POSTing to endpoint: {"jsonrpc":"2.0","error":{"code":-32000,"message":"Bad Request: No valid session. Send an initialize request first."},"id":null}. One POST in the server log, no New session, no second initialize. The model told the user to reconnect with /mcp.	Server logged 3 new sessions (86d4de81, 75c446b7, 6454960b) after the restart. search-docs("hello") reached the server with no user action. Result was Error: Search failed. Please try again later. (app-level, dummy OpenAI key). Server flush: 404 unknown-session-id window_s=11 total=3 GET=2 POST=1 DELETE=0.	Re-initializes after the 404 and the call reaches the server without user action	PASS
Flush line on SIGTERM	RED has no counter and no flush line	[mcp] 404 unknown-session-id window_s=11 total=3 GET=2 POST=1 DELETE=0, logged right after [shutdown] Received SIGTERM (the curl-phase server: window_s=25 total=7 GET=2 POST=3 DELETE=2, matching the 7 curl 404s; the v1-phase server: window_s=15 total=2 GET=1 POST=1 DELETE=0)	One line per method counts, emitted on shutdown	PASS

SDK v1 client behaviour (a fact, not a FAIL): after the 404 the v1 client did not re-initialize by itself. sessionId AFTER equals the session id before the call (7ccc905c-f7fa-41a8-ab13-518b47b883ca), listTools#2 ended in ERROR, and the transport closed. In RED it behaved the same way. The spec requires only the 404 from the server.

Notes

• tmux was not installed on this machine, so a non-interactive Claude Code driver was used for both RED and GREEN: claude -p --input-format stream-json, one process, two user turns over a FIFO, so the MCP connection persists across the restart. There are no pane captures. The driver is the same for both runs. The GREEN run used p1-cc-final2.sh, a copy of p1-cc-green.sh with only the output paths changed and the server log opened in append mode.
• OPENAI_API_KEY was the dummy sk-dummy-p1. search-docs therefore returned Error: Search failed. Please try again later. in both RED and GREEN. This is an app-level error, not a session error.
• The SDK v1 client throws on 404 and leaves re-init to the caller. That is client behaviour, not a server defect.
• Claude Code: the 404 status was seen server-side only. The client-side status was not captured in the stream.

The proof ran on 264faf5, whose tree is identical to this head after the commit regroup.

Client behaviour note

The SDK v1 StreamableHTTPClientTransport throws on 404 and leaves re-initialize to the caller. That is client behaviour; the server now does what the spec requires.

Tests

4032 passing. tsc, build, prettier (CI globs), test-shape and version-sync are all clean.

Follow-ups (not in this PR)

• /messages with a prototype-key session id returns 500 at src/sse-handlers.ts:410 (live-probed with constructor, __proto__, toString, hasOwnProperty). Same class as the own-key fix here. Next fix candidate.
• The server error handler exits 0 on bind failure; it should exit non-zero.
• static-quality.yml uses an unpinned prettier, CI runs Node 24 only, and comment lines 22-24 are stale.
• package.json engines says >=20 but deps need >=20.19.0; there is no files field.
• Three stale ensureSession comments outside this diff.
• sse-transport.test.ts is flaky under full-suite load.

Context

This is phase P1 of the stateless-MCP migration plan: https://www.notion.so/3ed3aa38185281d89892e2c4a20ed154

🤖 Generated with Claude Code

https://claude.ai/code/session_01EDxYQLKhDxwoYe8GV2noDY