AliveMCP

Guide · ODM Integration

MCP Tools for Mongoose — connection events, populate vs lean queries, replica set transactions

Three Mongoose behaviours regularly catch MCP server authors off-guard: Mongoose buffers operations when the connection is in a disconnected state and drains the buffer when reconnection succeeds — a tool call that arrives during a brief network blip between the MCP server and MongoDB does not fail immediately; instead it sits in the buffer for up to serverSelectionTimeoutMS (default 30 seconds), causing the tool call to appear hung to the agent before eventually timing out; populate() issues one additional query per document by default — a tool returning 50 posts with their authors issues 50 separate find({ _id: { $in: [...authorIds] } }) queries under the hood, one per populated reference, and each query acquires its own pool connection; and multi-document transactions in Mongoose require a MongoDB replica set or sharded cluster — calling session.withTransaction() against a standalone MongoDB instance (common in development) throws Transaction numbers are only allowed on a replica set member or mongos, which then silently prevents you from discovering the transaction requirement until production deployment.

TL;DR

Set serverSelectionTimeoutMS: 5000 and bufferCommands: false to fail fast on connection loss. Use Model.find().populate({ path: 'author', select: 'name email' }) — Mongoose batches via $in. Add .lean() for read-only tool results (50–70% faster, plain objects). Wrap multi-collection writes in session.withTransaction(). Health probe: mongoose.connection.db.admin().ping().

Connection lifecycle — events, buffering, and fast-fail configuration

Mongoose maintains a single default connection (mongoose.connection) with readyState: 0 (disconnected), 1 (connected), 2 (connecting), 3 (disconnecting). Model operations queue in Mongoose's internal buffer when readyState !== 1. For MCP servers that must fail fast rather than buffer, disable buffering and set short timeouts.

import mongoose from 'mongoose';

// Connect with MCP-server-appropriate timeouts
await mongoose.connect(process.env.MONGODB_URI!, {
  // How long to wait for a server that matches the topology description
  serverSelectionTimeoutMS: 5_000,  // Default 30s — too long for an MCP tool call
  // How long a send/receive on a socket can take before timeout
  socketTimeoutMS: 45_000,
  // Max connections in the pool
  maxPoolSize: 20,
  // Minimum connections kept alive
  minPoolSize: 2,
  // Return error immediately if no connection is available (don't queue)
  // Set this on individual models or globally in schema options
  // bufferCommands: false is per-schema — set it in schema definition
});

// Mongoose connection events — wire up before connect() resolves
mongoose.connection.on('connected', () => {
  console.log('Mongoose: connected to MongoDB');
});

mongoose.connection.on('error', (err) => {
  console.error('Mongoose: connection error:', err);
  // Don't exit — Mongoose will attempt to reconnect automatically
});

mongoose.connection.on('disconnected', () => {
  // Mongoose will reconnect; tool calls during disconnect go to buffer
  // (unless bufferCommands: false is set in schema)
  console.warn('Mongoose: disconnected — tool calls may queue');
});

// Schema with buffering disabled — tool calls fail immediately if disconnected
const PostSchema = new mongoose.Schema({
  title:    { type: String, required: true },
  authorId: { type: mongoose.Schema.Types.ObjectId, ref: 'User', required: true },
  body:     { type: String },
  tags:     [{ type: String }],
  createdAt: { type: Date, default: Date.now },
}, {
  bufferCommands: false, // Return error immediately if not connected — don't buffer
  autoIndex: false,      // Don't build indexes at startup in production
});

const Post  = mongoose.model('Post', PostSchema);
const User  = mongoose.model('User', UserSchema);

// Startup gate — wait for connection before starting MCP server
async function startup() {
  // mongoose.connect() resolves when the first connection is established
  // Verify with a ping after connect
  await mongoose.connection.db!.admin().ping();
  console.log('MongoDB ping OK — starting MCP server');
}

// Graceful shutdown
process.on('SIGTERM', async () => {
  await mongoose.disconnect();
  process.exit(0);
});

Mongoose's automatic reconnection is configured by the serverMonitoringMode and heartbeat frequency. In container environments where the MongoDB host may change (replica set failover), set family: 4 to force IPv4 and avoid DNS resolution delays that extend the effective reconnection window.

Populate with field selection — efficient reference resolution for MCP tools

Mongoose's populate() resolves ObjectId references by issuing a find({ _id: { $in: [...ids] } }) query per populated path. Despite the common misconception, this is not one query per document — Mongoose collects all IDs from the result set and fires one query per populated path, regardless of result set size. The problem is fetching all fields of each referenced document when you only need a few.

import { Post, User, Comment } from './models';

// Inefficient: fetches entire User document for each author reference
async function listPostsBad() {
  return Post.find().populate('authorId').limit(50);
  // Returns all User fields: name, email, passwordHash, preferences, ... for each post
}

// Better: select only needed fields from populated documents
async function listPostsGood() {
  return Post
    .find()
    .populate({
      path: 'authorId',
      select: 'name email',  // Only fetch name and email from User collection
      model: 'User',
    })
    .select('title createdAt authorId')  // Only fetch these Post fields too
    .sort({ createdAt: -1 })
    .limit(50)
    .lean();  // Return plain JS objects — no Mongoose document overhead
}

// Deep populate: nested references
async function getPostWithComments(postId: string) {
  return Post.findById(postId)
    .populate({
      path: 'comments',      // Populate the comments array
      select: 'body createdAt authorId',
      populate: {
        path: 'authorId',    // Nested populate — author of each comment
        select: 'name',
      },
      options: { limit: 20, sort: { createdAt: -1 } },
    })
    .lean();
}

// Post-query populate: when you already have documents and need to populate
// a field conditionally (avoids re-querying the Post collection)
async function populateAuthorsAfterFilter(posts: any[]) {
  return User.populate(posts, {
    path: 'authorId',
    select: 'name email avatar',
  });
}

// Virtual populate: define count without storing the array
const UserSchemaWithVirtual = new mongoose.Schema({ name: String });
UserSchemaWithVirtual.virtual('postCount', {
  ref: 'Post',
  localField: '_id',
  foreignField: 'authorId',
  count: true,  // Only return the count, not the documents
});

// Lean vs full documents
async function leanVsFull(userId: string) {
  // Full Mongoose document — has .save(), .toJSON(), virtuals, middleware
  const fullUser = await User.findById(userId);
  // fullUser is a Mongoose Document — 2-5x more memory, slower JSON serialization

  // Lean document — plain JS object
  const leanUser = await User.findById(userId).lean();
  // leanUser is { _id: ObjectId, name: 'Alice', ... } — faster, less memory
  // CANNOT call leanUser.save(), leanUser.toJSON() — no document methods
  // Use lean for read-only tool results; full documents for tool calls that update records
  return { fullUser, leanUser };
}

Use .lean() for any tool that returns data without modifying it. The performance difference is significant at scale: lean queries skip instantiating Mongoose Document objects, virtual getters, and change tracking overhead. For a tool returning 100 posts with populated authors, lean is typically 50–70% faster and uses half the memory.

Multi-document transactions — replica set requirement and session lifecycle

MongoDB multi-document transactions require a replica set or sharded cluster. A standalone mongod does not support transactions. In production deployments this is rarely a problem (Atlas, managed MongoDB, and most self-hosted setups use replica sets), but development environments often use standalone mongod, hiding the requirement until you deploy.

import mongoose from 'mongoose';
import { Post, User, AuditLog } from './models';

// Atomic tool handler: deduct credits and create a purchase record
server.tool('create_post_with_billing', async ({ userId, title, body, cost }) => {
  const session = await mongoose.startSession();

  try {
    const result = await session.withTransaction(async () => {
      // All writes within withTransaction use the session
      const user = await User.findById(userId).session(session);
      if (!user) throw new Error('User not found');
      if (user.credits < cost) throw new Error('Insufficient credits');

      // Decrement credits
      await User.findByIdAndUpdate(
        userId,
        { $inc: { credits: -cost } },
        { session, new: true }  // Must pass session to every operation
      );

      // Create the post
      const [post] = await Post.create(
        [{ title, body, authorId: userId }],
        { session }  // Model.create() with session requires array syntax
      );

      // Audit record
      await AuditLog.create(
        [{ action: 'post_created', userId, postId: post._id, cost }],
        { session }
      );

      return { postId: String(post._id), newCredits: user.credits - cost };
      // withTransaction commits on return — retries on transient errors automatically
    });

    return result;
  } finally {
    await session.endSession();  // Always end the session
  }
});

// Development environment check — log warning if running standalone MongoDB
async function checkTransactionSupport(): Promise<boolean> {
  try {
    const adminDb = mongoose.connection.db!.admin();
    const serverStatus = await adminDb.command({ isMaster: 1 });
    const isReplicaSet = !!serverStatus.setName;
    if (!isReplicaSet) {
      console.warn(
        'WARNING: MongoDB is running as a standalone instance. ' +
        'Multi-document transactions will fail. ' +
        'Use mongod --replSet rs0 in development or Docker Compose with a replica set.'
      );
    }
    return isReplicaSet;
  } catch {
    return false;
  }
}

// Schema-level concurrency control: optimistic locking with __v (versionKey)
const InventorySchema = new mongoose.Schema({
  itemId:    { type: String, required: true },
  quantity:  { type: Number, required: true, min: 0 },
}, { optimisticConcurrency: true });  // Adds __v version key — throws VersionError on stale update

// Tool with optimistic locking (single-document atomic update — no transaction needed)
server.tool('decrement_inventory', async ({ itemId, quantity }) => {
  // findOneAndUpdate is atomic at the document level — no transaction needed
  const item = await Inventory.findOneAndUpdate(
    { itemId, quantity: { $gte: quantity } },  // Only update if sufficient quantity
    { $inc: { quantity: -quantity } },
    { new: true }
  ).lean();

  if (!item) throw new Error('Item not found or insufficient quantity');
  return { itemId, remaining: item.quantity };
});

session.withTransaction() automatically retries the transaction callback on transient errors (TransientTransactionError). This is important for MCP servers where concurrent tool calls may cause write conflicts on the same documents. Do not catch TransientTransactionError inside the callback — let withTransaction handle retries. Only throw errors that should abort the transaction permanently (validation errors, business rule violations).

Health probe — Mongoose connection reachability from an MCP server

mongoose.connection.readyState tells you the current state, but does not verify the database is actually responsive. Use db.admin().ping() for a live connectivity check that traverses the actual connection.

async function checkMongooseHealth(): Promise<{
  healthy: boolean;
  readyState: number;
  readyStateLabel: string;
  latencyMs?: number;
  error?: string;
}> {
  const stateLabels: Record<number, string> = {
    0: 'disconnected',
    1: 'connected',
    2: 'connecting',
    3: 'disconnecting',
  };
  const readyState = mongoose.connection.readyState;
  const start = Date.now();

  if (readyState !== 1) {
    return {
      healthy: false,
      readyState,
      readyStateLabel: stateLabels[readyState] ?? 'unknown',
      error: \`Connection not ready: \${stateLabels[readyState]}\`,
    };
  }

  try {
    await mongoose.connection.db!.admin().ping();
    return {
      healthy: true,
      readyState,
      readyStateLabel: 'connected',
      latencyMs: Date.now() - start,
    };
  } catch (err) {
    return {
      healthy: false,
      readyState,
      readyStateLabel: 'connected-but-unresponsive',
      error: String(err),
    };
  }
}

// Pool stats for diagnostics
function poolStats() {
  const pool = (mongoose.connection as any).pool;
  return {
    totalConnectionCount: pool?.totalConnectionCount ?? 0,
    availableConnectionCount: pool?.availableConnectionCount ?? 0,
    pendingConnectionCount: pool?.pendingConnectionCount ?? 0,
  };
}

// Startup gate
async function startup() {
  const health = await checkMongooseHealth();
  if (!health.healthy) {
    console.error('Mongoose health check failed:', health.error);
    process.exit(1);
  }
  console.log(\`Mongoose ready (\${health.latencyMs}ms) — readyState: \${health.readyStateLabel}\`);
}

AliveMCP monitors your MCP server's MongoDB-backed tool endpoints on a 60-second probe cycle, tracking latency, uptime percentage, and alert routing to Slack or webhooks — giving you visibility into connection pool saturation and replica set failover events before they surface as tool call timeouts in your agents.

Related guides