mcp-db provides a Redis-backed session and event store for MCP servers. It intercepts streamable HTTP traffic at the transport layer, persists MCP sessions using the session ID provided by the server transport, and records events for auditing, replay, and cross-node admission. The library enables any node to take over an active session by reconstructing the SDK transport from storage, supporting horizontal scaling and zero-downtime deployments. Core components include SessionManager, RedisStorage, EventStore (via the Redis-backed implementation), ProtocolInterceptor, ASGITransportWrapper, and StreamableHTTPAdmissionController. Typical usage involves wiring your MCP-enabled ASGI app to a wrapper that persists session state and rehydrates the transport for subsequent requests, allowing sessions to survive node restarts or load-balanced routing.

What you can do with mcp-db:

• Persist MCP sessions and event streams in Redis, enabling cross-node continuity and session reconstruction.
• Use a transport wrapper to warm up ACTIVE sessions on other nodes and route requests to the appropriate storage-backed state.
• Enable distributed scaling: run multiple MCP servers behind a load balancer while preserving session continuity.
• Leverage the provided examples for single-node setups, round-robin load balancing, and Redis-backed monitoring/demonstration flows to validate behavior.

Note: This project is experimental and not yet published to PyPI. You will need to install directly from source to use it in your environment.

Prerequisites:

• Python 3.10 or newer
• Redis 7.x or newer (for streams)
• Git

Install from source (recommended because the project is not published to PyPI):

1) Clone the repository

git clone https://github.com/yourusername/mcp-db.git cd mcp-db

2) Install the package in editable mode (uv is the recommended runner in examples)

uv pip install -e .

Alternatively, install with pip (editable)

pip install -e .

Optional: install Redis support extras if you plan to use Redis-backed storage

pip install -e ".[redis]"

Prerequisites for running examples (optional)

Ensure Redis is running locally or provide a Redis URL in your configuration

Notes and tips:

• This library is experimental and may change APIs; pin versions of any MCP SDKs you use alongside it.
• The package is not published to PyPI; install directly from the source repository as shown above.
• When configuring Redis-backed storage, you typically provide a URL like redis://localhost:6379/0 and an optional prefix for keys, e.g., prefix="mcp".
• The wrapper does not generate session IDs; it relies on the MCP server transport to provide the Mcp-Session-Id. Ensure your MCP server transport adheres to this contract.
• For development, use uv run or your preferred uvicorn-like runner to test ASGI integration; the examples directory demonstrates common patterns (single node, round-robin LB, and SSE/Last-Event-ID flows).
• If you plan to use Redis streams for events, ensure Redis 7+ is used and that the Redis server is reachable from all nodes in your cluster.