MongoDB MCP Server: Setup and Read-Only Mode

The MongoDB MCP server is MongoDB’s official MCP server, published as mongodb-mcp-server from the mongodb-js/mongodb-mcp-server repository. It gives an AI agent two sets of tools: database tools that query and change collections through a connection string, and Atlas tools that manage clusters, users and access lists through Atlas API credentials. Read-only mode is off by default. For agent work, turn it on with --readOnly, connect as a database user that holds only the read role on the database the job needs, keep the connection string in an environment variable rather than a prompt, and disable whole tool groups you do not need. MongoDB also runs a hosted version for Atlas, at https://mcp.mongodb.com, with OAuth sign-in and a read mode set for the whole organization.

The general case for any database behind MCP, from replicas to row limits, is in database MCP servers. This piece is about MongoDB’s server in particular.

Two ways to run it

MongoDB’s MCP server overview↗ (opens in a new tab) describes two deployment types:

• Local MCP: you run mongodb-mcp-server yourself, usually started by your client over stdio with npx, or in Docker. It works with any MongoDB deployment, including Atlas, Atlas Local, Community Edition and Enterprise Advanced, and it can limit access down to a single collection through the database user you give it.
• MongoDB Atlas Managed MCP Server: MongoDB hosts it at https://mcp.mongodb.com, for Atlas clusters only. There is no connection string or secret on your machine. Access is controlled up to project level, and an administrator decides whether AI clients may write.

Choose the local server for self-managed databases, or when you want the narrowest possible database user. Choose the managed server when you are on Atlas and would rather not hold credentials at all. Which is safer in general is weighed in local vs remote MCP servers.

What the tools cover

• Database tools: find, aggregate, count, collection-schema, collection-indexes, explain, db-stats and mongodb-logs read. insert-many, update-many, delete-many, create-index, rename-collection, drop-collection and drop-database write.
• Atlas tools: list organizations, projects, clusters and database users; inspect access lists; read triggered alerts; and atlas-get-performance-advisor for suggested indexes and a sample of recent slow queries. They also create clusters, database users and access-list entries, and pause or upgrade clusters.
• Atlas Local tools create and delete local Atlas deployments in Docker, and MongoDB Assistant tools search MongoDB’s own knowledge base.

The Atlas tools appear only when Atlas credentials are configured. That split matters, because the two kinds of credential do very different things.

Connection strings vs Atlas API credentials

A connection string, set in MDB_MCP_CONNECTION_STRING, logs in to one deployment as one database user and drives the database tools. Atlas API credentials, a service account’s client ID and secret in MDB_MCP_API_CLIENT_ID and MDB_MCP_API_CLIENT_SECRET, reach the Atlas Administration API and drive the Atlas tools. The mongodb-mcp-server README↗ (opens in a new tab) asks you to give the service account only the roles the job needs: Project Read Only to view clusters and databases, Org Read Only to list organizations and projects, and project-level roles rather than organization-wide ones. It warns that Organization Owner is rarely necessary.

One path mixes the two. With Atlas credentials and no connection string, atlas-connect-cluster creates a temporary database user with a random password, which by default expires after four hours. MongoDB’s tools reference↗ (opens in a new tab) says that user gets readAnyDatabase in read-only mode and readWriteAnyDatabase otherwise, and that the credentials stay in memory and never reach the model. Convenient, but readAnyDatabase still reads every database on the cluster. When the agent should see one database, supply your own connection string for a narrower user instead.

Read-only mode and disabling tools

--readOnly, or MDB_MCP_READ_ONLY=true, keeps only tools whose operation type is read, connect or metadata; create, update and delete tools are not registered at all, so the model never sees them. MongoDB’s security best practices↗ (opens in a new tab) pair it with a read-only database user and say never to use write credentials with the MCP server. The flag stops the model asking; the user’s role stops the database obeying. Use both.

--disabledTools goes further. It takes tool names, operation types (create, update, delete, read, metadata, connect) or the categories atlas and mongodb. Disabling connect removes the tools that connect to or switch between deployments, so the agent can reach only the one connection you configured. A few more settings are worth knowing:

• maxDocumentsPerQuery caps find and aggregate results at 100 documents by default, and maxBytesPerQuery caps their size. maxTimeMS sets a server-side time limit on reads; it is not set by default.
• indexCheck rejects queries that would scan a whole collection.
• disableServerSideJs is on by default, blocking operators such as $where and $function.
• confirmationRequiredTools asks you before drop-database, drop-collection, delete-many, drop-index and a few Atlas tools, and aggregate always asks before a pipeline with $out or $merge. The README notes that a client without MCP elicitation support runs those tools without asking, so do not rely on it alone.

A least-privilege database user

Create one user per agent or job with the built-in read role on the one database it needs. On a self-managed deployment, in mongosh:

use admin
db.createUser({
  user: "mcp_reader",
  pwd: passwordPrompt(),
  roles: [ { role: "read", db: "sales" } ]
})

On Atlas, add the database user through Atlas itself, in the UI, the Atlas CLI or the Admin API, with read access to that one database; Atlas can also make it a temporary user that expires. For finer limits, a custom role can grant find on specific collections only. Never reuse the application’s own login, which can write.

Never paste a connection string into a prompt

A connection string usually carries a username and password. Pasted into a chat, it sits in the transcript, in the conversation sent to the model provider and in anything the session exports, and the connect tool accepts it as an argument. Put it in the server’s environment instead, and give the environment the same care: MongoDB notes that its own log files may contain connection strings, so the log folder should be readable by you alone. The README also prefers environment variables to command-line arguments, which show up in process lists. The setups below read the value from your environment or a secure prompt, so no file you commit holds it.

Setup in Claude Code

For the hosted Atlas server, install MongoDB’s plugin from a Claude Code session with /plugin install mongodb-atlas@claude-plugins-official, run /reload-plugins, then authenticate it from /mcp. An Atlas Organization Owner has to enable AI client access first, unless the organization was created along with a new Atlas account, where it starts on. For the local server, set the connection string in your shell and add a project .mcp.json; Claude Code expands ${VAR} references in it:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server@latest", "--readOnly", "--disabledTools", "atlas", "connect"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "${MDB_MCP_CONNECTION_STRING}"
      }
    }
  }
}

MongoDB’s interactive npx mongodb-mcp-server@latest setup writes a configuration for you and asks about read-only mode first; answer yes. The local server needs Node.js 22 or later, or Docker.

Setup in Cursor

For Atlas, add MongoDB Atlas from the marketplace under Cursor Settings and authenticate it under Tools & MCPs. For the local server, .cursor/mcp.json takes the same entry, with Cursor’s own ${env:NAME} syntax for the variable:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "${env:MDB_MCP_CONNECTION_STRING}"
      }
    }
  }
}

Setup in VS Code

VS Code can ask for the connection string once and store it securely, using an input with password set, so it never appears in .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "mdb-connection-string",
      "description": "MongoDB connection string",
      "password": true
    }
  ],
  "servers": {
    "mongodb": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server@latest", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "${input:mdb-connection-string}"
      }
    }
  }
}

The rest of that file’s format is in the VS Code mcp.json guide.

Read mode on the hosted Atlas server

On the hosted server, read-only is set by an administrator rather than a flag. When people connect their own AI clients through Atlas App Connections, an Organization Owner chooses Read, Read and write, or Disabled for the whole organization, and the client’s access is the narrower of that mode and the user’s own Atlas role. According to MongoDB’s page on managing AI client access↗ (opens in a new tab), tools outside the mode are not registered, and by default access ends after 7 days without use or 30 days after it was granted. It cannot be limited to certain projects or clients. For automated agents, an owner creates an MCP configuration instead: a pair of service accounts with the roles the owner picks, an optional IP access list, and a read-only setting that Atlas preselects.

From a slow query to a task

Read-only is enough for the most useful MongoDB job an agent does: finding what to fix. atlas-get-performance-advisor returns suggested indexes and recent slow queries, and explain shows why a query is slow. Each finding is work someone has to schedule. With fenbs connected as a second MCP server at https://fenbs.ai/api/mcp, the agent can search the board, then file each one as an enhancement or a bug with a priority from 1 to 10, a note naming the collection and the query shape, and a plan with the index to add. The index itself goes in through your normal migration and review, not through the agent’s read-only session. On fenbs the connection signs in with OAuth, carries the read, write and comment scopes you allow, and cannot exceed your role on the board, and History shows each task under the assistant’s name. fenbs does not connect to MongoDB; the agent carries the finding across.