feat: add RedisEventStore for production SSE resumability

[Ar-maan05]

Description

Closes #2570

This PR adds a production-grade, Redis-backed EventStore ( RedisEventStore ) to support SSE stream resumability in multi-process/multi-worker deployments.

The implementation resides in a new mcp.server.contrib package designed for production-grade add-ons requiring optional dependencies.

Design & Architecture

1. Redis Data Structures:
   • Atomic Monotonic IDs: Uses a Redis string counter ( {prefix}counter ) and INCR to generate unique, monotonic integer event IDs safely across concurrent processes.
   • Event Metadata: Uses a Redis Hash ( {prefix}event:{event_id} ) storing stream_id and the serialized JSONRPCMessage payload.
   • Stream Ordering: Uses a Sorted Set ( {prefix}stream:{stream_id} ) to map event IDs to their integer score, allowing ZRANGEBYSCORE to perform $O(\log N)$ range queries when replaying events.
2. Robustness:
   • Storing a message = None sentinel writes an empty string to Redis to identify priming events, which are skipped on replay.
   • Cleans up keys using an optional ttl (Time to Live) on all keys generated ( counter , event , stream ). Logs a warning if ttl=None to prevent unbounded memory growth.
   • Supports dynamic key_prefix to isolate multiple MCP servers sharing a single Redis instance/cluster.
3. Lazy Imports & Optional Dependencies:
   • redis is placed in [project.optional-dependencies] under the redis extra.
   • Type annotations/imports of redis.asyncio are enclosed inside if TYPE_CHECKING: guards. This ensures the MCP SDK remains fully importable and functional at runtime for users who do not install the redis extra.

How to Use

Install the optional dependency:

pip install "mcp[redis]"

Configure your SSE manager:

import redis.asyncio as aioredis
from mcp.server.contrib.event_stores import RedisEventStore
from mcp.server.streamable_http_manager import StreamableHTTPSessionManager

redis_client = aioredis.from_url("redis://localhost:6379")
event_store = RedisEventStore(redis_client, ttl=3600)  # 1 hour expiry

session_manager = StreamableHTTPSessionManager(
app=mcp_server,
event_store=event_store,
)

Verification & Testing

Unit Tests

Wrote 21 extensive async unit tests using fakeredis to avoid external server dependencies in CI/CD.

• Monotonic ID generation and collision-free concurrency.
• Correct message serialization and deserialization roundtrips.
• Stream boundary isolation and replay sort order.
• Expiry/TTL setting correctness.
• Key prefix multi-tenant isolation.
• Warning log emissions.

.venv/bin/pytest tests/server/contrib/ -v

Result: 21 passed.

Quality & Linting

• Checked and validated with pyright : 0 errors.
• Checked and formatted with ruff : All checks passed.

[maxisbey]

Thanks for the thorough work here — the design writeup and test coverage are well done.

We're going to decline this one, for two reasons that compound:

The upcoming spec revision removes SSE resumability from the streamable HTTP transport entirely (SEP-2575, merged into the draft on 2026-05-11 — the Resumability and Redelivery section is gone and the draft now says explicitly that Last-Event-ID resumption is not supported, with tasks as the replacement for durability across disconnects). So the EventStore abstraction this plugs into is on its way out of the SDK rather than something we want to invest further in.

Separately, and this would apply even without the spec change: we keep concrete infrastructure backends out of the SDK and ship only the abstraction. That matches the other official SDKs — the TypeScript SDK ships the EventStore interface with an in-memory example only; Go ships interface + in-memory; C# ships an adapter to ASP.NET's framework-level IDistributedCache abstraction rather than any specific database client. Taking a redis dependency (even as an optional extra) and a new contrib namespace would put us on the hook for an open-ended set of backend adapters, which is better served by standalone packages.

If you'd like this to live on while 2025-11-25 is still the current revision, publishing it as its own package on PyPI is the right home — the EventStore ABC is a stable public interface to build against.

_{AI Disclaimer}

[Ar-maan05]

Thanks for the detailed feedback. I have taken your suggestion and published this as a standalone package: mcp-persist (pip install "mcp-persist[redis]"). It builds against the stable EventStore ABC as you recommended. Happy to hear any thoughts.