Redis Storage

Use Redis when session metadata or server-to-client workflows must work across restarts, deploys, or multiple server instances. Redis gives you two pieces: RedisSessionStore for serializable session metadata and RedisStreamManager for routing active stream messages across instances. This guide focuses on choosing and wiring Redis. Use the Sessions API reference for constructor options, defaults, method behavior, Redis command details, and stream-manager contracts.

Choose the Redis pieces you need

Use the session store alone when you only need session metadata persistence or ordinary request recovery across instances. Add the stream manager when active server-to-client delivery must cross instance boundaries.

Deployment need	Configure
Sessions survive restarts on one server	`RedisSessionStore`
Load-balanced servers share session metadata	`RedisSessionStore`
Notifications or resource updates must reach clients connected to another instance	`RedisSessionStore` plus `RedisStreamManager`
Sampling, elicitation, or roots requests need client responses routed back across instances	`RedisSessionStore` plus `RedisStreamManager`

RedisSessionStore does not store active stream controllers. Use RedisStreamManager for distributed server-to-client delivery.

Install Redis support

Install a Redis client library and provide an already-connected client to mcp-use.

npm install redis

The Redis classes are also compatible with clients that implement the minimal Redis client contract documented in the API reference. Distributed stream routing requires Pub/Sub support, including subscribe and unsubscribe operations on the Pub/Sub client.

Persist session metadata

Use RedisSessionStore when reconnecting clients should keep session metadata after a restart or deploy.

import { MCPServer, RedisSessionStore } from "mcp-use/server";
import { createClient } from "redis";

const redis = createClient({
  url: process.env.REDIS_URL,
});

await redis.connect();

const server = new MCPServer({
  name: "redis-session-server",
  version: "1.0.0",
  sessionStore: new RedisSessionStore({
    client: redis,
  }),
});

await server.listen(3000);

Use the API reference when you need custom key prefixes, TTLs, or shutdown behavior.

Add distributed stream routing

Use RedisStreamManager when an active client stream may live on one server while another server needs to send a notification or route the response to a server-to-client request. Pub/Sub needs a dedicated Redis connection, so create a duplicate client.

import {
  MCPServer,
  RedisSessionStore,
  RedisStreamManager,
} from "mcp-use/server";
import { createClient } from "redis";

const redis = createClient({ url: process.env.REDIS_URL });
const pubSubRedis = redis.duplicate();

await redis.connect();
await pubSubRedis.connect();

const server = new MCPServer({
  name: "distributed-session-server",
  version: "1.0.0",
  sessionStore: new RedisSessionStore({
    client: redis,
  }),
  streamManager: new RedisStreamManager({
    client: redis,
    pubSubClient: pubSubRedis,
  }),
});

await server.listen(3000);

Use separate Redis connections for normal commands and Pub/Sub. A client in subscriber mode cannot reliably publish or run ordinary commands.

Verify distributed behavior

Before using Redis in production, verify these cases in an environment that resembles your deployment:

Restarting one server does not force clients to re-initialize.
A notification or resource update published by one instance reaches a client stream connected to another instance.
Sampling, elicitation, or other server-to-client request responses route back to the instance waiting for them.
Redis connection shutdown is handled when the server exits.

If you only run one instance and can lose sessions on restart, In-Memory Storage is simpler.

Next steps

Redis session store API reference

Look up Redis session store options and methods.

Redis stream manager API reference

Look up distributed stream routing options and methods.

ServerConfig API reference

Look up sessionStore and streamManager fields.

Session management example

Compare your setup with a runnable Redis-backed example.

Get Started

MCP Server

MCP Apps

MCP Client

MCP Agent

Tooling

Choose the Redis pieces you need

Install Redis support

Persist session metadata

Add distributed stream routing

Verify distributed behavior

Next steps

Redis session store API reference

Redis stream manager API reference

ServerConfig API reference

Session management example

​Choose the Redis pieces you need

​Install Redis support

​Persist session metadata

​Add distributed stream routing

​Verify distributed behavior

​Next steps

Redis session store API reference

Redis stream manager API reference

ServerConfig API reference

Session management example

Choose the Redis pieces you need

Install Redis support

Persist session metadata

Add distributed stream routing

Verify distributed behavior

Next steps