mcp-session-store

Pluggable session backends so MCP servers can scale horizontally.

MCP's Streamable HTTP transport is stateful each session is tied to a server instance. This fights load balancers. Scaling an MCP server typically means writing custom Redis plumbing. mcp-session-store solves this by shipping battle-tested session backends with encryption, distributed locks, and pub/sub.

Installation

# Core package
npm install @siddharthasingh/mcp-session-store

# Pick a backend
npm install @siddharthasingh/mcp-session-store-redis
# or postgres, dynamodb, cloudflare-kv

Quick Start

import { createSessionStore } from '@siddharthasingh/mcp-session-store';
import { redis } from '@siddharthasingh/mcp-session-store-redis';

const store = createSessionStore({
  backend: redis({ url: 'redis://localhost:6379' }),
  ttl: 3600,
  encryption: { key: process.env.SESSION_ENCRYPTION_KEY }, // Automatic AEAD encryption
  pubsub: true,                 // Cross-instance eventing
  locks: true,                  // Distributed locking for tool calls
});

// Plug into your MCP server framework
server.useSessionStore(store);

Supported Backends

1. Memory: The default for local development. Fast, but state is lost on restart.
2. Redis: The standard for production. Uses Pub/Sub for cross-instance communication and SET NX PX for distributed locks.
3. Postgres: Uses LISTEN/NOTIFY for pub/sub, advisory locks for distributed locking, and ON CONFLICT for robust upserts.
4. DynamoDB: Leverages native TTL and conditional writes for robust cloud-native scaling.
5. Cloudflare KV: Edge-friendly backend optimized for worker environments.

Core Features

• AEAD Encryption: Session state is automatically encrypted before hitting the backend.
• Distributed Locks: Prevent race conditions when multiple instances try to update the same session concurrently.
• Pub/Sub Support: Ensure that server events sent to a session reach the client, even if they are connected to a different instance behind a load balancer.

License

MIT