Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

fix(mcp): recover from transient redis startup failures (#121901)

Richard Solomou50f2be9cc1aa
diff --git a/services/mcp/README.md b/services/mcp/README.md
index 6efca8502d21..b6fc9d626b40 100644
--- a/services/mcp/README.md
+++ b/services/mcp/README.md
@@ -408,6 +408,8 @@ Then replace `https://mcp.posthog.com/mcp` with `http://localhost:8787/mcp` in t
The server defaults to port **8787**, reads config from `.env` (see `.env.example`), and expects a local Redis on port `6379` for session state; production deployments must set `REDIS_URL` to a TLS-encrypted `rediss://` endpoint.
+Startup waits up to 45 seconds for Redis to become ready, including connection retries. If Redis stops reconnecting or the deadline expires, the process exits without starting the HTTP server.
+
### Session cache
Each MCP transport session keeps its own active organization and project, including connections without a `project_id` or `organization_id` pin. An unpinned session starts from the user's active organization and project, within the credential's allowed scope. Later website changes and switches in other MCP sessions do not change that selection. `switch-project` and `switch-organization` update only the calling session; switching to another organization clears the previous project.
diff --git a/services/mcp/src/hono/index.ts b/services/mcp/src/hono/index.ts
index 37f883fbb4a6..7ffab8929020 100644
--- a/services/mcp/src/hono/index.ts
+++ b/services/mcp/src/hono/index.ts
@@ -5,6 +5,7 @@ import { getCustomApiBaseUrl, isLocalApi } from '@/lib/constants'
import { createApp } from './app'
import { redisOperationsTotal } from './metrics'
+import { connectRedis } from './redis-connection'
import { registerShutdownHandlers } from './shutdown'
const PORT = parseInt(process.env.PORT || '3001', 10)
@@ -46,7 +47,7 @@ redis.on('connect', () => {
async function main(): Promise<void> {
try {
- await redis.connect()
+ await connectRedis(redis)
} catch (err) {
console.error('[MCP] Failed to connect to Redis:', err)
process.exit(1)
diff --git a/services/mcp/src/hono/redis-connection.ts b/services/mcp/src/hono/redis-connection.ts
new file mode 100644
index 000000000000..79870e46db1f
--- /dev/null
+++ b/services/mcp/src/hono/redis-connection.ts
@@ -0,0 +1,34 @@
+import type Redis from 'ioredis'
+
+export async function connectRedis(redis: InstanceType<typeof Redis>, timeoutMs: number = 45_000): Promise<void> {
+ await new Promise<void>((resolve, reject) => {
+ let timer: ReturnType<typeof setTimeout>
+
+ function cleanup(): void {
+ clearTimeout(timer)
+ redis.removeListener('ready', onReady)
+ redis.removeListener('end', onEnd)
+ }
+
+ function onReady(): void {
+ cleanup()
+ resolve()
+ }
+
+ function onEnd(): void {
+ cleanup()
+ reject(new Error('Redis connection ended before startup'))
+ }
+
+ timer = setTimeout(() => {
+ cleanup()
+ redis.disconnect()
+ reject(new Error(`Redis did not become ready within ${timeoutMs}ms`))
+ }, timeoutMs)
+
+ redis.once('ready', onReady)
+ redis.once('end', onEnd)
+ // connect() rejects on the first socket close while ioredis continues reconnecting.
+ void redis.connect().catch(() => {})
+ })
+}
diff --git a/services/mcp/tests/hono/redis-connection.test.ts b/services/mcp/tests/hono/redis-connection.test.ts
new file mode 100644
index 000000000000..6bd3810fbb1b
--- /dev/null
+++ b/services/mcp/tests/hono/redis-connection.test.ts
@@ -0,0 +1,59 @@
+import type Redis from 'ioredis'
+import { EventEmitter } from 'node:events'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { connectRedis } from '@/hono/redis-connection'
+
+class RedisStub extends EventEmitter {
+ connect = vi.fn<() => Promise<void>>()
+ disconnect = vi.fn()
+}
+
+describe('Redis startup connection', () => {
+ beforeEach(() => {
+ vi.useFakeTimers()
+ })
+
+ afterEach(() => {
+ vi.useRealTimers()
+ })
+
+ it('waits for readiness after the initial connection closes', async () => {
+ const redis = new RedisStub()
+ redis.connect.mockRejectedValue(new Error('Connection is closed.'))
+ const connected = vi.fn()
+ const connection = connectRedis(redis as unknown as InstanceType<typeof Redis>, 1000).then(connected)
+ await vi.advanceTimersByTimeAsync(500)
+ expect(connected).not.toHaveBeenCalled()
+
+ redis.emit('ready')
+ await connection
+ expect(connected).toHaveBeenCalledOnce()
+ expect(redis.listenerCount('ready')).toBe(0)
+ expect(vi.getTimerCount()).toBe(0)
+ })
+
+ it('stops reconnecting when startup times out', async () => {
+ const redis = new RedisStub()
+ redis.connect.mockRejectedValue(new Error('Connection is closed.'))
+ const connection = connectRedis(redis as unknown as InstanceType<typeof Redis>, 1000)
+ await Promise.all([
+ expect(connection).rejects.toThrow('Redis did not become ready within 1000ms'),
+ vi.advanceTimersByTimeAsync(1000),
+ ])
+ expect(redis.disconnect).toHaveBeenCalledOnce()
+ expect(redis.listenerCount('ready')).toBe(0)
+ expect(redis.listenerCount('end')).toBe(0)
+ expect(vi.getTimerCount()).toBe(0)
+ })
+
+ it('fails immediately when Redis stops trying to connect', async () => {
+ const redis = new RedisStub()
+ redis.connect.mockRejectedValue(new Error('Connection is closed.'))
+ const connection = connectRedis(redis as unknown as InstanceType<typeof Redis>, 1000)
+ redis.emit('end')
+ await expect(connection).rejects.toThrow('Redis connection ended before startup')
+ expect(redis.listenerCount('ready')).toBe(0)
+ expect(vi.getTimerCount()).toBe(0)
+ })
+})