Connect Devin to MongoDB

Devin can work with your MongoDB data the way an engineer with a read-only connection string would: read what collections actually contain, work out why a query is slow, rehearse a migration in a sandbox database, and open a PR. This guide sets that up with identities you create for Devin, so it never runs as one of your engineers.

Everything stays in your Atlas account: a database user, a service account, MongoDB tooling installed through an environment blueprint, and optionally an MCP server. Start narrow (read-only production) and widen roles later; the roles are the boundary, and you change them in Atlas without touching Devin.

Two planes, two identities

Plane	What it reaches	Devin’s identity	Credential
Data plane	Databases, documents, indexes, `explain()`	A database user	Username and password in a connection string
Control plane	Clusters, Search indexes, Performance Advisor, slow-query logs, database users, access lists	An Atlas service account	OAuth 2.0 client ID and client secret

A database user can’t call the Atlas Administration API, and a service account can’t read documents through the API. Most teams start with the data plane only and add the service account when Devin needs Performance Advisor or slow-query logs (dedicated clusters, M10 and up). Two caveats:

A service account that can create database users (GROUP_OWNER, GROUP_DATABASE_ACCESS_ADMIN) can mint itself a data-plane identity. The MongoDB MCP server does exactly that when asked to connect to a cluster (Option B).
Slow-query data includes literal query values.

Choose how Devin connects

All three paths use the same network access (Step 1) and identities (Step 2); they differ in what Devin gets to hold.

Path	Best for	Setup
Option A: CLI in a blueprint	Work Devin runs and repeats in a repo: migrations, backfills, seed data, tests against real-shaped data	Four Devin Secrets and a short blueprint. Start here.
Option B: MongoDB MCP server	Schema discovery and query/index analysis as tools, with `--readOnly` and `--indexCheck` guardrails	A custom STDIO MCP server using the same credentials. Adds to Option A.
Option C: MongoDB Atlas plugin	Atlas questions and project-wide reads, without storing a MongoDB credential in the session	Marketplace plugin, OAuth login as a dedicated Atlas user; org access mode set to Read.

Why connect Devin to MongoDB?

The schema lives in the documents. MongoDB has no information_schema, and Mongoose or Prisma models drift from what is stored. Devin samples the live collections and works from the real shape.
The slow-query loop closes in one session. Devin reads Performance Advisor and the slow-query log, runs explain() on the real collection, finds the code that issues the query, and opens a PR with the fix and the proposed index.
The database user’s roles decide what Devin can touch. Start read-only on production with a devin_dev sandbox for writes, and every action lands in Atlas logs under Devin’s own identity.

Prerequisites

Atlas

A project with a cluster.
Organization Owner to create a service account; Project Owner for the database user and access lists.

Devin

Permission to edit the environment blueprint and add Secrets.
For the MCP paths, Manage MCP Servers.

Network

Devin’s IPs on the project IP access list (Step 1).
If you use a Devin network policy, allow *.mongodb.net and cloud.mongodb.com, plus the hosts the blueprint installs from: pgp.mongodb.com and repo.mongodb.org (Option A), registry.npmjs.org and nodejs.org (Option B). The driver connects on port 27017, not 443; policy entries are hostnames or CIDRs, so there’s no port to set. Snapshot builds run under the same policy.

Step 1: Open network access

Atlas refuses connections from IPs not on the project IP access list. Add the IPs listed under IP allowlisting, not from memory. Dedicated tenants have their own egress; confirm with your account team.

atlas accessLists create <ip> --type ipAddress --comment "Devin" --projectId <project-id>
atlas accessLists create <cidr> --type cidrBlock --comment "Devin" --projectId <project-id>

The list contains both single addresses and a CIDR range; use --type ipAddress for single addresses and --type cidrBlock for the range. If your organization requires an API access list on service accounts, add the same IPs on the service account’s page in Atlas. Calls from an unlisted IP fail with 403.

Step 2: Create Devin’s identities

Database user

Read on production databases, read/write in a sandbox, scoped to named clusters:

atlas dbusers create \
  --username devin-sessions \
  --password "<generated-password>" \
  --role read@analytics,read@billing,readWrite@devin_dev \
  --scope <cluster-name> \
  --projectId <project-id>

Without --scope the user can reach every cluster in the project. Use a custom database role when built-in roles can’t express the boundary. Generate the password with a password manager and don’t leave it in shell history. Copy this user’s connection string; don’t give Devin the cluster admin user.

Service account (only if Devin needs the control plane)

In Atlas, Identity & Access > Applications at the organization level. Start read-only, and pick the shortest client-secret lifetime your rotation allows.

	Roles	Why
Grant	`ORG_MEMBER` on the organization; `GROUP_READ_ONLY` and `GROUP_DATA_ACCESS_READ_ONLY` on each project	Read-only baseline
Add only if needed	`GROUP_SEARCH_INDEX_EDITOR`	Devin manages Search indexes
Never	`GROUP_OWNER`, `GROUP_DATABASE_ACCESS_ADMIN`	Either lets Devin widen its own access

The Never row matters most with Option B. If the service account can create database users, the MCP server’s atlas-connect-cluster tool creates a temporary user on the whole cluster (readAnyDatabase, or readWriteAnyDatabase without --readOnly), bypassing the per-database roles on devin-sessions. That user lives for 4 hours unless the MCP disconnect tool deletes it first.

Step 3: Connect Devin

Option A: CLI in a blueprint

1. Add Devin Secrets

On the blueprint’s Secrets tab:

Secret	Value
`MONGODB_URI`	The `devin-sessions` connection string, e.g. `mongodb+srv://devin-sessions:<password>@cluster0.abcde.mongodb.net/`. Percent-encode the password.
`MONGODB_ATLAS_CLIENT_ID`	Service account client ID (`mdb_sa_id_...`), if using the control plane
`MONGODB_ATLAS_CLIENT_SECRET`	Service account client secret
`MONGODB_ATLAS_PROJECT_ID`	Default project ID

Secrets are injected per session, so rotating a value needs no rebuild. The Atlas CLI reads the client ID and secret from these environment variables, so there is no atlas auth login. On first use it caches an access token in ~/.config/atlascli/config.toml; that’s fine inside a session, but never create that file in initialize.

2. Add the blueprint

initialize:
  - name: Install the Atlas CLI and mongosh
    run: |
      curl -fsSL https://pgp.mongodb.com/server-8.0.asc \
        | sudo gpg --batch --yes -o /usr/share/keyrings/mongodb-server-8.0.gpg --dearmor
      echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/8.0 multiverse" \
        | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list
      sudo apt-get update
      sudo apt-get install -y mongodb-atlas-cli mongodb-mongosh
      atlas --version && mongosh --version

knowledge:
  - name: mongodb-access
    contents: |
      Connect to MongoDB with `mongosh "$MONGODB_URI"`; the URI is a Devin Secret. The Atlas CLI
      authenticates as a service account from MONGODB_ATLAS_CLIENT_ID and MONGODB_ATLAS_CLIENT_SECRET,
      with MONGODB_ATLAS_PROJECT_ID as the default project. Do not run `atlas auth login`, do not ask
      for a username, password, or API key, and never write the connection string into a file, script,
      log, or PR. Production databases are read-only; write only to the devin_dev database. Ship
      schema, index, and migration changes through a pull request.

Swap jammy if your image isn’t Ubuntu 22.04. The knowledge block matters more than the install: without it, sessions run atlas auth login (a browser flow nobody can finish) or ask for a connection string that is already in the environment.

Don’t write credentials to disk in initialize. A ~/.mongoshrc.js, ~/.config/atlascli/config.toml, or an exported URI in ~/.bashrc ends up in the snapshot, shared by every future session.

3. Build the snapshot

Save the blueprint, wait for Success, then start a new session. Open sessions keep the old snapshot.

Option B: MongoDB MCP server

The official mongodb-mcp-server runs as a local process inside the session and uses the Step 2 identities. To get its guardrails, add it as a custom MCP server (Customize > MCPs > Add MCP > Add custom MCP, transport STDIO) rather than through the marketplace mongodb plugin, whose manifest doesn’t expose --readOnly or --indexCheck.

Field	Value
Command	`npx`
Arguments	`-y mongodb-mcp-server@<version> --readOnly --indexCheck`
Environment	`MDB_MCP_CONNECTION_STRING` (same value as `MONGODB_URI`); optionally `MDB_MCP_API_CLIENT_ID` and `MDB_MCP_API_CLIENT_SECRET` for Atlas tools

Pin <version> to a release you’ve tested; npx fetches the package on every session start. With the read-only service account from Step 2, atlas-connect-cluster returns 401; Devin reaches data through the preconfigured connection from MDB_MCP_CONNECTION_STRING, which is the intended path.

--readOnly skips registering create, update, and delete tools, and rejects aggregations containing $out or $merge. Without it, those aggregations run after a confirmation prompt, or unconfirmed if the MCP client doesn’t support prompts. Use it for anything pointed at production.
--indexCheck rejects queries whose plan is a collection scan. It’s a performance guardrail; if explain itself fails, the query runs anyway.

The server requires Node ^20.19.0 || ^22.13.0 || >=24.0.0. Check node --version in a session; if it’s older, or npx isn’t on the path the MCP process sees, add Node to the blueprint:

initialize:
  - name: Install Node.js for the MongoDB MCP server
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "22"

Keep the read-only database user even with --readOnly. Devin can also run mongosh "$MONGODB_URI" with the same user, so the user’s roles are the boundary that actually holds.

Option C: MongoDB Atlas plugin

The MongoDB Atlas plugin connects Devin to MongoDB’s hosted MCP server (mcp.mongodb.com) and installs MongoDB’s agent skills. Devin acts with the Atlas roles of the user who signs in, capped by the organization’s AI client access mode.

An Organization Owner enables AI client access (Organization Settings > App Connections) and sets the access mode to Read, so write tools aren’t registered. The setting applies to every AI client in the organization, not only Devin.
Create a dedicated Atlas user for Devin with GROUP_READ_ONLY and GROUP_DATA_ACCESS_READ_ONLY, only in projects it may read. GROUP_DATA_ACCESS_READ_ONLY reads documents in every database in the project, so this is wider than the devin-sessions user.
Install the plugin and complete the OAuth login once in Customize > MCPs, signed in as that user, not as yourself.
Pin the plugin to a commit once it works.

Traffic comes from MongoDB’s and Devin’s hosted infrastructure, not the session, so Step 1’s IP lists and your network policy don’t apply. Access ends after 7 days of inactivity or 30 days from sign-in, whichever comes first; sign in again. Revoking access doesn’t delete database users or other artifacts the client created, so audit them.

Rebuilds and version pinning

The blueprint installs whatever apt resolves at build time, and Option B’s npx fetches mongodb-mcp-server on every session start. Pin both (mongodb-atlas-cli=<version>, mongodb-mongosh=<version>, mongodb-mcp-server@<version>) once they work, and bump them deliberately. Rotating a secret needs no rebuild; changing an installed tool does.

Step 4: Set permissions

Authentication says who Devin is; database and Atlas roles say what it can touch. MCP flags and knowledge instructions are conveniences on top, not the boundary.

Profile	Typical work	Database user roles	Service account roles
Explore (start here)	Document the schema, explain a slow query, propose an index in a PR	`read` on production databases	`GROUP_READ_ONLY` + `GROUP_DATA_ACCESS_READ_ONLY`
Build	Write and test migrations, pipelines, and seed data against real-shaped data	Explore, plus `readWrite@devin_dev`	Same as Explore
Operate	Create indexes or Atlas Search indexes on named collections	Explore, plus a custom role granting `createIndex` on those collections	Explore, plus `GROUP_SEARCH_INDEX_EDITOR`

For Explore, suggested indexes need only GROUP_READ_ONLY (query values come back masked). The slow-query list, sample query values, and log downloads also need GROUP_DATA_ACCESS_READ_ONLY; the GROUP_DATA_ACCESS_READ_WRITE the Atlas CLI help asks for isn’t needed. With GROUP_READ_ONLY alone, the MCP atlas-get-performance-advisor tool reports “No slow query logs found” rather than the 401, so an empty result may be a role problem.

Code still ships through pull requests. Devin reads production to understand the problem and proves the fix in devin_dev; the migration or index lands through your normal review.

Step 5: Verify

Start a new session and ask Devin to run: Connectivity. Which user, which roles, and (if configured) whether the Atlas CLI authenticates:

mongosh "$MONGODB_URI" --quiet --eval 'JSON.stringify(db.runCommand({connectionStatus: 1}), null, 2)'
atlas clusters list --projectId "$MONGODB_ATLAS_PROJECT_ID"

Boundary. The first insert should fail (not authorized on <prod-db> to execute command on dedicated clusters, user is not allowed to do action [insert] on [<prod-db>.devin_probe] on M0/Flex); the second should succeed:

mongosh "$MONGODB_URI" --quiet --eval 'db.getSiblingDB("<prod-db>").devin_probe.insertOne({probe: 1})'
mongosh "$MONGODB_URI" --quiet --eval 'db.getSiblingDB("devin_dev").devin_probe.insertOne({probe: 1}); db.getSiblingDB("devin_dev").devin_probe.drop()'

Check the roles in connectionStatus match the profile you granted; an open connection alone proves little. For the MCP server, ask Devin to list databases through the MCP tools (it uses the preconfigured connection), then to insert a document: with --readOnly there is no insert-many tool, and an aggregation with $out is refused.

Troubleshooting

Symptom	Applies to	Cause and fix
Connection times out, or the error mentions the IP access list	A, B	Devin’s IPs are missing from the project IP access list (the most common failure), or your network policy blocks `*.mongodb.net` on TCP 27017.
`querySrv ENOTFOUND _mongodb._tcp.<host>`	A, B	DNS blocked or hostname wrong. Allow `*.mongodb.net` in the network policy.
`Authentication failed` or `bad auth : authentication failed`	A, B	Wrong password or wrong `authSource`.
`MongoParseError: Protocol and host list are required`	A, B	The URI password contains `@`, `/`, or `+` and isn’t percent-encoded. Encode it; this isn’t an auth error.
`not authorized on <db> to execute command` or `user is not allowed to do action`	A, B	Signed in but not permitted. Expected when Devin writes to production; otherwise widen the user’s roles.
Atlas CLI says `unauthorized` or suggests `atlas auth login`	A, B	Service-account secrets missing, wrong, or expired, or the service account’s role doesn’t allow that action (the MCP server reports this as invalid credentials too). Check the role before rotating secrets. Don’t run `atlas auth login`.
Atlas CLI returns `403` after authenticating	A, B	The service account’s API access list is missing Devin’s IPs (Step 1).
Devin runs `atlas auth login` or asks for a connection string	A	The `knowledge` block is missing, or the secrets aren’t on the blueprint the session uses.
Blueprint build fails on `apt-get`, or the MCP server won’t start	A, B	Network policy is missing `pgp.mongodb.com`, `repo.mongodb.org`, `registry.npmjs.org`, or `nodejs.org`; or Node is older than 20.19 (run `node --version`).
MCP rejects a query for not using an index	B	`--indexCheck` is doing its job. Add the index in a PR, or run the query with `mongosh` against `devin_dev`. Queries that need a collation index are always rejected: the MCP `find` tool has no collation argument.
Atlas tools missing or write tools appear	C	AI client access is disabled, or the access mode is Read and write, or the signed-in Atlas user has broader roles than intended. Check the mode under App Connections and who completed the OAuth login.
Credentials work in one session and not the next	A	A stale config file from an earlier `initialize` is in the snapshot. Remove it from the blueprint and rebuild.

Limitations

Stored credentials are required. Devin’s short-lived OIDC token can’t be used with MongoDB today: the Administration API accepts only service-account secrets or API keys. Atlas Workload Identity Federation covers the data plane on dedicated clusters, but needs a driver-level token callback and hasn’t been tested with Devin’s issuer. If you want to try it, tell your account team. Self-hosted MongoDB. The data-plane steps (database user, MONGODB_URI, mongosh, MCP server) apply unchanged. There is no Atlas service account or IP access list; network access goes through your VPN or your own allowlist.

Support

For the Atlas side, see the Atlas security docs and MongoDB MCP Server docs. For the Devin side, contact support@cognition.ai or your account team.

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

Release Notes

Connect Devin to MongoDB

Two planes, two identities

Choose how Devin connects

Why connect Devin to MongoDB?

Prerequisites

Step 1: Open network access

Step 2: Create Devin’s identities

Database user

Service account (only if Devin needs the control plane)

Step 3: Connect Devin

Option A: CLI in a blueprint

1. Add Devin Secrets

2. Add the blueprint

3. Build the snapshot

Option B: MongoDB MCP server

Option C: MongoDB Atlas plugin

Rebuilds and version pinning

Step 4: Set permissions

Step 5: Verify

Troubleshooting

Limitations

Support

​Two planes, two identities

​Choose how Devin connects

​Why connect Devin to MongoDB?

​Prerequisites

​Step 1: Open network access

​Step 2: Create Devin’s identities

​Database user

​Service account (only if Devin needs the control plane)

​Step 3: Connect Devin

​Option A: CLI in a blueprint

​1. Add Devin Secrets

​2. Add the blueprint

​3. Build the snapshot

​Option B: MongoDB MCP server

​Option C: MongoDB Atlas plugin

​Rebuilds and version pinning

​Step 4: Set permissions

​Step 5: Verify

​Troubleshooting

​Limitations

​Support

Two planes, two identities

Choose how Devin connects

Why connect Devin to MongoDB?

Prerequisites

Step 1: Open network access

Step 2: Create Devin’s identities

Database user

Service account (only if Devin needs the control plane)

Step 3: Connect Devin

Option A: CLI in a blueprint

1. Add Devin Secrets

2. Add the blueprint

3. Build the snapshot

Option B: MongoDB MCP server

Option C: MongoDB Atlas plugin

Rebuilds and version pinning

Step 4: Set permissions

Step 5: Verify

Troubleshooting

Limitations

Support