Redis Setup

​

Requirements

​

Development Setup

​

Option 1: Docker Compose (Recommended)

# Start Redis
docker compose -f ci/docker-compose.yml up redis -d

# Verify Redis is running
docker compose -f ci/docker-compose.yml exec redis redis-cli ping

# Start the full stack (app + Redis)
docker compose -f ci/docker-compose.yml up

​

Option 2: Local Installation

# macOS
brew install redis
brew services start redis

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

​

Configuration

import { CachePlugin } from '@frontmcp/plugin-cache';

CachePlugin.init({
  type: 'redis',
  config: {
    host: process.env.REDIS_HOST || 'localhost',
    port: Number(process.env.REDIS_PORT || 6379),
    password: process.env.REDIS_PASSWORD,
    db: parseInt(process.env.REDIS_DB || '0'),
    tls: process.env.REDIS_TLS === 'true',
  }
});

​

Production Setup

​

Managed Redis Services (Recommended)

​

Self-Hosted Production

# docker-compose.prod.yml
services:
  redis:
    image: redis:7-alpine
    command: >
      redis-server
      --appendonly yes
      --requirepass ${REDIS_PASSWORD}
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
    volumes:
      - redis-data:/data
    restart: unless-stopped

​

Security Best Practices

1. Authentication: Always set REDIS_PASSWORD in production
2. Network: Run Redis in private network, not exposed to internet
3. TLS: Enable TLS for encrypted connections
4. Persistence: Use AOF for durability (appendonly yes)

​

Configuration Example

// src/main.ts
import 'reflect-metadata';
import { FrontMcp } from '@frontmcp/sdk';
import { CachePlugin } from '@frontmcp/plugin-cache';

@FrontMcp({
  info: { name: 'My Server', version: '1.0.0' },
  redis: {
    host: process.env.REDIS_HOST,
    port: Number(process.env.REDIS_PORT || 6379),
    password: process.env.REDIS_PASSWORD,
    tls: process.env.REDIS_TLS === 'true',
  },
  plugins: [
    CachePlugin.init({
      type: 'global-store',
      defaultTTL: 600,
    }),
  ],
})
export default class Server {}

​

Running more than one instance

​

When Redis is unreachable at startup

• redis and transport.persistence log the failure ([TransportService] Failed to connect to redis - session persistence disabled) and the server starts. The connection is retried in the background with exponential backoff (1s doubling to 30s); once Redis is reachable, sessions are persisted again and /readyz turns healthy without a restart. Until then, sessions live on the instance that created them.
• Every Redis connection FrontMCP opens reconnects on its own and logs connection errors at a rate-limited interval (with a count of suppressed repeats) rather than once per retry.
• throttle.storage fails closed: rate limits are a security control, so startup aborts with GuardStorageUnavailableError (throttle.storage (redis) is unavailable: …). This is the default in production, where storage fallback defaults to 'error'. If Redis goes away while the server is running, a rate-limited call is refused with the same GuardStorageUnavailableError rather than an internal error. To keep serving with per-instance counters instead, opt in explicitly (a mid-run outage then logs one warning, uses per-instance counters, and returns to Redis once it answers):

@FrontMcp({
  throttle: {
    enabled: true,
    storage: {
      type: 'redis',
      redis: { config: { host: process.env.REDIS_HOST ?? 'localhost', port: 6379 } },
      fallback: 'memory', // per-instance counters while Redis is down
    },
    global: { maxRequests: 1000, windowMs: 60_000, partitionBy: 'ip' },
  },
})

​

Environment Variables

​

Redis Configuration

​

Plugin Secrets

​

Health Checks

import Redis from 'ioredis';

async function checkRedisHealth(): Promise<boolean> {
  const redis = new Redis({
    host: process.env.REDIS_HOST,
    port: Number(process.env.REDIS_PORT || 6379),
    password: process.env.REDIS_PASSWORD,
    lazyConnect: true,
  });

  try {
    await redis.connect();
    await redis.ping();
    await redis.quit();
    return true;
  } catch {
    return false;
  }
}

​

Troubleshooting

​

Connection Refused

• Verify Redis is running: redis-cli ping
• Check firewall rules
• Verify host/port configuration
• If startup fails, or rate-limited calls are refused, with GuardStorageUnavailableError, the throttle.storage backend is down; see When Redis is unreachable at startup

​

Clients keep re-initializing or tools repeat their questions

• A 404 for a session the client just used, on a load-balanced deployment, means the instances run with different MCP_SESSION_SECRET values
• A 2026-07-28 tool that asks its first question again after it was answered, with mcp-20260728: rejected requestState and reason: 'bad-signature' in the log, means VAULT_SECRET (or JWT_SECRET) is unset or differs between instances

​

Authentication Failed

• Ensure REDIS_PASSWORD matches server config
• Check for special characters in password (may need URL encoding)

​

Memory Issues

• Set maxmemory and maxmemory-policy in Redis config
• Monitor with redis-cli INFO memory

​

Docker Network Issues

# Inside Docker container
REDIS_HOST=redis

# Outside Docker (local development)
REDIS_HOST=localhost