Installation

Prerequisites

Before installing, ensure you have:

Node.js 18+ - Download Node.js
Package manager - npm, yarn, or pnpm
Storage Backend (optional, defaults to in-memory):
- Redis - Production distributed storage
- File System - Local JSON persistence
- SQLite - Native persistent database
- Supabase - Cloud-native PostgreSQL
- Neon - Serverless Postgres

Install the Package

Choose your preferred package manager:

npm2yarn

npm install @mcp-ts/sdk

Configure Storage Backend

The library automatically selects a storage backend based on your environment variables. Choose the option that best fits your needs:

Option 1: Redis (Production)

Recommended for production and serverless deployments.

Local Redis Setup

# macOS (Homebrew)
brew install redis
brew services start redis

# Ubuntu/Debian
sudo apt-get install redis-server
sudo systemctl start redis

# Windows (WSL or Docker)
docker run -d -p 6379:6379 redis:latest

Environment Configuration

# Explicit selection (optional)
MCP_TS_STORAGE_TYPE=redis

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

Option 2: File System (Development)

Perfect for local development with persistent sessions across restarts.

# Explicit selection (optional)
MCP_TS_STORAGE_TYPE=file

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

Option 3: In-Memory (Testing)

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

# Explicit selection (optional)
MCP_TS_STORAGE_TYPE=memory

This is the default if no storage configuration is provided.

Storage Selection Logic

The library uses the following priority:

Explicit: If MCP_TS_STORAGE_TYPE is set, use that backend
Auto-detect Redis: If REDIS_URL is present, use Redis
Auto-detect File: If MCP_TS_STORAGE_FILE is present, use File
Auto-detect SQLite: If MCP_TS_STORAGE_SQLITE_PATH is present, use SQLite
Auto-detect Supabase: If SUPABASE_URL is present, use Supabase
Auto-detect Neon: If NEON_DATABASE_URL is present, use Neon
Default: Fall back to In-Memory storage

See Storage Overview for more details.

Verify Installation

Test your setup with a simple script:

// test-mcp.ts
import { sessions } from '@mcp-ts/sdk/server';

async function test() {
  const sessionId = await sessions.generateSessionId();
  console.log('Generated session ID:', sessionId);

  await sessions.create({
    sessionId,
    userId: 'test-user',
    serverId: 'test-server',
    serverName: 'Test Server',
    serverUrl: 'https://example.com',
    callbackUrl: 'https://example.com/callback',
    transportType: 'streamable-http',
    status: 'active',
    createdAt: Date.now(),
  });

  const session = await sessions.get('test-user', sessionId);
  console.log('Storage backend working:', session?.serverName);
}

test();

TypeScript Configuration

If using TypeScript, ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Next Steps

Storage Overview - Detailed backend comparison
Next.js Integration - Set up with Next.js
React Hook - Use the React hook
API Reference - Explore the API

Getting Started

Framework Guides

Examples

Core Concepts

Resources

Prerequisites

Install the Package

Configure Storage Backend

Option 1: Redis (Production)

Local Redis Setup

Environment Configuration

Option 2: File System (Development)

Option 3: In-Memory (Testing)

Storage Selection Logic

Verify Installation

TypeScript Configuration

Next Steps

​Prerequisites

​Install the Package

​Configure Storage Backend

​Option 1: Redis (Production)

​Local Redis Setup

​Environment Configuration

​Option 2: File System (Development)

​Option 3: In-Memory (Testing)

​Storage Selection Logic

​Verify Installation

​TypeScript Configuration

​Next Steps

Prerequisites

Install the Package

Configure Storage Backend

Option 1: Redis (Production)

Local Redis Setup

Environment Configuration

Option 2: File System (Development)

Option 3: In-Memory (Testing)

Storage Selection Logic

Verify Installation

TypeScript Configuration

Next Steps