feat: Add SessionStore interface for distributed session management

[stefanskiasan]

Summary

This PR adds native support for distributed session storage in the MCP SDK, enabling multi-pod/multi-node deployments where session state must be shared across server instances.

The Problem

The official @modelcontextprotocol/sdk stores session state in-memory:

// Original SDK - sessions are local to each process private _initialized: boolean = false; sessionId?: string;

This means:

• Sessions cannot be shared across multiple pods/containers
• Load balancers routing requests to different instances will fail
• Sessions are lost on server restart

The Solution

This PR introduces:

1. SessionStore interface - Abstract interface for external session storage
2. SessionData interface - Session metadata structure
3. SessionStorageMode type - Explicit mode selection ('memory' | 'external')
4. RedisSessionStore - Production-ready Redis implementation
5. InMemorySessionStore - For development/testing

Usage

// Single-pod mode (default) - sessions in memory const singlePodTransport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), sessionStorageMode: 'memory' // This is the default }); // Multi-pod mode - sessions in Redis const multiPodTransport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), sessionStorageMode: 'external', // Explicit mode selection sessionStore: new RedisSessionStore({ redis: new Redis(), ttlSeconds: 3600 }) });

Key Features

• Backward compatible - Default behavior unchanged when no sessionStore provided
• Explicit mode configuration - Clear distinction between memory and external modes
• Cross-pod session recovery - Sessions automatically recovered from external store
• Automatic TTL refresh - Session activity updates refresh TTL
• Type-safe - Full TypeScript support with exported interfaces
• Comprehensive tests - Unit and integration tests for all new functionality

Files Changed

• src/server/streamableHttp.ts - Core SessionStore integration
• src/server/index.ts - Export new types and classes
• src/server/session-stores/redis.ts - Redis and InMemory implementations
• src/server/session-stores/index.ts - Re-exports
• src/server/streamableHttp.test.ts - Integration tests
• src/server/session-stores/redis.test.ts - Unit tests

Test plan

• All 1458 existing SDK tests pass
• New unit tests for RedisSessionStore (19 tests)
• New unit tests for InMemorySessionStore (included in above)
• New integration tests for SessionStore with StreamableHTTPServerTransport
• Cross-pod session recovery simulation test
• Build succeeds for both ESM and CJS

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@anthropic-advisori/mcp-sdk@1193 

commit: c258d9f