Storage Backends

The library supports multiple storage backends for session persistence, allowing you to choose the best option for your deployment environment.

Available Backends

Redis (Production)

Recommended for production and serverless deployments.

Redis provides distributed, persistent storage with automatic TTL (Time To Live) management. Perfect for:

• Production environments
• Serverless deployments (Vercel, AWS Lambda)
• Multi-instance applications
• High-availability setups

Installation:

npm install @mcp-ts/sdk ioredis

Configuration:

# Explicit selection (optional)
MCP_TS_STORAGE_TYPE=redis

# Redis connection URL (required)
REDIS_URL=redis://localhost:6379

# Or for cloud Redis with TLS
REDIS_URL=rediss://default:password@host.upstash.io:6379

Features:

• Automatic session expiration (12 hours TTL)
• Atomic operations for data consistency
• Distributed storage across instances
• Production-ready scalability

Usage:

import { storage } from '@mcp-ts/sdk/server';

// Storage automatically uses Redis when REDIS_URL is set
const sessionId = storage.generateSessionId();

await storage.createSession({
  sessionId,
  identity: 'user-123',
  serverUrl: 'https://mcp.example.com',
  callbackUrl: 'https://app.com/callback',
  transportType: 'sse',
  active: true,
  createdAt: Date.now(),
});

---

File System (Development)

Perfect for local development with persistent sessions across restarts.

File storage persists sessions to a JSON file on disk. Ideal for:

• Local development
• Single-instance deployments
• Testing with persistent state
• Environments without Redis

Configuration:

# Explicit selection (optional)
MCP_TS_STORAGE_TYPE=file

# File path for session storage (required)
MCP_TS_STORAGE_FILE=./sessions.json

Features:

• Persistent across application restarts
• No external dependencies
• Human-readable JSON format
• Automatic directory creation

Usage:

import { storage } from '@mcp-ts/sdk/server';

// Storage automatically uses File when MCP_TS_STORAGE_FILE is set
const sessions = await storage.getIdentitySessionsData('user-123');
console.log('Stored sessions:', sessions);

File Format:

[
  {
    "sessionId": "abc123",
    "identity": "user-123",
    "serverId": "server-1",
    "serverName": "My MCP Server",
    "serverUrl": "https://mcp.example.com",
    "callbackUrl": "https://app.com/callback",
    "transportType": "sse",
    "active": true,
    "createdAt": 1706234567890
  }
]

---

In-Memory (Testing)

Fast ephemeral storage, ideal for testing. Sessions are lost on restart.

In-memory storage keeps sessions in RAM. Best for:

• Unit testing
• Integration testing
• Quick prototyping
• Temporary sessions

Configuration:

# Explicit selection (optional)
MCP_TS_STORAGE_TYPE=memory

# No additional configuration needed

---

SQLite (Persistent & Fast)

Zero-configuration persistent storage, faster than file based.

SQLite provides a single-file relational database that is robust and requires no external server process.

Installation:

npm install better-sqlite3
npm install -D @types/better-sqlite3

Configuration:

# Explicit selection (optional)
MCP_TS_STORAGE_TYPE=sqlite

# SQLite DB Path (optional, defaults to ./sessions.db)
MCP_TS_STORAGE_SQLITE_PATH=./data/mcp.db

Features:

• Persistent single-file database
• Much faster than JSON file storage
• ACID compliant transactions
• Zero configuration (auto-creates DB)

Features:

• Fastest performance
• No external dependencies
• Zero configuration
• Sessions lost on restart

Usage:

import { storage } from '@mcp-ts/sdk/server';

// Storage uses in-memory by default if no other backend is configured
await storage.createSession({
  sessionId: 'test-123',
  identity: 'test-user',
  serverUrl: 'https://test.example.com',
  callbackUrl: 'https://test.com/callback',
  transportType: 'sse',
  active: true,
  createdAt: Date.now(),
});

---

PostgreSQL (Coming Soon)

PostgreSQL support is planned for a future release, providing:

• Relational data storage
• Advanced querying capabilities
• ACID compliance
• Integration with existing databases

---

Automatic Backend Selection

The library automatically selects the appropriate storage backend using this priority:

Priority Order:

1. Explicit: If MCP_TS_STORAGE_TYPE is set, use that backend
2. Auto-detect Redis: If REDIS_URL is present, use Redis
3. Auto-detect File: If MCP_TS_STORAGE_FILE is present, use File
4. Auto-detect SQLite: If MCP_TS_STORAGE_SQLITE_PATH is present, use SQLite
5. Default: Fall back to In-Memory storage

---

Custom Backend Implementation

You can use specific storage backends directly:

import { 
  RedisStorageBackend,
  MemoryStorageBackend,
  FileStorageBackend 
} from '@mcp-ts/sdk/server';
import { Redis } from 'ioredis';

// Custom Redis instance
const redis = new Redis({
  host: 'localhost',
  port: 6379,
  password: 'secret',
});
const redisStorage = new RedisStorageBackend(redis);

// Custom file path
const fileStorage = new FileStorageBackend({ 
  path: '/var/data/sessions.json' 
});
await fileStorage.init();

// In-memory for testing
const memoryStorage = new MemoryStorageBackend();

---

Backend Comparison

Feature	Redis	SQLite	File System	In-Memory
Persistence	Yes	Yes	Yes	No
Distributed	Yes	No	No	No
Auto-Expiry	Yes (TTL)	Yes (Manual)	No	No
Performance	Fast	Very Fast	Medium	Fastest
Setup	Requires Redis	Native	Built-in	Built-in
Serverless	Yes	Limited	Yes
Production	Recommended	Single-instance	Not recommended
Development	Good	Excellent	Good
Testing	Good	Good	Excellent

---

Session Data Structure

All backends store the same session data structure:

interface SessionData {
  sessionId: string;
  identity?: string;
  serverId?: string;
  serverName?: string;
  serverUrl: string;
  callbackUrl: string;
  transportType: 'sse' | 'streamable_http';
  active: boolean;
  createdAt: number;
  headers?: Record<string, string>;
  // OAuth data
  tokens?: OAuthTokens;
  clientInformation?: OAuthClientInformation;
  codeVerifier?: string;
  clientId?: string;
}

---

Best Practices

Production Deployments

# Use Redis for production
MCP_TS_STORAGE_TYPE=redis
REDIS_URL=rediss://user:pass@production-redis.example.com:6379

Local Development

# Use File storage for development
MCP_TS_STORAGE_TYPE=file
MCP_TS_STORAGE_FILE=./dev-sessions.json

Testing

# Use in-memory for tests
MCP_TS_STORAGE_TYPE=memory

Serverless (Vercel, AWS Lambda)

# Use Redis with Upstash or similar
REDIS_URL=rediss://default:token@serverless-redis.upstash.io:6379

---

Troubleshooting

Redis Connection Failed

# Verify Redis is running
redis-cli ping  # Should return PONG

# Check connection string
echo $REDIS_URL

# Test with redis-cli
redis-cli -u $REDIS_URL ping

File Storage Not Persisting

# Check file permissions
ls -la ./sessions.json

# Verify path is writable
touch ./sessions.json

# Check environment variable
echo $MCP_TS_STORAGE_FILE

Sessions Lost on Restart

If you're using in-memory storage (default), sessions will be lost on restart. Switch to Redis or File storage for persistence:

# Add to .env
MCP_TS_STORAGE_TYPE=file
MCP_TS_STORAGE_FILE=./sessions.json

---

Next Steps

• Installation Guide - Setup instructions
• API Reference - Complete API documentation
• Next.js Integration - Framework-specific guides