将 Devin 连接到 MongoDB

Devin 可以像持有只读连接字符串的工程师一样处理你的 MongoDB 数据：查看集合中的实际内容，分析 query 变慢的原因，在沙盒数据库中预演迁移，并提交拉取请求 (PR) 。本指南使用你专门为 Devin 创建的身份进行配置，确保 Devin 永远不会以你团队中任何一位工程师的身份运行。

所有内容都保留在你的 Atlas 账户中：一个数据库用户、一个服务账号、通过环境蓝图安装的 MongoDB 工具，以及可选的 MCP 服务器。建议先从最小权限起步 (生产环境只读) ，之后再逐步放宽 Roles 权限。Roles 即权限边界，你可以直接在 Atlas 中调整，无需改动 Devin 的任何配置。

两个平面，两种身份

平面	可访问的内容	Devin 的身份	凭据
数据平面	数据库、文档、索引、`explain()`	数据库用户	连接字符串中的用户名和密码
控制平面	集群、Search 索引、Performance Advisor、慢 query 日志、数据库用户、访问列表	Atlas 服务账号	OAuth 2.0 client ID 和客户端密钥

数据库用户无法调用 Atlas Administration API，服务账号也无法通过 API 读取文档。大多数团队一开始只使用数据平面，等到 Devin 需要 Performance Advisor 或慢 query 日志 (仅限 M10 及以上的专用集群) 时再添加服务账号。有两点需要注意：

能够创建数据库用户的服务账号 (GROUP_OWNER、GROUP_DATABASE_ACCESS_ADMIN) 可以为自己生成一个数据平面身份。MongoDB MCP 服务器在收到连接集群的请求时就会这样做 (选项 B) 。
慢 query 数据中包含 query 的实际字面值。

选择 Devin 的连接方式

三种方式使用相同的网络访问 (步骤 1) 和身份 (步骤 2) ，区别在于 Devin 能持有哪些凭据和权限。

方式	适用场景	设置
选项 A：在蓝图中使用 CLI	Devin 在代码仓库中运行并反复执行的工作：迁移、回填、填充种子数据，以及基于真实结构数据的测试	四个 Devin Secrets 和一份简短的蓝图。建议从这里开始。
选项 B：MongoDB MCP 服务器	以工具形式提供 schema 自动发现和 query/索引分析，并通过 `--readOnly` 和 `--indexCheck` 设置护栏	一个使用相同凭据的自定义 STDIO MCP 服务器，可在选项 A 的基础上叠加使用。
选项 C：MongoDB Atlas plugin	解答 Atlas 相关问题、执行项目范围的读取，且无需在会话中存储 MongoDB 凭据	从 MCP Marketplace 安装 plugin，以专用 Atlas 用户身份通过 OAuth 登录，并将组织访问模式设置为 Read。

为什么要将 Devin 连接到 MongoDB？

schema 就藏在文档里。 MongoDB 没有 information_schema，而 Mongoose 或 Prisma 模型也会与实际存储的数据逐渐脱节。Devin 会对线上集合进行采样，依据真实的数据结构开展工作。
一个会话即可完成慢 query 的完整闭环。 Devin 会读取 Performance Advisor 和慢 query 日志，在真实集合上运行 explain()，定位发出该 query 的代码，然后提交包含修复和建议索引的拉取请求 (PR) 。
数据库用户的 Roles 决定了 Devin 的访问范围。 起步阶段可在生产环境中仅授予只读权限，并为写操作单独配置 devin_dev 沙盒；所有操作都会以 Devin 自己的身份记录在 Atlas 日志中。

前置条件

Atlas

一个包含集群的项目。
创建服务账号需要 Organization Owner 角色；创建数据库用户和配置访问列表需要 Project Owner 角色。

Devin

拥有编辑环境蓝图和添加 Secrets 的权限。
如果采用 MCP 方式，还需要 Manage MCP Servers 权限。

网络

已将 Devin 的 IP 添加到项目的 IP 访问列表中 (步骤 1) 。
如果你使用了 Devin 网络策略，请允许 *.mongodb.net 和 cloud.mongodb.com，以及蓝图安装软件所需的主机：pgp.mongodb.com 和 repo.mongodb.org (选项 A) ，registry.npmjs.org 和 nodejs.org (选项 B) 。驱动程序通过 27017 端口而非 443 端口连接；由于策略条目只能是主机名或 CIDR，因此无需设置端口。环境快照构建同样受该策略约束。

步骤 1：开放网络访问

Atlas 会拒绝来自项目 IP 访问列表以外 IP 的连接。请添加 IP 允许列表中列出的 IP，切勿凭记忆填写。专用租户使用各自独立的出站 IP，请与你的账户团队确认。

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

该列表中既有单个地址，也有一个 CIDR 范围：单个地址请使用 --type ipAddress，CIDR 范围请使用 --type cidrBlock。如果你的组织要求为服务账号配置 API 访问列表，请在 Atlas 中该服务账号的页面上添加相同的 IP。来自未列入名单的 IP 的调用将失败，并返回 403。

步骤 2：创建 Devin 的身份

数据库用户

对生产数据库只读，在沙盒中可读写，作用域限定于指定集群：

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

如果不指定 --scope，该用户将可以访问项目中的所有集群。如果内置 Roles 无法限定所需的访问范围，请使用自定义数据库角色。请使用密码管理器生成密码，切勿让密码留在 shell 历史记录中。请复制该用户的连接字符串；不要将集群管理员用户提供给 Devin。

服务账号 (仅当 Devin 需要访问控制平面时)

在 Atlas 中，于组织级别进入 Identity & Access > Applications。先从只读权限开始，并在轮换策略允许的范围内，将客户端 secrets 的有效期设为最短。

	Roles	原因
授予	在组织上授予 `ORG_MEMBER`；在每个项目上授予 `GROUP_READ_ONLY` 和 `GROUP_DATA_ACCESS_READ_ONLY`	只读基线环境
仅在需要时添加	`GROUP_SEARCH_INDEX_EDITOR`	Devin 需要管理 Search 索引
切勿授予	`GROUP_OWNER`、`GROUP_DATABASE_ACCESS_ADMIN`	任何一个都会让 Devin 能够自行扩大访问权限

对于选项 B，切勿授予这一行尤为关键。如果服务账号能够创建数据库用户，MCP 服务器的 atlas-connect-cluster 工具就会在整个集群上创建一个临时用户 (readAnyDatabase；若未使用 --readOnly，则为 readWriteAnyDatabase) ，从而绕过 devin-sessions 上按数据库设置的 Roles。该用户会保留 4 小时，除非 MCP 的断开连接工具提前将其删除。

步骤 3：连接 Devin

方案 A：在蓝图中使用 CLI

添加 Devin Secrets

在蓝图的 Secrets 选项卡中添加以下内容：

Secret	值
`MONGODB_URI`	`devin-sessions` 的连接字符串，例如 `mongodb+srv://devin-sessions:<password>@cluster0.abcde.mongodb.net/`。密码需进行百分号编码。
`MONGODB_ATLAS_CLIENT_ID`	服务账号的 client ID (`mdb_sa_id_...`) ，使用控制平面时需要
`MONGODB_ATLAS_CLIENT_SECRET`	服务账号的客户端密钥
`MONGODB_ATLAS_PROJECT_ID`	默认项目 ID

Secrets 按会话注入，因此轮换值后无需重建。Atlas CLI 会从这些环境变量中读取 client ID 和客户端密钥，因此无需执行 atlas auth login。首次使用时，它会将访问令牌缓存到 ~/.config/atlascli/config.toml 中；在会话内这样做没有问题，但切勿在 initialize 中创建该文件。

添加蓝图

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.

如果你的镜像不是 Ubuntu 22.04，请将 jammy 替换为对应的版本代号。 knowledge 块比安装步骤更重要：缺少它，会话就会去运行 atlas auth login (一个没人能完成的浏览器流程) ，或者向你索要一个环境中早已存在的连接字符串。

不要在 initialize 中将凭据写入磁盘。无论是 ~/.mongoshrc.js、~/.config/atlascli/config.toml，还是在 ~/.bashrc 中导出的 URI，最终都会被打包进快照，由之后的每个会话共享。

构建快照

保存蓝图，等待状态变为 Success 后，启动一个新会话。已打开的会话仍会沿用旧快照。

选项 B：MongoDB MCP 服务器

官方的 mongodb-mcp-server 以本地进程的形式在会话内运行，并使用步骤 2 中配置的身份。要启用其护栏，请将其添加为自定义 MCP 服务器 (Customize > MCPs > Add MCP > Add custom MCP，传输方式选择 STDIO) ，而不要通过 MCP Marketplace 中的 mongodb plugin 添加，因为该 plugin 的清单未提供 --readOnly 和 --indexCheck 选项。

字段	值
Command	`npx`
Arguments	`-y mongodb-mcp-server@<version> --readOnly --indexCheck`
Environment	`MDB_MCP_CONNECTION_STRING` (与 `MONGODB_URI` 的值相同) ；如需使用 Atlas 工具，还可设置 `MDB_MCP_API_CLIENT_ID` 和 `MDB_MCP_API_CLIENT_SECRET`

请将 <version> 固定为你已测试过的版本，因为 npx 会在每次会话启动时重新拉取该软件包。使用步骤 2 中的只读服务账号时，atlas-connect-cluster 会返回 401；Devin 会通过 MDB_MCP_CONNECTION_STRING 提供的 preconfigured 连接访问数据，这正是预期的方式。

--readOnly 会跳过创建、更新和删除类工具的注册，并拒绝包含 $out 或 $merge 的聚合。若不启用该选项，这些聚合会在确认提示后执行；如果 MCP 客户端不支持提示，则会未经确认直接执行。凡是连接生产环境，都应启用该选项。
--indexCheck 会拒绝执行计划为集合扫描的 query。这是一项性能护栏；如果 explain 本身执行失败，query 仍会照常运行。

该服务器要求 Node 版本为 ^20.19.0 || ^22.13.0 || >=24.0.0。请在会话中运行 node --version 进行检查；如果版本过低，或 MCP 进程可见的路径中找不到 npx，请将 Node 添加到蓝图中：

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

即使启用了 --readOnly，也请继续使用只读数据库用户。Devin 也能以同一用户身份运行 mongosh "$MONGODB_URI"，因此真正起到限制作用的是该用户的 Roles 权限。

选项 C：MongoDB Atlas plugin

MongoDB Atlas plugin 会将 Devin 连接到 MongoDB 托管的 MCP 服务器 (mcp.mongodb.com) ，并安装 MongoDB 的 Agent 技能。Devin 以登录用户的 Atlas Roles 执行操作，权限上限由该组织的 AI 客户端访问模式决定。

由 Organization Owner 启用 AI 客户端访问 (Organization Settings > App Connections) ，并将访问模式设为 Read，这样就不会注册写入工具。该设置对组织中的所有 AI 客户端生效，而不仅限于 Devin。
为 Devin 创建一个专用 Atlas 用户，授予 GROUP_READ_ONLY 和 GROUP_DATA_ACCESS_READ_ONLY Roles，且仅在允许其读取的项目中授予。GROUP_DATA_ACCESS_READ_ONLY 可读取项目中所有数据库的文档，因此其权限范围比 devin-sessions 用户更广。
安装该 plugin，并在 Customize > MCPs 中以该用户 (而非你自己) 的身份完成一次 OAuth 登录。
确认运行正常后，将该 plugin 固定到某个 commit。

流量来自 MongoDB 和 Devin 的托管基础架构，而非会话本身，因此步骤 1 中的 IP 列表和你的网络策略均不适用。访问权限会在连续 7 天无活动或自登录起满 30 天后失效 (以先到者为准) ，届时需重新登录。撤销访问权限不会删除该客户端创建的数据库用户或其他工件，请务必进行审查。

重建与版本固定

蓝图会安装构建时 apt 解析到的任意版本，而方案 B 中的 npx 会在每次会话启动时拉取 mongodb-mcp-server。确认可以正常运行后，请固定这两者的版本 (mongodb-atlas-cli=<version>、mongodb-mongosh=<version>、mongodb-mcp-server@<version>) ，之后再有计划地升级。轮换 secrets 无需重建，但更改已安装的工具则需要重建。

步骤 4：设置权限

身份验证确定 Devin 是谁；数据库 Roles 和 Atlas Roles 决定它能访问哪些内容。MCP 开关和 Knowledge 指示只是叠加在上层的便利手段，并不构成权限边界。

Profile	典型工作	数据库用户 Roles	服务账号 Roles
Explore (建议从这里开始)	为 schema 编写文档、分析慢 query、通过 PR 提议索引	生产数据库上的 `read`	`GROUP_READ_ONLY` + `GROUP_DATA_ACCESS_READ_ONLY`
Build	基于与真实结构一致的数据，编写并测试迁移、流水线和种子数据	Explore 的全部 Roles，外加 `readWrite@devin_dev`	与 Explore 相同
Operate	在指定集合上创建索引或 Atlas Search 索引	Explore 的全部 Roles，外加一个授予这些集合 `createIndex` 权限的自定义角色	Explore 的全部 Roles，外加 `GROUP_SEARCH_INDEX_EDITOR`

对于 Explore，索引建议功能只需要 GROUP_READ_ONLY (返回的 query 值会经过掩码处理) 。慢 query 列表、示例 query 值和日志下载还需要 GROUP_DATA_ACCESS_READ_ONLY；Atlas CLI 帮助中要求的 GROUP_DATA_ACCESS_READ_WRITE 则不需要。如果只授予 GROUP_READ_ONLY，MCP atlas-get-performance-advisor 工具会报告“No slow query logs found”，而不是返回 401，因此结果为空可能是角色配置问题。

代码仍然通过 pull request 交付。Devin 读取生产环境来理解问题，并在 devin_dev 中验证修复；迁移或索引则通过你的常规评审流程合入。

步骤 5：验证

启动一个新会话，并让 Devin 运行以下检查： 连通性。 确认当前用户、所拥有的 Roles，以及 (如已配置) Atlas CLI 能否成功完成身份验证：

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

边界检查。 第一次插入应失败 (专用集群上报错 not authorized on <prod-db> to execute command，M0/Flex 上报错 user is not allowed to do action [insert] on [<prod-db>.devin_probe]) ；第二次插入应成功：

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()'

检查 connectionStatus 中的 Roles 是否与你授予的 Profile 一致；仅凭连接成功说明不了什么。对于 MCP 服务器，请让 Devin 通过 MCP 工具列出数据库 (它会使用 preconfigured 连接) ，再让它插入一个文档：启用 --readOnly 时没有 insert-many 工具，且带有 $out 的聚合操作会被拒绝。

故障排查

症状	适用于	原因与修复方法
连接超时，或错误信息提到 IP 访问列表	A, B	项目 IP 访问列表中缺少 Devin 的 IP (最常见的故障原因) ，或你的网络策略在 TCP 27017 端口上阻止了 `*.mongodb.net`。
`querySrv ENOTFOUND _mongodb._tcp.<host>`	A, B	DNS 被阻止或主机名有误。请在网络策略中允许 `*.mongodb.net`。
`Authentication failed` 或 `bad auth : authentication failed`	A, B	密码错误或 `authSource` 有误。
`MongoParseError: Protocol and host list are required`	A, B	URI 中的密码包含 `@`、`/` 或 `+`，且未进行百分号编码。请对其进行编码；这并非身份验证错误。
`not authorized on <db> to execute command` 或 `user is not allowed to do action`	A, B	已登录但没有权限。如果是 Devin 写入生产环境，这属于预期行为；否则请扩大该用户的 Roles 权限。
Atlas CLI 提示 `unauthorized` 或建议运行 `atlas auth login`	A, B	服务账号 secrets 缺失、错误或已过期，或服务账号的角色不允许执行该操作 (MCP 服务器同样会将其报告为凭据无效) 。轮换 secrets 前请先检查角色。不要运行 `atlas auth login`。
Atlas CLI 在身份验证后返回 `403`	A, B	服务账号的 API 访问列表中缺少 Devin 的 IP (步骤 1) 。
Devin 运行 `atlas auth login` 或索要连接字符串	A	缺少 `knowledge` 块，或 secrets 未配置在会话所用的蓝图上。
蓝图构建在 `apt-get` 步骤失败，或 MCP 服务器无法启动	A, B	网络策略中缺少 `pgp.mongodb.com`、`repo.mongodb.org`、`registry.npmjs.org` 或 `nodejs.org`；或 Node 版本低于 20.19 (可运行 `node --version` 查看) 。
MCP 因 query 未使用索引而拒绝执行	B	这说明 `--indexCheck` 在正常工作。请通过 PR 添加索引，或使用 `mongosh` 对 `devin_dev` 运行该 query。需要排序规则 (collation) 索引的 query 始终会被拒绝，因为 MCP 的 `find` 工具不支持 collation 参数。
Atlas 工具缺失或出现了写入工具	C	AI 客户端访问已禁用，或访问模式为 Read and write，或已登录的 Atlas 用户拥有超出预期的 Roles 权限。请在 App Connections 下检查模式，并确认是谁完成了 OAuth 登录。
凭据在一个会话中有效，到下一个会话却失效	A	快照中残留了先前 `initialize` 生成的过期配置文件。请将其从蓝图中移除并重建。

限制

必须使用已存储的凭据。 Devin 的短期 OIDC 令牌目前无法用于 MongoDB：Administration API 仅接受服务账号 secrets 或 API 密钥。Atlas 工作负载身份联合可用于专用集群的数据平面，但需要在驱动层实现令牌回调，且尚未针对 Devin 的签发方进行测试。如需试用，请联系你的账户团队。 自托管 MongoDB。 数据平面相关步骤 (数据库用户、MONGODB_URI、mongosh、MCP 服务器) 同样适用，无需改动。自托管环境中没有 Atlas 服务账号或 IP 访问列表，网络访问需通过你的 VPN 或你自己的允许列表实现。

支持

Atlas 相关问题，请参阅 Atlas 安全文档和 MongoDB MCP 服务器文档。Devin 相关问题，请联系 support@cognition.ai 或你的账户团队。

开始使用

核心指南

部署并接入 Devin

与 Devin 协作

产品使用指南

集成

Admin

发布说明

将 Devin 连接到 MongoDB

两个平面，两种身份

选择 Devin 的连接方式

为什么要将 Devin 连接到 MongoDB？

前置条件

步骤 1：开放网络访问

步骤 2：创建 Devin 的身份

数据库用户

服务账号 (仅当 Devin 需要访问控制平面时)

步骤 3：连接 Devin

方案 A：在蓝图中使用 CLI

添加 Devin Secrets

添加蓝图

构建快照

选项 B：MongoDB MCP 服务器

选项 C：MongoDB Atlas plugin

重建与版本固定

步骤 4：设置权限

步骤 5：验证

故障排查

限制

支持

​两个平面，两种身份

​选择 Devin 的连接方式

​为什么要将 Devin 连接到 MongoDB？

​前置条件

​步骤 1：开放网络访问

​步骤 2：创建 Devin 的身份

​数据库用户

​服务账号 (仅当 Devin 需要访问控制平面时)

​步骤 3：连接 Devin

​方案 A：在蓝图中使用 CLI

​ 添加 Devin Secrets

​ 添加蓝图

​ 构建快照

​选项 B：MongoDB MCP 服务器

​选项 C：MongoDB Atlas plugin

​重建与版本固定

​步骤 4：设置权限

​步骤 5：验证

​故障排查

​限制

​支持

两个平面，两种身份

选择 Devin 的连接方式

为什么要将 Devin 连接到 MongoDB？

前置条件

步骤 1：开放网络访问

步骤 2：创建 Devin 的身份

数据库用户

服务账号 (仅当 Devin 需要访问控制平面时)

步骤 3：连接 Devin

方案 A：在蓝图中使用 CLI

添加 Devin Secrets

添加蓝图

构建快照

选项 B：MongoDB MCP 服务器

选项 C：MongoDB Atlas plugin

重建与版本固定

步骤 4：设置权限

步骤 5：验证

故障排查

限制

支持