Kubernetes Readiness Probes for MCP Servers — gate traffic until truly ready

Liveness vs readiness: the critical distinction for MCP servers

Kubernetes uses two independent probes with fundamentally different responses to failure:

• Liveness failure → the kubelet restarts the container. This is appropriate for an unrecoverable hang: a deadlocked event loop that will never process another message. Restarting is the only fix.
• Readiness failure → the endpoint is removed from the Service's Endpoints list. The container continues running. This is appropriate for a recoverable not-yet-ready state: a database that is still initializing its connection pool, a config secret that took longer than usual to fetch from Vault, a cache that needs one more second to warm. The pod should stop receiving new traffic until it is ready, but it should not be killed.

For MCP servers, the distinction is especially important because of long-lived SSE connections. If a pod becomes temporarily overloaded — all database connections held by slow tool calls — the correct response is to stop sending it new requests, not to restart it and forcibly disconnect the existing clients. The readiness probe enables this: the overloaded pod fails readiness, stops receiving new SSE connections, clears its backlog, passes readiness again, and rejoins the load balancer — all without a single client disconnection.

Implementing a /ready endpoint for MCP servers

The readiness endpoint must check every dependency that tool calls actually need. A probe that only checks "is the HTTP server listening?" is no better than a TCP probe — it will report the pod as ready while database queries are failing and tool responses contain only error messages.

Node.js / TypeScript — comprehensive readiness check

import express from 'express';
import { pool } from './db';               // Your database connection pool
import { toolRegistry } from './tools';    // Your MCP tool registry

interface ReadinessCheck {
  name: string;
  ok: boolean;
  latencyMs?: number;
  error?: string;
}

async function checkDatabasePool(): Promise<ReadinessCheck> {
  const start = Date.now();
  try {
    // Acquire a connection from the pool; if pool is saturated this will throw
    const conn = await pool.acquire({ timeout: 1000 });
    await conn.query('SELECT 1');  // Minimal round-trip to verify the connection is valid
    pool.release(conn);
    return { name: 'database', ok: true, latencyMs: Date.now() - start };
  } catch (err) {
    return { name: 'database', ok: false, error: String(err) };
  }
}

async function checkToolRegistry(): Promise<ReadinessCheck> {
  // Verify the tool registry has been built and contains the expected tools
  const toolCount = toolRegistry.size;
  if (toolCount === 0) {
    return { name: 'tool_registry', ok: false, error: 'No tools registered' };
  }
  return { name: 'tool_registry', ok: true };
}

async function checkSecrets(): Promise<ReadinessCheck> {
  // Verify required environment secrets were injected (not their values — just presence)
  const required = ['DATABASE_URL', 'API_KEY'];
  const missing = required.filter(k => !process.env[k]);
  if (missing.length > 0) {
    return { name: 'secrets', ok: false, error: `Missing: ${missing.join(', ')}` };
  }
  return { name: 'secrets', ok: true };
}

const app = express();

app.get('/ready', async (req, res) => {
  const checks = await Promise.all([
    checkDatabasePool(),
    checkToolRegistry(),
    checkSecrets(),
  ]);

  const ok = checks.every(c => c.ok);
  const status = ok ? 200 : 503;

  res.status(status).json({
    ready: ok,
    checks,
    timestamp: new Date().toISOString(),
  });
});

// /live — liveness probe (separate, lighter weight — see mcp-server-liveness-probe guide)
app.get('/live', async (req, res) => {
  await new Promise(resolve => setImmediate(resolve));
  res.json({ live: true });
});

FastAPI / Python — equivalent readiness check

from fastapi import FastAPI
from fastapi.responses import JSONResponse
import asyncio
import asyncpg
import os

app = FastAPI()
db_pool: asyncpg.Pool | None = None  # Set during startup

@app.on_event("startup")
async def startup():
    global db_pool
    db_pool = await asyncpg.create_pool(os.environ["DATABASE_URL"], min_size=2, max_size=10)

@app.get("/ready")
async def readiness():
    checks = []

    # Check database pool
    try:
        async with db_pool.acquire(timeout=1.0) as conn:
            await conn.fetchval("SELECT 1")
        checks.append({"name": "database", "ok": True})
    except Exception as e:
        checks.append({"name": "database", "ok": False, "error": str(e)})

    # Check required secrets
    required = ["DATABASE_URL", "API_KEY"]
    missing = [k for k in required if not os.environ.get(k)]
    checks.append({"name": "secrets", "ok": len(missing) == 0,
                   "error": f"Missing: {missing}" if missing else None})

    ok = all(c["ok"] for c in checks)
    return JSONResponse({"ready": ok, "checks": checks}, status_code=200 if ok else 503)

Kubernetes readiness probe configuration

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: mcp-server
  template:
    metadata:
      labels:
        app: mcp-server
    spec:
      containers:
        - name: mcp-server
          image: your-registry/mcp-server:v1.2.3
          ports:
            - containerPort: 3000

          livenessProbe:
            httpGet:
              path: /live
              port: 3000
            initialDelaySeconds: 60
            periodSeconds: 15
            timeoutSeconds: 5
            failureThreshold: 3

          readinessProbe:
            httpGet:
              path: /ready
              port: 3000
            # Readiness probes start sooner — we want to know about dependency failures quickly
            initialDelaySeconds: 10
            periodSeconds: 10
            timeoutSeconds: 5
            # Two consecutive successes required before pod accepts traffic (prevents flapping
            # when a dependency briefly recovers then fails again during warmup)
            successThreshold: 2
            # Three consecutive failures to remove from load balancer
            failureThreshold: 3

Tuning successThreshold to prevent SSE connection flapping

The default successThreshold is 1, meaning a single successful readiness probe is enough to add the pod back to the load balancer. For MCP servers using the SSE transport, this can cause connection flapping: a pod that is borderline ready — its database pool has one idle connection — passes readiness, receives a flood of new SSE connections, the pool saturates, and the pod immediately fails readiness again.

Setting successThreshold: 2 requires two consecutive successes before the pod re-enters the load balancer. This provides a brief window (one probe interval = 10 seconds) during which the pod must maintain readiness, which smooths out transient recovery oscillation.

Readiness probes during rolling deployments

The readiness probe is the mechanism that makes zero-downtime rolling deployments possible. When you apply a new Deployment spec, Kubernetes starts new pods with the updated image. Each new pod is excluded from the Service load balancer until its readiness probe passes. Only after the new pod is ready does Kubernetes start terminating old pods — and it only terminates as many old pods as the maxUnavailable setting allows.

spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1           # At most 1 extra pod above desired count during update
      maxUnavailable: 0     # Never reduce below desired count during update

      # With replicas: 2, maxUnavailable: 0, maxSurge: 1:
      # - New pod starts (3 pods total: 2 old + 1 new)
      # - New pod passes readiness
      # - 1 old pod terminates (back to 2 pods: 1 old + 1 new)
      # - Second new pod starts (3 pods total: 1 old + 2 new)
      # - Second new pod passes readiness
      # - Last old pod terminates (2 pods: 2 new)
      # At no point does the Service have fewer than 2 ready endpoints.

For MCP servers with SSE connections, the old pods drain their connections during the terminationGracePeriodSeconds window. The new pods serve new connections immediately after their readiness probe passes. The combination of a well-implemented readiness probe and a non-zero termination grace period gives you true zero-downtime deploys even for long-lived MCP SSE sessions.

Connection pool saturation as a readiness signal

One of the most valuable uses of the readiness probe for MCP servers is detecting database connection pool saturation. When every connection in the pool is held by a running tool call — which can happen during a burst of long-running operations — new tool calls queue waiting for a connection to become available. The MCP server is live (the event loop is processing requests) but not ready to accept new MCP connections because those connections will queue indefinitely.

// Expose pool saturation as a readiness signal
async function checkConnectionPool(): Promise<ReadinessCheck> {
  const poolStats = pool.stats();
  // If idle connections = 0 and waiting queue is non-empty, the pool is saturated
  if (poolStats.idle === 0 && poolStats.waiting > 0) {
    return {
      name: 'connection_pool',
      ok: false,
      error: `Pool saturated: ${poolStats.waiting} requests waiting for ${poolStats.total} connections`,
    };
  }
  // Also gate on pool size: if we are below minimum idle, the pool is still warming
  if (poolStats.total < poolStats.min) {
    return {
      name: 'connection_pool',
      ok: false,
      error: `Pool warming: ${poolStats.total}/${poolStats.min} minimum connections established`,
    };
  }
  return { name: 'connection_pool', ok: true };
}

This check causes the pod to leave the load balancer when saturated, reducing the flood of new connections that would otherwise worsen the saturation spiral. It is a self-regulating feedback loop: overload triggers readiness failure, which stops new traffic, which gives the pool time to clear queued work and release connections, which restores readiness.

When all pods fail readiness simultaneously

If your readiness checks gate on a shared dependency — a single database, a shared Redis cache, an external API — then all pods will fail readiness simultaneously when that dependency goes down. Kubernetes will remove all pods from the Service load balancer at the same time, making your endpoint completely unreachable from inside the cluster.

This is the boundary at which external monitoring becomes critical. AliveMCP continues probing your public endpoint regardless of Kubernetes readiness state. When all pods fail readiness and your Ingress starts returning 502 or 503, AliveMCP detects this within 60 seconds and alerts your team. The internal cluster view (readiness probe failures on individual pods) and the external view (the endpoint returning 503 to real clients) are both important signals — but only the external view represents what your users are experiencing.

Readiness probe for MCP servers with external tool dependencies

MCP servers that proxy tool calls to external APIs (OpenAI, GitHub, Stripe, a proprietary data service) face an additional readiness question: if the upstream API is down, should the pod report itself as not-ready? The answer depends on your traffic handling strategy:

• Do not include upstream API health in the readiness probe if your server can still serve some tools without that API (the failing tool will return isError: true for that specific call, which is the correct MCP error handling path). Removing the pod from the load balancer would make all tools unavailable, not just the ones that depend on the failing API — which is worse than serving partial functionality.
• Do include upstream API health in the readiness probe if every tool in your server requires the upstream API and there is no graceful degradation path. A pod that can only return errors is not ready to serve traffic in any meaningful sense.

// Decide whether to include upstream in readiness based on impact scope
async function checkUpstreamAPI(): Promise<ReadinessCheck> {
  // Only include in readiness if ALL tools require this upstream
  const required = process.env.ALL_TOOLS_REQUIRE_UPSTREAM === 'true';
  if (!required) {
    return { name: 'upstream_api', ok: true }; // Skip — partial degradation is acceptable
  }
  try {
    const resp = await fetch(`${process.env.UPSTREAM_API_URL}/health`, { signal: AbortSignal.timeout(2000) });
    return { name: 'upstream_api', ok: resp.ok };
  } catch (err) {
    return { name: 'upstream_api', ok: false, error: String(err) };
  }
}

Further reading

• MCP Server Liveness Probes — detecting hung event loops and deadlocks
• MCP Server Horizontal Scaling — HPA, KEDA, and SSE session state
• MCP Server Zero-Downtime Deployment — rolling updates and blue-green strategies
• MCP Server Health Check — /live and /ready endpoint implementations
• MCP Server on Kubernetes — Deployments, Services, and ingress configuration
• MCP Server Capacity Planning — sizing connection pools and scaling thresholds