fix(client): handle HTTP 410 Gone for expired/stale MCP sessions

[joseairosa]

Summary

This PR adds proper handling for HTTP 410 Gone responses in StreamableHTTPClientTransport, enabling seamless reconnection when MCP sessions expire or servers restart.

Problem

When an MCP server restarts or a session times out, the server returns HTTP 410 Gone to indicate the session ID is no longer valid. Currently, the client:

1. Throws an error on 410
2. Retains the stale session ID in _sessionId
3. Sends the same invalid session ID on all subsequent requests
4. Gets 410 repeatedly, breaking the connection permanently

This creates a poor user experience where MCP connections become permanently broken after server restarts, requiring users to manually restart their client applications.

Real-world scenario

Client                          Server
  |                               |
  |-- POST (session: abc-123) --->|
  |                               | (server restarts, session gone)
  |<-------- 410 Gone ------------|
  |                               |
  |-- POST (session: abc-123) --->|  <- Still sending stale ID!
  |<-------- 410 Gone ------------|
  |                               |
  |-- POST (session: abc-123) --->|  <- Stuck in loop
  |<-------- 410 Gone ------------|
  ...forever...

Solution

Handle 410 responses by:

1. Clearing the stale _sessionId
2. Automatically retrying the request
3. Server assigns a new session ID on the retry

This follows the same pattern already used for 401 (auth) and 403 (scope) responses.

After this fix

Client                          Server
  |                               |
  |-- POST (session: abc-123) --->|
  |                               | (server restarts, session gone)
  |<-------- 410 Gone ------------|
  |                               |
  |-- POST (no session ID) ------>|  <- Retry without stale ID
  |<-- 200 OK (session: xyz-789) -|  <- New session assigned
  |                               |
  |-- POST (session: xyz-789) --->|  <- Working again!
  |<-------- 200 OK --------------|

Changes

• send() method: Added 410 handling that clears session ID and retries POST requests
• _startOrAuthSse() method: Added 410 handling that clears session ID and retries SSE GET connections
• Tests: Added comprehensive tests for both POST and GET 410 scenarios

Testing

All existing tests pass, plus 2 new tests:

• should clear session ID and retry on 410 during POST request
• should clear session ID and retry on 410 during SSE GET request

cd packages/client && pnpm test
# ✓ 42 tests passed

Related

This complements the server-side behavior where servers should return 410 Gone for expired sessions, as documented in the MCP Streamable HTTP transport specification.

[changeset-bot]

🦋 Changeset detected

Latest commit: b4124d1

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

This PR includes changesets to release 1 package

Name	Type
@modelcontextprotocol/client	Patch

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

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1402

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1402

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1402

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1402

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1402

commit: b4124d1

[felixweinberger]

Thanks for this! A few thoughts:

1. Did you encounter this 410 in the wild with a real server? The spec says servers should return HTTP 404 for expired sessions and doesn't mention 410.

2. Should we add a guard against infinite recursion, similar to _hasCompletedAuthFlow for 401? While unlikely with a well-behaved server, it matches the existing defensive pattern.

3. Per spec: "When a client receives HTTP 404 in response to a request containing an MCP-Session-Id, it MUST start a new session by sending a new InitializeRequest". Just retrying the original message (e.g., a tools/call) won't work - should this trigger a full re-initialization flow instead?