MCP server connection pooling

Why MCP changes connection pool math

In a stateless REST API with a pool of 20 connections and average query time of 50ms, you can serve 400 requests/second (20 connections ÷ 0.05s). In an MCP server, if 20 concurrent sessions each hold their connection from initialize to session close, you have zero connections available for new sessions — the pool is exhausted at 20 sessions. The fix is simple: do not hold connections across tool calls:

Acquire-per-tool-call pattern with Knex

Using Knex.js (which wraps pg, mysql2, or better-sqlite3) as an example of the acquire-per-tool-call pattern:

// db.ts — pool configuration
import knex from 'knex';

export const db = knex({
  client: 'pg',
  connection: process.env.DATABASE_URL,
  pool: {
    min: 2,
    max: 20,
    acquireTimeoutMillis: 8000,  // fail fast instead of queueing indefinitely
    idleTimeoutMillis: 30000,    // release idle connections after 30s
    reapIntervalMillis: 1000,    // check for idle connections every 1s
  },
  asyncStackTraces: process.env.NODE_ENV !== 'production',
});

// Structured pool stats for monitoring
export function getPoolStats() {
  const pool = (db.client as any).pool;
  return {
    total: pool.numUsed() + pool.numFree() + pool.numPendingAcquires(),
    used: pool.numUsed(),
    free: pool.numFree(),
    pending: pool.numPendingAcquires(),
  };
}

// tool handler — acquire per call, release in finally
server.tool(
  'search_documents',
  'Search documents by keyword',
  { query: z.string().min(1) },
  async (args) => {
    // Do NOT use a connection held at session scope — acquire per call
    let rows: unknown[];
    try {
      rows = await db('documents')
        .where('content', 'ilike', `%${args.query}%`)
        .limit(20)
        .select('id', 'title', 'snippet');
    } catch (err: any) {
      // Pool exhaustion throws with a message containing "acquire timeout"
      if (err.message?.includes('acquire')) {
        return {
          isError: true,
          content: [{ type: 'text', text: 'Service temporarily busy — please retry.' }],
        };
      }
      throw err; // Propagate unexpected errors as MCP protocol errors
    }
    return { content: [{ type: 'text', text: JSON.stringify(rows) }] };
  }
);

Knex automatically returns the connection to the pool after every query chain completes. You do not need an explicit release call. If you use raw connection objects (e.g., pg's pool.connect()), always release in a finally block — a missing release on the error path is the most common cause of pool exhaustion in production.

Pool size formula

Start with this formula, then tune based on observed pool stats:

pool_max = target_concurrent_sessions × avg_tool_calls_per_session × db_query_fraction × concurrency_factor

# Realistic example:
# 100 concurrent sessions
# 3 tool calls per session on average (but not all at once)
# 60% of tool calls hit the database
# At peak, ~20% of sessions are in an active tool call simultaneously
#
# pool_max = 100 × 3 × 0.6 × 0.2 = 36 → round up to 40

# PostgreSQL rule: total connections across all app instances must be below
# max_connections (default 100) minus connections reserved for admin/replication.
# For a single instance: pool_max ≤ 80 (leaving 20 for admin).
# For N instances: pool_max_per_instance ≤ 80 / N.

PostgreSQL's max_connections is a hard server-side limit. If your application opens more connections than the server allows, connections are refused with FATAL: sorry, too many clients already. For multiple application instances on a single database, use a connection pooler (PgBouncer in transaction mode) between the app and PostgreSQL — PgBouncer multiplexes many application connections onto a small number of server-side connections.

Pool exhaustion detection and alerting

Log pool stats on every tool call and alert when pending acquisitions exceed zero for more than one probe cycle:

// Middleware: log pool stats on every MCP request
app.use('/mcp', (req, res, next) => {
  const stats = getPoolStats();
  // Alert when more than 10% of pool is waiting
  if (stats.pending > 0) {
    console.warn({ event: 'pool_pressure', ...stats });
  }
  res.on('close', () => {
    // Log post-request pool state to detect connection leaks
    const after = getPoolStats();
    if (after.used > stats.used) {
      console.error({ event: 'possible_connection_leak', before: stats, after });
    }
  });
  next();
});

AliveMCP measures initialize latency on every probe. If your initialize handler runs a startup query (e.g., loading user context from the DB), pool pressure will cause probe latency to spike. This is an early warning of pool exhaustion before it starts failing user-facing tool calls. Configure an AliveMCP latency alert at P95 > 500ms to catch pool pressure before it becomes pool exhaustion.

Redis connection pooling

For Redis (used in caching, rate limiting, or distributed session state), the same acquire-per-operation discipline applies. The ioredis client maintains an internal connection pool; use a single shared client instance rather than creating a new client per session or tool call:

// redis.ts — shared client, do NOT create per-session
import Redis from 'ioredis';

export const redis = new Redis(process.env.REDIS_URL!, {
  maxRetriesPerRequest: 3,
  enableOfflineQueue: false,  // fail fast when Redis is unreachable
  connectTimeout: 5000,
  lazyConnect: true,
  // Connection pool via ioredis Cluster or explicit pool size:
  // For ioredis single-node: one TCP connection, commands pipelined
  // For high-throughput: use ioredis.Cluster or a dedicated pooler
});

// Graceful shutdown
export async function closeRedis() {
  await redis.quit();
}

Unlike PostgreSQL, Redis uses a single multiplexed connection by default (ioredis pipelines commands). Connection pool exhaustion is rarely a Redis problem unless you're creating a new client per session. The common mistake is forgetting to call quit() during graceful shutdown — leaving Redis connections open causes NOAUTH errors on the next startup if the Redis server reuses the connection.

Related questions

Further reading

• MCP server caching — LRU cache to reduce DB queries per tool call
• MCP server rate limiting — Redis-based sliding window for tool call limits
• MCP server graceful shutdown — draining pool connections before process exit
• MCP server load testing — finding pool exhaustion ceiling under concurrent sessions
• MCP server error handling — surfacing pool exhaustion as isError results
• MCP server observability — exporting pool metrics to Prometheus
• AliveMCP — probe latency spikes as an early warning for connection pool pressure