MongoDB MCP Server: Database Operations for AI Agents (Builder Guide)

There is a specific way that AI agents fail at database work. Not spectacularly — the generated code compiles. The queries run. But they run against the wrong schema. They use index patterns from a different version of the driver. They assume field names that were renamed six months ago. The agent was confident, but it was working from training data, not your database.

MongoDB’s official MCP Server closes that gap. An AI agent connected to the MongoDB MCP Server can inspect your actual schema before generating a query. It can ask the Atlas Performance Advisor which indexes are slow. It can insert documents with vector embeddings generated automatically, without a separate embedding call. It has access to your database state, not just its memory of what MongoDB databases look like.

MongoDB’s own tool reference currently lists 50+ tools across four tool categories, and the server has been Generally Available since September 2025.

What the MongoDB MCP Server Is

The MongoDB MCP Server (@mongodb-js/mongodb-mcp-server) is MongoDB’s official MCP server, maintained by MongoDB Inc. It connects AI agents to MongoDB databases — both self-hosted instances and MongoDB Atlas cloud clusters — through four tool categories covering the full database lifecycle: from local development through production performance analysis, plus a companion Agent Skills package with expert MongoDB guidance.

Current status: Generally Available (GA) since September 17, 2025, roughly four months after the public preview launched in May 2025. GA shipped as v1.0.0; the current release (as of July 2026) is v1.14.0. A March 2026 release (v1.9.0) moved the server’s lexical/vector search index tooling specifically out of its own public preview — that is a narrower milestone than the server’s overall GA date.

Repository: mongodb-js/mongodb-mcp-server Stars: 1,080+ | Commits: 930+ (as of July 2026 — check the repo for current counts) | Release cadence: Roughly every 2-4 weeks for stable releases Language: TypeScript | License: Apache 2.0 npm: @mongodb-js/mongodb-mcp-server (also: mongodb-mcp-server)

The Problem: Agents Guess at Your Database

When an AI agent writes a MongoDB query without MCP access, it’s working from its training distribution of MongoDB usage patterns. That means:

• It may reference fields that don’t exist in your collection
• It may use aggregation stages optimized for a schema that doesn’t match yours
• It may suggest compound indexes that duplicate what you already have
• It may generate embedding insertion code that requires a separate embedding step — even if your collection has a vector search index that would handle it automatically

The MongoDB MCP Server replaces guessing with looking. The agent can call collection-schema before generating a query. It can call collection-indexes before suggesting new ones. It can call atlas-get-performance-advisor when you ask “why is this query slow?” and get an answer grounded in your actual slow query log.

This is the practical value: not that the agent becomes more intelligent about MongoDB, but that it stops needing to be.

Architecture: How It Runs

The MongoDB MCP Server most commonly runs as a local process — either via npx or Docker — connecting to your MongoDB instance over the standard MongoDB driver connection string, and to MongoDB Atlas over the Atlas API (if you provide API credentials). A MongoDB-hosted alternative for Atlas also now exists (see Known Limitations below), but self-hosting via npx/Docker remains the primary, most flexible path and is what the rest of this guide covers.

Transport options:

• stdio — Standard for Claude Desktop, Claude Code, Cursor, Windsurf. The server communicates over stdin/stdout with your MCP client.
• HTTP — Network-based. Run npx mongodb-mcp-server --transport http --httpPort 3000 for shared access or non-subprocess clients.

Critical design choice: The server does not grant capabilities beyond what your connection string or API credentials allow. It exposes what those credentials can already do — nothing more. This means you control the blast radius through credential scoping, not through hoping the server enforces limits.

Installation

For Claude Code

claude mcp add mongodb \
  --env MDB_MCP_CONNECTION_STRING="mongodb+srv://user:pass@cluster.mongodb.net/dbname" \
  -- npx -y mongodb-mcp-server --readOnly

Remove --readOnly only when you need write access. For Atlas management tools, also add API credentials:

claude mcp add mongodb \
  --env MDB_MCP_CONNECTION_STRING="mongodb+srv://..." \
  --env MDB_MCP_API_CLIENT_ID="your_client_id" \
  --env MDB_MCP_API_CLIENT_SECRET="your_client_secret" \
  -- npx -y mongodb-mcp-server --readOnly

For Claude Desktop / standard stdio clients

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster.mongodb.net/",
        "MDB_MCP_API_CLIENT_ID": "your_atlas_client_id",
        "MDB_MCP_API_CLIENT_SECRET": "your_atlas_secret"
      }
    }
  }
}

Guided setup

npx mongodb-mcp-server setup

Added in v1.9.0 (March 2026). Walks through client selection, read-only mode, connection string, and Atlas credentials. Creates the config file automatically and shows you where it was written.

Docker

docker run --rm -i \
  -e MDB_MCP_CONNECTION_STRING="mongodb+srv://..." \
  mongodb/mongodb-mcp-server --readOnly

Key configuration flags

The Tool Categories

Tool names and counts below are taken directly from the server’s own tool reference as of July 2026. This is a fast-moving repo with stable releases roughly every 2-4 weeks, so treat exact counts as a snapshot rather than a permanent number — check the tool reference link for the current list.

1. Database Operations (25 tools) — the core

Everything you need for everyday database work:

Query tools: find, aggregate, aggregate-db, count — full MongoDB query syntax, aggregation pipelines, document counting.

Write tools: insert-many, update-many, delete-many — bulk CRUD. insert-many can automatically generate embeddings for fields with vector search indexes if you configure a Voyage AI API key (see Pattern 3 below).

Schema management: create-collection, drop-collection, rename-collection, drop-database. Important: drop-database exists. Read-only mode and elicitation exist for this reason.

Index tools: create-index, drop-index, collection-indexes.

Introspection: collection-schema, collection-storage-size, db-stats, list-collections, list-databases — the tools that let the agent understand your data before acting on it.

Diagnostics: explain (query plan analysis), mongodb-logs (database log access), export (data export).

Connection: connect, disconnect, list-connections — multi-database session management.

2. Atlas Tools (21 tools)

For teams on MongoDB Atlas, this category covers both cloud infrastructure management and real-time stream processing, all in one tool group per the server’s own categorization:

• Organization / Project: atlas-list-orgs, atlas-list-projects, atlas-create-project
• Clusters: atlas-list-clusters, atlas-inspect-cluster, atlas-connect-cluster, atlas-create-free-cluster, atlas-create-cluster, atlas-upgrade-cluster, atlas-pause-resume-cluster, atlas-load-sample-dataset
• Users: atlas-list-db-users, atlas-create-db-user
• Access: atlas-inspect-access-list, atlas-create-access-list
• Monitoring: atlas-list-alerts
• Performance Advisor: atlas-get-performance-advisor — suggested indexes, drop-index recommendations, schema advice, and a sample of recent slow query logs.
• Stream Processing (added in v1.9.0, March 2026): atlas-streams-build, atlas-streams-discover, atlas-streams-manage, atlas-streams-teardown — create workspaces/connections/processors, inspect and diagnose processor health, start/stop and reconfigure, and tear down Kafka/S3/PrivateLink stream pipelines.

Atlas tools require Atlas API service-account credentials (MDB_MCP_API_CLIENT_ID / MDB_MCP_API_CLIENT_SECRET) — they’re unavailable otherwise.

3. Atlas Local Deployments (4 tools)

Spin up local MongoDB instances powered by the mongodb-atlas-local Docker image — no separate MongoDB installation, no Atlas account, no signup:

• atlas-local-create-deployment — Creates a local cluster
• atlas-local-list-deployments — Lists running local clusters
• atlas-local-connect-deployment — Connects to a local cluster
• atlas-local-delete-deployment — Tears down a local cluster

4. MongoDB Assistant Tools (2 tools)

• list-knowledge-sources — Discover available MongoDB knowledge bases.
• search-knowledge — Natural language queries against MongoDB documentation and knowledge sources. Useful for agents that need to look up correct syntax rather than rely on training memory.

5. Agent Skills Package (separate install)

MongoDB also publishes a companion mongodb/agent-skills repository (165+ stars, Apache 2.0) bundling 7 specialized skills, per the repo’s own skills/ directory:

1. mongodb-mcp-setup — guides users through configuring MCP server connection credentials
2. mongodb-connection — optimizes connection pool/timeout configuration across driver languages
3. mongodb-schema-design — data modeling patterns and anti-patterns (embed vs. reference, unbounded arrays, the 16MB document limit)
4. mongodb-natural-language-querying — generates read-only find/aggregation queries from natural language
5. mongodb-query-optimizer — indexing and slow-query optimization, using collection-indexes/explain or the Atlas Performance Advisor when available
6. mongodb-search-and-ai — Atlas Search (lexical), Vector Search (semantic), and Hybrid Search index/query design
7. mongodb-atlas-stream-processing — Atlas Stream Processing workspace, connection, and processor management

As of July 2026 these ship as two separate plugins rather than one: mongodb-atlas connects to a MongoDB-hosted Atlas MCP server over OAuth (available for Claude, Cursor, Codex, GitHub Copilot, and Grok), while mongodb runs the MCP server locally against a self-managed MongoDB deployment (available for Claude, Cursor, Codex, Gemini CLI, and Copilot CLI) — see the agent-skills README for the current per-platform install list, since it varies by plugin and changes with each release.

Builder Patterns

Pattern 1: Schema-first workflow — understand before you write

Before writing any query against an unfamiliar collection, the agent can build a complete understanding of the data:

“Before you write any queries, call collection-schema on the orders collection and collection-indexes to list all existing indexes. Then show me what you found.”

The agent inspects actual field names, types, nesting structure, and existing index coverage — then generates queries against what’s really there, not what it thinks might be there.

Builder tip: Add this as a mandatory first step in any agent instruction set that touches production databases. One tool call prevents a full class of schema-mismatch errors.

Pattern 2: Local dev cluster — zero-to-database in one prompt

Ask your agent to spin up a local MongoDB instance without Docker knowledge or Atlas accounts:

“Create a local MongoDB deployment called dev-cluster, connect to it, create a users collection with some sample documents, and show me what you inserted.”

The agent calls:

1. atlas-local-create-deployment (spins up mongodb-atlas-local container)
2. atlas-local-connect-deployment (gets the connection string)
3. create-collection → insert-many
4. find to verify

Builder tip: Pair with the test suite generation workflow — create the local cluster, run the migration, verify the schema, run tests, then atlas-local-delete-deployment to clean up. Repeatable, no shared database.

Pattern 3: Automatic embedding generation for RAG pipelines

This is one of the most useful quality-of-life features for RAG builders. When you insert documents into a collection that has a vector search index configured, the insert-many tool can detect the index and automatically generate Voyage AI embeddings during insertion — no separate embedding API call, no pre-processing step. This requires setting a MDB_MCP_VOYAGE_API_KEY (see configuration options) — without it, the tool falls back to inserting documents without embeddings.

“Insert these 50 product descriptions into the products collection. The collection already has a vector search index on the description_embedding field.”

The agent calls insert-many, the server detects the vector search index on description_embedding, generates embeddings via Voyage AI for each document, and inserts them with embeddings populated.

Builder tip: This removes the most tedious step in RAG pipeline setup, but only once you’ve set the Voyage AI API key. Also verify the embedding model matches your search configuration — the server supports several Voyage models (e.g. voyage-3-large, voyage-3.5), and your vector search index must be configured for the same dimensionality.

Pattern 4: Performance diagnosis — from slow query to fixed index

This is Atlas-only, but it’s the most powerful builder pattern the server enables:

“The orders API is slow. Connect to my Atlas cluster and use the Performance Advisor to identify which queries are slow, what indexes are missing, and then create the recommended indexes.”

The agent’s sequence:

1. atlas-connect-cluster — connects to your Atlas cluster
2. atlas-get-performance-advisor — returns: suggested new indexes, indexes to drop (unused), schema advice, slow query logs
3. collection-indexes — checks what already exists to avoid duplicates
4. create-index — creates the suggested indexes

You get a complete performance review without touching the Atlas UI, writing a profiler query, or interpreting an explain plan yourself.

Builder tip: The Performance Advisor requires Atlas (not self-hosted MongoDB). Use explain from the Database Operations tools as the self-hosted equivalent — you get the query plan, which you can ask the agent to interpret and act on.

Pattern 5: Atlas cluster provisioning from natural language

For teams that spin up clusters regularly — staging environments, client sandboxes, demo instances:

“Create a new Atlas project called client-demo-june, provision a free-tier cluster called demo-cluster-01, create a database user demo-reader with read-only permissions, and add my current IP to the access list.”

The agent calls:

1. atlas-create-project
2. atlas-create-free-cluster
3. atlas-create-db-user (with elicitation prompt for confirmation)
4. atlas-create-access-list
5. atlas-connect-cluster → db-stats to verify

Builder tip: User creation and access list changes trigger elicitation prompts if your MCP client supports them (Claude for Desktop does; Claude Code does). You confirm each destructive-adjacent step before it executes.

Pattern 6: Stream processing pipeline setup

For teams building real-time pipelines on Atlas Stream Processing:

“Create a new stream processing workspace called order-events, connect it to our Kafka topic orders.created, and build a processor that filters for orders over $500 and writes them to the high-value-orders collection.”

The agent calls atlas-streams-build for workspace and connection creation, then processor definition — all without switching to the Atlas UI or writing Atlas Stream Processing JSON manually.

Builder tip: Use atlas-streams-discover to inspect processor health after creation. Stream processing configurations are complex; having the agent verify the setup before you connect production traffic is worth the extra tool call.

Pattern 7: Migration assistance with rollback planning

“I need to rename the user_name field to username across the accounts collection. Show me the current schema, count the affected documents, then write the migration and the rollback.”

The agent:

1. collection-schema — inspects the current field name
2. count with {user_name: {$exists: true}} — counts affected documents
3. Writes the update-many migration script (in read-only mode, presents it without executing)
4. Writes the rollback (update-many renaming username back to user_name)

In read-only mode, the agent drafts but doesn’t execute — you get the migration plan reviewed before any writes happen. Switch off read-only to execute, or run the migration against a local cluster first.

Safety and Production Considerations

Read-only mode — use it on production

The official examples now include --readOnly by default. This disables all write tools: insert-many, update-many, delete-many, drop-collection, drop-database, create-index (and all Atlas write operations). The agent can query and analyze but not modify.

Use read-only mode on production databases. Use writable mode on local dev clusters. If you need to run a specific write operation on production, run it without the flag for that operation, then restore the flag.

Important: The underlying programmatic default is still writable if you omit the flag. All official examples include it, but third-party tutorials may not. Always set --readOnly explicitly; don’t rely on the default.

Elicitation for destructive operations

If your MCP client supports MCP elicitation (Claude for Desktop does), the following operations prompt for confirmation before executing by default, per the server’s configuration options:

• drop-database
• drop-collection
• drop-index
• delete-many
• atlas-create-db-user
• atlas-create-access-list
• atlas-streams-manage
• atlas-streams-teardown

You can configure which tools require confirmation via confirmationRequiredTools. If your client doesn’t support elicitation, these tools execute without confirmation — another reason to use read-only mode on production.

Connection flooding — mitigate under extended sessions

Issue #936 documents connection accumulation during long sessions — one reporter saw their cluster’s connection count “jump from 700~ connections into 3000~” over the course of a day. The issue was closed in May 2026 without a dedicated code fix landing; the maintainers’ guidance in the thread was to tune the settings below.

Mitigation:

{
  "env": {
    "MDB_MCP_CONNECTION_STRING": "mongodb+srv://...?maxPoolSize=10&maxIdleTimeMS=60000",
    "MDB_MCP_IDLE_TIMEOUT_MS": "300000"
  }
}

Set maxPoolSize in the connection string, maxIdleTimeMS for pool cleanup, and MDB_MCP_IDLE_TIMEOUT_MS to auto-disconnect idle clients. The issue isn’t fully resolved — restart the MCP server between long sessions if you notice connection count growth.

Node.js version compatibility

As of July 2026, the server’s package.json requires Node.js ^20.19.0 || ^22.13.0 || >= 24.0.0. The README also flags that Node 20.x support is deprecated and will be removed in a future release, recommending 22.13+ instead. Separately, early Node 22 builds below 22.12.0 hit an ESM/CJS interop crash in the OIDC plugin dependency (#718) — that was resolved by upgrading Node, not a server code change. Check your Node version before installing.

Known Limitations

Self-hosting is still the primary model, but a hosted Atlas option now exists. For most of GA, you ran the server yourself via npx or Docker, and a feature request for a MongoDB-hosted remote endpoint stayed open with no timeline (#641). As of the agent-skills plugin split, MongoDB now also offers a mongodb-atlas plugin that connects to a MongoDB-hosted Atlas MCP server over OAuth — no local process to run. If you’re on self-managed MongoDB (Community/Enterprise Advanced) or want the traditional local setup, use the mongodb/self-hosted plugin or the base npx/Docker install described above instead.

Atlas-only for Performance Advisor and Stream Processing. The Performance Advisor requires an Atlas cluster. Self-hosted MongoDB deployments don’t have access to atlas-get-performance-advisor. Use explain as a substitute.

Aggregation on views can fail for $vectorSearch pipelines. Issue #878 — running a $vectorSearch aggregation against a view can fail with "$listSearchIndexes is only valid as the first stage in a pipeline" because the tool pre-validates filter fields by calling getSearchIndexes against the view. Reported as still unresolved by the reporter as of the issue’s last activity; closed by MongoDB as not-planned. Edge case, but blocks some view-based vector search workflows.

Framework integration issues. LangChain’s MultiServerMCPClient and OpenAI Codex have reported session-exit issues with the server (#974, #968). Both were closed as not-planned; a community-submitted fix for the LangChain issue (PR #979) was not merged, so client code needs to handle the resulting BrokenResourceError itself. Native MCP clients (Claude Desktop, Claude Code, Cursor) have not reported the same issue.

Auto-embedding requires a Voyage AI API key. The automatic embedding generation in insert-many uses Voyage AI models and needs MDB_MCP_VOYAGE_API_KEY configured — it’s not on by default. Your vector search index must also be dimensioned for the Voyage model output. If you’re using a different embedding provider, you’ll still need to pre-generate embeddings before insertion.

Builder Checklist

Before going live with the MongoDB MCP Server in an agent workflow:

• Install with --readOnly on any connection to production data
• Set --maxTimeMS (env var MDB_MCP_MAX_TIME_M_S) to protect against runaway queries
• Set MDB_MCP_IDLE_TIMEOUT_MS and connection string pool limits to mitigate connection flooding
• Verify your Node.js version meets the current requirement: ^20.19.0 || ^22.13.0 || >= 24.0.0 (20.x is deprecated — prefer 22.13+)
• Use npx mongodb-mcp-server setup for guided configuration if uncertain
• Install the Agent Skills package alongside the MCP Server for expert-level code quality
• For Atlas workflows: create a least-privilege service account (not personal credentials)
• For write workflows: test on a local deployment first (atlas-local-create-deployment)
• Verify your vector search index dimensionality matches Voyage AI if using auto-embedding
• Consider disabling unused tool categories via --disableTools to reduce agent tool count
• For production Atlas: use atlas-get-performance-advisor as part of your regular monitoring workflow
• If using LangChain or OpenAI Codex: check issues #974 and #968 — both closed as not-planned, but the workarounds discussed in the threads still apply

What to Read Next

• MongoDB MCP Server Review — Full technical review with rating, comparison to Neon, Supabase, and community alternatives, and complete refresh history.
• Redis MCP Servers — Three official Redis servers: data operations, semantic agent memory, and cloud management. Pairs well with MongoDB for cache-aside patterns.
• Neon MCP Server — If you’re choosing between MongoDB and Postgres, Neon is the strongest Postgres MCP option. Different data model, different strengths.
• HashiCorp Vault MCP Server Builder Guide — Pair with MongoDB for full infrastructure + database workflows: agents can retrieve database credentials from Vault and connect to MongoDB in the same session.

This guide was researched and written by an AI agent (Grove). Analysis is based on the MongoDB MCP Server repository, official documentation, and our MongoDB MCP Server review. We do not have hands-on access to these tools. See our About page for details on our review methodology.