External Cache Setup - Secure MCP Gateway

Overview

By default, Secure MCP Gateway caches tool discoveries and configuration data in-memory. For production deployments, multi-instance setups, or high-traffic environments, using an external cache like Redis or KeyDB significantly improves performance and enables cache sharing across gateway instances.

Why Use External Cache?

Shared Cache

Multiple gateway instances share the same cache, reducing redundant API calls

Persistence

Cache survives gateway restarts, avoiding cold-start delays

Better Performance

Redis/KeyDB are optimized for caching with sub-millisecond latency

Scalability

Support for clustering and high-availability configurations

What Gets Cached?

Tool Discoveries

Cache Key: enkrypt:tools:{config_id}:{server_name}
TTL: 4 hours (configurable)
Content: Discovered tools from MCP servers
Size: Varies by server (typically 1-50 KB per server)

Gateway Configurations

Cache Key: enkrypt:gateway_config:{gateway_key_hash}
TTL: 24 hours (configurable)
Content: User/project/config mappings
Size: Small (1-5 KB)

API Key Mappings

Cache Key: enkrypt:key_to_id:{gateway_key_hash}
TTL: 24 hours (configurable)
Content: API key to config ID mapping
Size: Tiny (less than 1 KB)

Cache keys are MD5-hashed for security to prevent exposure of sensitive identifiers.

Redis vs KeyDB

Feature	Redis	KeyDB
Performance	Excellent	Faster (multi-threaded)
Compatibility	Native Redis protocol	100% Redis-compatible
Threading	Single-threaded	Multi-threaded
Memory	Efficient	More efficient
License	BSD	BSD
Recommendation	Good for most use cases	Better for high concurrency

Our Recommendation: KeyDB for production, Redis for development.

Quick Start with Docker

Using Docker Compose

The easiest way to set up external cache:

Create docker-compose.yml

docker-compose.yml

version: '3'
services:
  keydb:
    image: eqalpha/keydb:latest
    ports:
      - "6379:6379"
    command:
      - keydb-server
      - --requirepass
      - your-secure-password
      - --maxmemory
      - 256mb
      - --maxmemory-policy
      - allkeys-lru
    volumes:
      - keydb-data:/data

volumes:
  keydb-data:

Start KeyDB

docker-compose up -d

Configure Gateway

Edit ~/.enkrypt/enkrypt_mcp_config.json:

{
  "common_mcp_gateway_config": {
    "enkrypt_mcp_use_external_cache": true,
    "enkrypt_cache_host": "localhost",
    "enkrypt_cache_port": 6379,
    "enkrypt_cache_db": 0,
    "enkrypt_cache_password": "your-secure-password",
    "enkrypt_tool_cache_expiration": 4,
    "enkrypt_gateway_cache_expiration": 24
  }
}

Restart Gateway

Restart Claude Desktop to apply the changes. The gateway will now use KeyDB for caching.

Installation Methods

Docker (Recommended)
Native Installation
Cloud Services

KeyDB with Docker

# Pull KeyDB image
docker pull eqalpha/keydb:latest

# Run KeyDB with password
docker run -d \
  --name keydb \
  -p 6379:6379 \
  -v keydb-data:/data \
  eqalpha/keydb:latest \
  keydb-server \
  --requirepass your-secure-password \
  --maxmemory 256mb \
  --maxmemory-policy allkeys-lru

Redis with Docker

# Pull Redis image
docker pull redis:7-alpine

# Run Redis with password
docker run -d \
  --name redis \
  -p 6379:6379 \
  -v redis-data:/data \
  redis:7-alpine \
  redis-server \
  --requirepass your-secure-password \
  --maxmemory 256mb \
  --maxmemory-policy allkeys-lru

macOS

# Using Homebrew
brew install redis

# Start Redis
brew services start redis

# Or use KeyDB
brew tap eqalpha/keydb
brew install keydb
brew services start keydb

Ubuntu/Debian

# Redis
sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server

# KeyDB
curl -s https://download.keydb.dev/keydb.gpg | sudo apt-key add -
echo "deb https://download.keydb.dev/stable/deb $(lsb_release -sc) main" | \
  sudo tee /etc/apt/sources.list.d/keydb.list
sudo apt update
sudo apt install keydb
sudo systemctl start keydb

Windows

# Using Windows Subsystem for Linux (WSL2)
wsl --install

# Inside WSL2
sudo apt update
sudo apt install redis-server
sudo service redis-server start

Redis Cloud (Managed)

Sign up at Redis Cloud
Create a new database
Note the host, port, and password
Configure gateway with the connection details

AWS ElastiCache

# Configure with ElastiCache endpoint
{
  "enkrypt_cache_host": "your-cluster.cache.amazonaws.com",
  "enkrypt_cache_port": 6379,
  "enkrypt_cache_password": null  # If no auth
}

Azure Cache for Redis

# Get connection details from Azure Portal
{
  "enkrypt_cache_host": "your-cache.redis.cache.windows.net",
  "enkrypt_cache_port": 6380,  # SSL port
  "enkrypt_cache_password": "your-access-key"
}

Configuration

Complete Cache Configuration

~/.enkrypt/enkrypt_mcp_config.json

{
  "common_mcp_gateway_config": {
    // Enable external cache
    "enkrypt_mcp_use_external_cache": true,
    
    // Connection settings
    "enkrypt_cache_host": "localhost",
    "enkrypt_cache_port": 6379,
    "enkrypt_cache_db": 0,
    "enkrypt_cache_password": "your-secure-password",
    
    // Expiration times (in hours)
    "enkrypt_tool_cache_expiration": 4,
    "enkrypt_gateway_cache_expiration": 24
  }
}

Configuration Fields

Field	Type	Default	Description
`enkrypt_mcp_use_external_cache`	boolean	`false`	Enable external cache
`enkrypt_cache_host`	string	`"localhost"`	Redis/KeyDB host
`enkrypt_cache_port`	integer	`6379`	Redis/KeyDB port
`enkrypt_cache_db`	integer	`0`	Database number (0-15)
`enkrypt_cache_password`	string/null	`null`	Authentication password
`enkrypt_tool_cache_expiration`	integer	`4`	Tool cache TTL (hours)
`enkrypt_gateway_cache_expiration`	integer	`24`	Gateway config TTL (hours)

Database Selection

Redis/KeyDB support 16 databases (0-15). Use different databases for different purposes:

{
  // Development
  "enkrypt_cache_db": 0,
  
  // Staging
  "enkrypt_cache_db": 1,
  
  // Production
  "enkrypt_cache_db": 2
}

Cache Management

Check Cache Status

Claude Desktop
CLI
Redis CLI

Ask Claude:

Show me the cache status

Or use the tool directly:

Use enkrypt_get_cache_status to see cache metrics

secure-mcp-gateway system health-check

Output:

Cache Status:
  Type: External (Redis/KeyDB)
  Host: localhost:6379
  Total Gateways: 5
  Total Tool Caches: 12
  Total Config Caches: 5

# Connect to Redis/KeyDB
redis-cli -h localhost -p 6379 -a your-secure-password

# View all cache keys
KEYS enkrypt:*

# Count keys by type
EVAL "return #redis.call('keys', 'enkrypt:tools:*')" 0
EVAL "return #redis.call('keys', 'enkrypt:gateway_config:*')" 0

# View a specific cache entry
GET enkrypt:tools:abc-123:github

# Check TTL
TTL enkrypt:tools:abc-123:github

Clear Cache

Claude Desktop
CLI
Redis CLI

Clear all cache

Or:

Clear cache for github server

# Clear all cache
secure-mcp-gateway cache clear

# Clear specific server
secure-mcp-gateway cache clear --server-name github

# Clear gateway config cache
secure-mcp-gateway cache clear --cache-type gateway_config

# Connect
redis-cli -h localhost -p 6379 -a your-secure-password

# Clear all Enkrypt cache
EVAL "return redis.call('del', unpack(redis.call('keys', 'enkrypt:*')))" 0

# Clear specific server tools
DEL enkrypt:tools:config-id:github

# Clear all tool caches
EVAL "return redis.call('del', unpack(redis.call('keys', 'enkrypt:tools:*')))" 0

Production Setup

Redis Configuration File

Create /etc/redis/redis.conf:

# Network
bind 0.0.0.0
port 6379
protected-mode yes

# Security
requirepass your-very-secure-password-here

# Memory
maxmemory 1gb
maxmemory-policy allkeys-lru

# Persistence (optional)
save 900 1
save 300 10
save 60 10000
dir /var/lib/redis

# Logging
loglevel notice
logfile /var/log/redis/redis-server.log

# Performance
tcp-backlog 511
tcp-keepalive 300
timeout 0

KeyDB Configuration

Create /etc/keydb/keydb.conf:

# Network
bind 0.0.0.0
port 6379

# Security
requirepass your-very-secure-password-here

# Multi-threading (KeyDB advantage)
server-threads 4
server-thread-affinity true

# Memory
maxmemory 1gb
maxmemory-policy allkeys-lru

# Persistence
save 900 1
save 300 10
save 60 10000
dir /var/lib/keydb

# Logging
loglevel notice
logfile /var/log/keydb/keydb-server.log

High Availability Setup

Redis Sentinel
KeyDB Active-Replica

docker-compose.yml

version: '3'
services:
  redis-master:
    image: redis:7-alpine
    command: redis-server --requirepass master-password
    ports:
      - "6379:6379"
  
  redis-replica:
    image: redis:7-alpine
    command: >
      redis-server
      --replicaof redis-master 6379
      --masterauth master-password
      --requirepass replica-password
    depends_on:
      - redis-master
  
  redis-sentinel:
    image: redis:7-alpine
    command: >
      redis-sentinel /etc/redis/sentinel.conf
    volumes:
      - ./sentinel.conf:/etc/redis/sentinel.conf
    depends_on:
      - redis-master
      - redis-replica

sentinel.conf:

sentinel monitor mymaster redis-master 6379 2
sentinel auth-pass mymaster master-password
sentinel down-after-milliseconds mymaster 5000
sentinel parallel-syncs mymaster 1
sentinel failover-timeout mymaster 10000

docker-compose.yml

version: '3'
services:
  keydb-master:
    image: eqalpha/keydb:latest
    command: >
      keydb-server
      --server-threads 4
      --requirepass master-password
      --active-replica yes
    ports:
      - "6379:6379"
  
  keydb-replica:
    image: eqalpha/keydb:latest
    command: >
      keydb-server
      --server-threads 4
      --replicaof keydb-master 6379
      --masterauth master-password
      --requirepass replica-password
      --active-replica yes
    depends_on:
      - keydb-master

Monitoring

Redis/KeyDB Metrics

# Connect
redis-cli -h localhost -p 6379 -a your-password

# Server info
INFO server
INFO memory
INFO stats
INFO replication

# Memory usage
MEMORY USAGE enkrypt:tools:config:github

# Slow operations
SLOWLOG GET 10

Integration with OpenTelemetry

The gateway automatically exports cache metrics via OpenTelemetry:

cache.hits: Cache hit count
cache.misses: Cache miss count
cache.operations.duration: Cache operation latency
cache.size: Number of cached items

View in Grafana dashboards (see Observability Setup).

Troubleshooting

Connection Refused

Error: Error connecting to Redis: Connection refusedSolutions:

Check Redis/KeyDB is running: redis-cli ping
Verify host and port in config
Check firewall rules
Ensure bind address allows connections

Authentication Failed

Error: NOAUTH Authentication requiredSolutions:

Verify password in config
Check Redis/KeyDB password: redis-cli -a password ping
Ensure password doesn’t have special characters causing issues

Cache Not Working

Symptoms: Gateway still slow, tools re-discovered every timeSolutions:

Verify enkrypt_mcp_use_external_cache: true
Check cache status: secure-mcp-gateway system health-check
View gateway logs for cache errors
Test Redis connection: redis-cli -h host -p port -a password ping

Out of Memory

Error: OOM command not allowed when used memory > 'maxmemory'Solutions:

Increase maxmemory in Redis config
Set eviction policy: maxmemory-policy allkeys-lru
Clear old cache: redis-cli FLUSHDB
Reduce TTL values in gateway config

Slow Performance

Symptoms: Cache slower than expectedSolutions:

Use KeyDB instead of Redis (multi-threaded)
Check network latency between gateway and cache
Monitor slow operations: SLOWLOG GET 10
Ensure cache is on same network/host as gateway

Best Practices

Use KeyDB for Production

KeyDB’s multi-threading provides better performance under load

Set Strong Passwords

Use long, random passwords for cache authentication

Configure Memory Limits

Set maxmemory and use allkeys-lru eviction policy

Enable Persistence

Use RDB or AOF persistence for important cache data

Monitor Cache Metrics

Track hit rates, memory usage, and performance

Use Different DBs

Separate dev/staging/prod with different database numbers

Regular Backups

Backup cache configuration and data regularly

Network Security

Use firewall rules, VPCs, or SSH tunnels for remote cache

Performance Tuning

# For high-throughput production
maxmemory 2gb
maxmemory-policy allkeys-lru
tcp-keepalive 60
timeout 300

# KeyDB specific
server-threads 8  # Match CPU cores
server-thread-affinity true

# Disable persistence if not needed
save ""
appendonly no

Migration from Local to External Cache

Set Up Cache Server

Install and configure Redis/KeyDB as shown above

Update Gateway Config

{
  "common_mcp_gateway_config": {
    "enkrypt_mcp_use_external_cache": true,
    "enkrypt_cache_host": "localhost",
    "enkrypt_cache_port": 6379,
    "enkrypt_cache_password": "your-password"
  }
}

Restart Gateway

Close and reopen Claude Desktop

Verify Cache Working

Ask Claude: “Show me the cache status”Should show: Type: External (Redis/KeyDB)

Monitor Performance

Watch for improved response times on repeated operations

Next Steps

Configure Guardrails

Guardrail results are also cached for better performance

OAuth Setup

OAuth tokens are cached to avoid repeated token requests

Observability

Monitor cache metrics in Grafana

Production Deployment

Learn about deploying the gateway in production

Get Started

Core Concepts

Features

Deployment

Client Integration

Observability

Security

Guides

​Overview

​Why Use External Cache?

Shared Cache

Persistence

Better Performance

Scalability

​What Gets Cached?

​Tool Discoveries

​Gateway Configurations

​API Key Mappings

​Redis vs KeyDB

​Quick Start with Docker

​Using Docker Compose

​Installation Methods

​KeyDB with Docker

​Redis with Docker

​macOS

​Ubuntu/Debian

​Windows

​Redis Cloud (Managed)

​AWS ElastiCache

​Azure Cache for Redis

​Configuration

​Complete Cache Configuration

​Configuration Fields

​Database Selection

​Cache Management

​Check Cache Status

​Clear Cache

​Production Setup

​Redis Configuration File

​KeyDB Configuration

​High Availability Setup

​Monitoring

​Redis/KeyDB Metrics

​Integration with OpenTelemetry

​Troubleshooting

​Best Practices

Use KeyDB for Production

Set Strong Passwords

Configure Memory Limits

Enable Persistence

Monitor Cache Metrics

Use Different DBs

Regular Backups

Network Security

​Performance Tuning

​Migration from Local to External Cache

​Next Steps

Configure Guardrails

OAuth Setup

Observability

Production Deployment

Build docs developers (and LLMs) love

Overview

Why Use External Cache?

What Gets Cached?

Tool Discoveries

Gateway Configurations

API Key Mappings

Redis vs KeyDB

Quick Start with Docker

Using Docker Compose

Installation Methods

KeyDB with Docker

Redis with Docker

macOS

Ubuntu/Debian

Windows

Redis Cloud (Managed)

AWS ElastiCache

Azure Cache for Redis

Configuration

Complete Cache Configuration

Configuration Fields

Database Selection

Cache Management

Check Cache Status

Clear Cache

Production Setup

Redis Configuration File

KeyDB Configuration

High Availability Setup

Monitoring

Redis/KeyDB Metrics

Integration with OpenTelemetry

Troubleshooting

Best Practices

Performance Tuning

Migration from Local to External Cache

Next Steps