MongoDB MCP Server: Build an AI Agent for Natural-Language Mongo Queries

Updated: May 18, 2026 — added the hosted MongoDB MCP option (one-click cloud deploy, live URL + bearer token).

The MongoDB MCP server turns any Claude, GPT-5, Gemini, DeepSeek or Grok client into a Mongo-fluent analyst. It exposes your collections, the aggregation framework, indexes, the slow-query profiler and Atlas cluster controls as MCP tools — so you can ask "show me daily signups for the last 30 days, broken down by source" and get an actual aggregate() pipeline run against your data.

This recipe covers both paths: the hosted route (~30 seconds, no install) for anyone who wants to get started immediately, and the self-hosted route for teams that need to run the server on their own network or against a database that's only reachable from a private VPC. The walkthrough then covers five queries that show off analytics, debugging and ops tasks, and explains connection-string mode (any Mongo) vs Atlas service-account mode (cluster management).

What the MongoDB MCP Server Provides

The server is maintained by the official mongodb-js org and ships as the mongodb-mcp-server npm package. It exposes two distinct toolsets, depending on which credentials you pass at startup:

You can pass both at once for a fully-armed agent. The --readOnly flag locks the server to non-mutating commands — strongly recommended until you trust write operations.

Prerequisites

Step 1: Start the Server with HTTP Transport

The default transport is stdio (good for Claude Desktop / Cursor). For browser-based clients like MCP Agent Studio you need HTTP — pass --transport http:

npx -y mongodb-mcp-server@latest \
  --transport http \
  --connectionString "mongodb+srv://USER:PASS@your-cluster.mongodb.net/your-db" \
  --readOnly

The server listens on http://127.0.0.1:3000 by default. Override with --httpHost and --httpPort if needed. Keep the process running — in production you'll want it under pm2, systemd, or in a container.

Step 2: Connect from MCP Agent Studio (Browser, No Install)

Easiest way to drive the server: MCP Agent Studio. Pick the pre-built MongoDB Agent template — it ships with a system prompt tuned for analytics, schema work and aggregation pipelines.

1. Open /templates/mongodb-agent and click Open in Studio.
2. Paste http://localhost:3000/mcp into the MCP server URL field.
3. Pick a model — Claude Sonnet 4.5 is the default; Opus 4.7 is the strongest for complex aggregation pipelines.
4. Send a first message: "List all databases on this cluster."

If you'd rather use Claude Desktop or Cursor, skip the --transport http flag — those clients speak stdio natively.

Step 3: Five Queries That Show What the Agent Can Do

1. Schema discovery

The agent uses the mongodb-aggregate tool with a $sample stage, then infers the schema. Useful when joining a project with no schema docs, or when you suspect a producer is writing the wrong shape.

2. Natural-language analytics

The model writes a pipeline with $match on createdAt, $group by date and source, $sort descending. You see the pipeline before it runs — copy it into your code if you want to reuse it.

3. Index audit

Calls $indexStats and filters by accesses.ops and accesses.since. Surfaces dead indexes that are wasting RAM. Pair with the "recommend an index for this slow query" prompt for a full index review.

4. Slow-query triage

Requires the profiler to be enabled (db.setProfilingLevel(1, { slowms: 100 })). The agent groups queries by namespace, surfaces the worst command shape, and suggests an index when the answer is obvious.

5. Atlas cluster snapshot

Only works when you start the server with --apiClientId + --apiClientSecret. The Atlas toolset uses the public Atlas Admin API under the hood.

Picking the Right Model

Mongo aggregation pipelines are non-trivial to write, so model choice matters more here than for, say, a Slack-message agent.

Use Compare mode in Agent Studio to send the same Mongo prompt to two models side-by-side — you'll see whose pipeline is correct in seconds.

Connection String vs Atlas Service Account

Two auth modes, two different sets of tools — easy to confuse:

• Connection string (--connectionString): Standard MongoDB URI. The agent can read/write data and inspect schemas. Works with any Mongo (local, Atlas, RDS-style hosted Mongo, self-hosted). This is what you want for analytics.
• Atlas service account (--apiClientId + --apiClientSecret): Atlas Admin API credentials. The agent can manage clusters, users, network access lists, and Search indexes — but cannot read your data. This is what you want for ops.

Pass both for the full picture. Create the service account at cloud.mongodb.com → Access Manager → Service Accounts.

Production Notes

• Always pair --readOnly with prod connection strings until you've verified the system prompt prevents accidental writes.
• Use a dedicated read-only DB user. Don't reuse the user your app writes with. Grant only the databases the agent should see.
• The HTTP transport has no auth. Bind to 127.0.0.1, or front with an auth proxy. Never expose 0.0.0.0:3000 to the public internet.
• Profiler queries can be heavy. If you enable the slow-query profiler, scope it to a database (not all of them) and use slowms: 100 or higher.
• Aggregation result sizes can blow up the model's context window. The default system prompt in the MongoDB Agent template caps results at 50 documents — keep that in your own prompts.

Related Recipes

• PostgreSQL MCP: Build a Claude Analytics Agent
• Build an AI Database Query Assistant (Supabase MCP)
• Best AI Model for MCP Tool Calling

Frequently Asked Questions