Connect Codex to MongoDB

MongoDB ships its own MCP server, mongodb-mcp-server, and its onboarding is built around AI clients that read JSON. Codex reads TOML. Run the vendor’s setup wizard and it writes a config Codex can’t parse, so skip it and write the TOML block yourself.

What you get

Once it’s connected, Codex works your cluster through real database tools. For reading and understanding what’s there: find, aggregate, count, explain, list-databases, list-collections, collection-schema, collection-indexes, db-stats, and collection-storage-size. For changing it: insert-many, update-one, update-many, delete-many, create-collection, drop-collection, create-index, drop-index, rename-collection, and drop-database. There’s also export, which MongoDB’s tool reference describes as saving query or aggregation results in JSON to a file on the machine running the server, and mongodb-logs, which returns the most recent logged mongod events.

If you supply Atlas API service account credentials (optional), a second set of tools becomes available for cluster-level work: atlas-list-clusters, atlas-create-cluster, atlas-pause-resume-cluster, atlas-get-performance-advisor, and others. Skip those credentials and you still get the full data-tool set against whatever cluster your connection string points at.

Setup

Prerequisites: MongoDB’s docs list Node.js 22.12.0 or later, plus a connection string for the cluster you want Codex to reach.

The vendor’s wizard, npx mongodb-mcp-server@latest setup, is a real command and it works. It just doesn’t help you here. It asks you to pick a client from a list (Cursor, VS Code, Claude Desktop, Claude Code, Open Code, Windsurf), then writes a JSON config to that client’s config path. Codex isn’t on the list, and JSON is the wrong shape for ~/.codex/config.toml no matter where you point it. Write the block by hand:

[mcp_servers.mongodb]
command = "npx"
args = ["-y", "mongodb-mcp-server@latest"]
startup_timeout_sec = 30

[mcp_servers.mongodb.env]
MDB_MCP_CONNECTION_STRING = "mongodb+srv://atlasuser:D1fficultP%[email protected]/myDatabase?retryWrites=true&w=majority"
MDB_MCP_READ_ONLY = "true"

Steps:

1. Open (or create) ~/.codex/config.toml.
2. Add the block above and swap in your own connection string. Read the percent-encoding gotcha below first.
3. Leave MDB_MCP_READ_ONLY at "true" while you find out what Codex does with the access. MongoDB documents the default as false, which permits writes, so this line is the one doing the work. Flip it to "false" when you want Codex creating and dropping things.
4. Restart Codex, then run codex mcp list to confirm mongodb initialized.

The CLI can write the same entry. codex mcp add takes repeatable --env flags, and they go before the -- separator:

codex mcp add mongodb \
  --env MDB_MCP_CONNECTION_STRING="mongodb+srv://..." \
  --env MDB_MCP_READ_ONLY=true \
  -- npx -y mongodb-mcp-server@latest

That puts your connection string in shell history, so hand-editing the file is the quieter option. Either way, open the file afterward if you want startup_timeout_sec on the entry.

For the Atlas cluster tools, add the service account pair to the same env table: MDB_MCP_API_CLIENT_ID (format mdb_sa_id_<objectId>) and MDB_MCP_API_CLIENT_SECRET (format mdb_sa_sk_<random-string>). Leave them out if you only need the data tools; you can add them later.

Gotchas

The package is unscoped. It’s mongodb-mcp-server, not @mongodb/mongodb-mcp-server. Every command on MongoDB’s get-started page uses the bare name. This is exactly the kind of name a model will confidently get wrong, so check what actually ends up in your args line.

Percent-encode the password. MongoDB’s own example shows why: mongodb+srv://atlasuser:D1fficultP%40ssw0rd@... is the password D1fficultP@ssw0rd with the @ written as %40. Leave it raw and the driver reads that first @ as the boundary between credentials and host. Same treatment for :, /, ?, and #.

Keep the connection string out of args. MongoDB’s configuration docs recommend environment variables over command-line arguments for exactly this reason: anything in args is visible in your OS process list to any other local process. The [mcp_servers.mongodb.env] table keeps it out of there, but ~/.codex/config.toml is still plaintext on disk. Don’t commit it, and don’t screenshot it.

default_tools_approval_mode = "writes" leans on annotations. Codex documents writes as prompting only for tools that aren’t marked read-only, which puts the decision in the server’s hands. MongoDB’s tool reference doesn’t say which of its tools carry that marking, so don’t treat the approval prompt as your safety net. MDB_MCP_READ_ONLY = "true" is the guard MongoDB actually enforces.

A cold npx can blow the startup window. The first run downloads mongodb-mcp-server before it can answer the handshake, and the default startup_timeout_sec is 10. The block above sets 30. Raise it further on a slow network. More on that failure: /config/mcp-servers-startup-timeout-sec/.

Related

• /config/connect-an-mcp-server/: the stdio/HTTP shape and the JSON-to-TOML translation table
• /config/mcp-servers-env/: how the .env sub-table works and why secrets go there
• /config/mcp-servers-startup-timeout-sec/: fixing the cold-npx handshake timeout
• /guides/install-codex-cli/: installing Codex CLI itself