MCP Server MongoDB — connecting and exposing MongoDB data as MCP tools

MongoDB driver setup: native driver vs Mongoose

MCP servers have different requirements than web application backends. There's no Mongoose-style ODM benefit here — you don't need schema enforcement at the ORM layer because Zod handles that at the tool parameter boundary. Mongoose's overhead (schema validation, middleware hooks, model compilation) adds 5–20ms per operation and increases cold-start memory. Use the native mongodb driver instead.

import { MongoClient, ServerApiVersion, Db } from 'mongodb';

const MONGO_URI = process.env.MONGODB_URI!;

// Singleton client — created once, reused across all tool calls
let _client: MongoClient | null = null;
let _db: Db | null = null;

export async function getDb(dbName = 'app'): Promise<Db> {
  if (_db) return _db;

  _client = new MongoClient(MONGO_URI, {
    serverApi: {
      version: ServerApiVersion.v1,
      strict: true,       // reject deprecated operators
      deprecationErrors: true
    },
    maxPoolSize: 10,      // tune to your Atlas tier's connection limit
    minPoolSize: 2,
    connectTimeoutMS: 5000,
    socketTimeoutMS: 30000,
    serverSelectionTimeoutMS: 5000
  });

  await _client.connect();
  _db = _client.db(dbName);
  return _db;
}

// TypeScript document interface — mirrors your collection's shape
export interface ProductDoc {
  _id?: import('mongodb').ObjectId;
  sku: string;
  name: string;
  price: number;
  status: 'active' | 'discontinued' | 'draft';
  tags: string[];
  createdAt: Date;
  updatedAt: Date;
}

export async function closeDb(): Promise<void> {
  await _client?.close();
  _client = null;
  _db = null;
}

Call getDb() in each tool handler rather than at module load time. This defers connection establishment until the first tool call, which keeps startup fast and lets the MCP server respond to initialize before the database connection is established.

CRUD tool patterns

The key safety rule for MongoDB tool parameters: never accept a raw filter object from the MCP caller and pass it directly to MongoDB. A caller could inject { "$where": "sleep(10000)" } or use $regex with catastrophic backtracking. Instead, define explicit Zod schemas for each allowed field and build the MongoDB filter programmatically.

import { z } from 'zod';
import { ObjectId, Filter } from 'mongodb';
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
import { getDb, ProductDoc } from './db.js';

// ---- find_documents ----
server.tool(
  'find_documents',
  {
    // Explicit allow-list — not z.record(z.unknown())
    sku: z.string().optional(),
    status: z.enum(['active', 'discontinued', 'draft']).optional(),
    tag: z.string().optional(),
    limit: z.number().int().min(1).max(100).default(20),
    skip: z.number().int().min(0).default(0),
    projection: z.array(z.string()).optional()
  },
  async ({ sku, status, tag, limit, skip, projection }) => {
    const db = await getDb();
    const filter: Filter<ProductDoc> = {};
    if (sku) filter.sku = sku;
    if (status) filter.status = status;
    if (tag) filter.tags = tag; // MongoDB matches if array contains value

    const proj = projection
      ? Object.fromEntries(projection.map(f => [f, 1]))
      : undefined;

    const docs = await db.collection<ProductDoc>('products')
      .find(filter, { projection: proj })
      .skip(skip)
      .limit(limit)
      .toArray();

    return {
      content: [{
        type: 'text',
        text: JSON.stringify(docs.map(serializeDoc), null, 2)
      }]
    };
  }
);

// ---- insert_document ----
server.tool(
  'insert_document',
  {
    sku: z.string().min(1),
    name: z.string().min(1),
    price: z.number().positive(),
    status: z.enum(['active', 'discontinued', 'draft']).default('draft'),
    tags: z.array(z.string()).default([])
  },
  async (params) => {
    const db = await getDb();
    const now = new Date();
    const result = await db.collection<ProductDoc>('products').insertOne({
      ...params,
      createdAt: now,
      updatedAt: now
    });
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ insertedId: result.insertedId.toHexString() })
      }]
    };
  }
);

// ---- update_document ----
server.tool(
  'update_document',
  {
    id: z.string().length(24, 'Must be a 24-character hex ObjectId'),
    name: z.string().optional(),
    price: z.number().positive().optional(),
    status: z.enum(['active', 'discontinued', 'draft']).optional(),
    tags: z.array(z.string()).optional()
  },
  async ({ id, ...fields }) => {
    const db = await getDb();
    const setFields: Partial<ProductDoc> = { updatedAt: new Date() };
    if (fields.name !== undefined) setFields.name = fields.name;
    if (fields.price !== undefined) setFields.price = fields.price;
    if (fields.status !== undefined) setFields.status = fields.status;
    if (fields.tags !== undefined) setFields.tags = fields.tags;

    const result = await db.collection<ProductDoc>('products').updateOne(
      { _id: new ObjectId(id) },
      { $set: setFields }
    );
    if (result.matchedCount === 0) {
      throw new McpError(ErrorCode.InvalidParams, `No document with id ${id}`);
    }
    return {
      content: [{ type: 'text', text: JSON.stringify({ modifiedCount: result.modifiedCount }) }]
    };
  }
);

// ---- delete_document ----
server.tool(
  'delete_document',
  { id: z.string().length(24) },
  async ({ id }) => {
    const db = await getDb();
    const result = await db.collection<ProductDoc>('products')
      .deleteOne({ _id: new ObjectId(id) });
    return {
      content: [{ type: 'text', text: JSON.stringify({ deletedCount: result.deletedCount }) }]
    };
  }
);

The helper serializeDoc converts ObjectId and Date fields to strings before JSON serialization — covered in the Resources section below.

Aggregation pipeline as a tool

A generic run_aggregation tool that accepts a raw pipeline from the caller is powerful but dangerous. Any caller with access to the tool can run arbitrary read operations across the entire collection, including $lookup joins to other collections, $out to write results to a new collection, or $graphLookup queries that can OOM the server. Restrict this tool to trusted admin contexts only.

The safer alternative for most use cases is named aggregate tools with hardcoded pipelines:

// SAFE: named aggregate tool with hardcoded pipeline
server.tool(
  'count_products_by_status',
  { /* no parameters — pipeline is fixed */ },
  async () => {
    const db = await getDb();
    const result = await db.collection<ProductDoc>('products').aggregate([
      { $group: { _id: '$status', count: { $sum: 1 } } },
      { $sort: { count: -1 } }
    ]).toArray();
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
    };
  }
);

server.tool(
  'revenue_by_tag',
  {
    start_date: z.string().datetime(),
    end_date: z.string().datetime()
  },
  async ({ start_date, end_date }) => {
    const db = await getDb();
    const result = await db.collection('orders').aggregate([
      {
        $match: {
          createdAt: {
            $gte: new Date(start_date),
            $lte: new Date(end_date)
          },
          status: 'completed'
        }
      },
      { $unwind: '$items' },
      {
        $lookup: {
          from: 'products',
          localField: 'items.sku',
          foreignField: 'sku',
          as: 'product'
        }
      },
      { $unwind: '$product' },
      { $unwind: '$product.tags' },
      {
        $group: {
          _id: '$product.tags',
          totalRevenue: { $sum: { $multiply: ['$items.price', '$items.qty'] } }
        }
      },
      { $sort: { totalRevenue: -1 } },
      { $limit: 20 }
    ]).toArray();

    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
    };
  }
);

// DANGEROUS: only expose in admin-scoped MCP servers
server.tool(
  'run_aggregation',
  {
    collection: z.enum(['products', 'orders', 'customers']), // explicit allow-list
    pipeline: z.array(z.record(z.unknown())).max(10)         // cap pipeline depth
  },
  async ({ collection, pipeline }) => {
    // Reject dangerous stages
    const dangerousStages = ['$out', '$merge', '$indexStats', '$currentOp'];
    for (const stage of pipeline) {
      const key = Object.keys(stage)[0];
      if (dangerousStages.includes(key)) {
        throw new McpError(ErrorCode.InvalidParams, `Stage ${key} is not permitted`);
      }
    }
    const db = await getDb();
    const result = await db.collection(collection).aggregate(pipeline).toArray();
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
    };
  }
);

Exposing collections as MCP resources

MCP resources let clients browse and read data without calling a tool. For MongoDB, a natural resource hierarchy is: collections as the resource list, and individual documents as resources identified by a URI. The trickiest part is ObjectId serialization — ObjectId.toJSON() produces a plain string in some contexts and an object in others depending on the MongoDB driver version. Use .toHexString() explicitly.

import {
  ListResourcesRequestSchema,
  ReadResourceRequestSchema
} from '@modelcontextprotocol/sdk/types.js';
import { ObjectId } from 'mongodb';

// Serialize a MongoDB document for MCP content
function serializeDoc(doc: Record<string, unknown>): Record<string, unknown> {
  return JSON.parse(JSON.stringify(doc, (_key, value) => {
    if (value instanceof ObjectId) return value.toHexString();
    if (value instanceof Date) return value.toISOString();
    return value;
  }));
}

server.setRequestHandler(ListResourcesRequestSchema, async () => {
  const db = await getDb();
  const collections = await db.listCollections().toArray();

  const resources = await Promise.all(
    collections.map(async (col) => {
      const count = await db.collection(col.name).estimatedDocumentCount();
      return {
        uri: `mongodb://${col.name}`,
        name: col.name,
        description: `${count.toLocaleString()} documents`,
        mimeType: 'application/json'
      };
    })
  );

  return { resources };
});

server.setRequestHandler(ReadResourceRequestSchema, async ({ params }) => {
  // URI scheme: mongodb://{collection}/{objectId}
  const match = params.uri.match(/^mongodb:\/\/([^/]+)\/([a-f0-9]{24})$/);
  if (!match) {
    throw new McpError(ErrorCode.InvalidParams, `Unrecognised URI: ${params.uri}`);
  }
  const [, collection, hexId] = match;

  const db = await getDb();
  const doc = await db.collection(collection).findOne({ _id: new ObjectId(hexId) });
  if (!doc) {
    throw new McpError(ErrorCode.InvalidParams, `Document ${hexId} not found in ${collection}`);
  }

  return {
    contents: [{
      uri: params.uri,
      mimeType: 'application/json',
      text: JSON.stringify(serializeDoc(doc as Record<string, unknown>), null, 2)
    }]
  };
});

One important caveat: estimatedDocumentCount() uses collection metadata and is fast (constant time), but it can return stale counts after an unclean shutdown. Use countDocuments() if accuracy is critical, at the cost of a full collection scan for large collections.

Health endpoint: /health/mongodb

The /health/mongodb endpoint should verify that the connection is live, the server is reachable, and the connection pool is healthy. A ping command tests the round-trip; listCollections confirms database-level access.

import express from 'express';

const app = express();

app.get('/health/mongodb', async (_req, res) => {
  const start = Date.now();
  try {
    const db = await getDb();

    // 1. Ping — fastest liveness check
    await db.command({ ping: 1 });
    const pingMs = Date.now() - start;

    // 2. List collections — confirms DB-level access
    const collections = await db.listCollections().toArray();

    // 3. Connection pool stats (native driver exposes these)
    const client = db.client as import('mongodb').MongoClient;
    // @ts-ignore — internal property, present on native driver
    const pool = (client as unknown as { topology?: { s?: { pool?: {
      totalConnectionCount: number;
      availableConnectionCount: number;
      pendingConnectionCount: number;
    } } } }).topology?.s?.pool;

    res.json({
      status: 'ok',
      ping_ms: pingMs,
      collections: collections.length,
      pool: pool ? {
        total: pool.totalConnectionCount,
        available: pool.availableConnectionCount,
        pending: pool.pendingConnectionCount
      } : null
    });
  } catch (err) {
    res.status(503).json({
      status: 'error',
      error: (err as Error).message,
      elapsed_ms: Date.now() - start
    });
  }
});

Wire AliveMCP to this endpoint with a 30-second check interval. A 503 response triggers an immediate alert. A response where pool.available === 0 and pool.pending > 0 indicates pool exhaustion — all connections are busy and new operations are queuing. This is a precursor to timeout errors that may not yet surface as a 503.

Silent failure modes and AliveMCP monitoring

MongoDB has several failure modes that don't surface as HTTP errors on the MCP server process, meaning a naive HTTP check returns 200 while callers experience errors.

AliveMCP monitors your /health/mongodb endpoint and alerts you the moment connection pool exhaustion or replica failover affects tool availability — before callers start filing bug reports.

Frequently asked questions

Further reading

• MCP Server Postgres — pg driver, connection pooling, and query tools
• MCP Server Redis — caching, pub/sub, and session storage for MCP
• MCP Server Health Check — designing endpoints for uptime monitors
• MCP Server Connection Pooling — pool sizing and exhaustion detection
• MCP Server Error Handling — mapping database errors to McpError codes