> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 将 Devin 连接到 MongoDB

> 通过限定作用域的数据库用户、Atlas 服务账号、在蓝图中安装的 mongosh 和 Atlas CLI，或 MongoDB MCP 服务器，将 Devin 连接到 MongoDB Atlas。

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

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

<h2 id="two-planes-two-identities">
  两个平面，两种身份
</h2>

| 平面 | 可访问的内容 | 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 的实际字面值。

<h2 id="choose-how-devin-connects">
  选择 Devin 的连接方式
</h2>

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

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

<h2 id="why-connect-devin-to-mongodb">
  为什么要将 Devin 连接到 MongoDB？
</h2>

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

<h2 id="prerequisites">
  前置条件
</h2>

**Atlas**

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

**Devin**

* 拥有编辑[环境蓝图](/zh/onboard-devin/environment/blueprints)和添加 [Secrets](/zh/product-guides/secrets) 的权限。
* 如果采用 MCP 方式，还需要 **Manage MCP Servers** 权限。

**网络**

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

<h2 id="step-1-open-network-access">
  步骤 1：开放网络访问
</h2>

Atlas 会拒绝来自项目 IP 访问列表以外 IP 的连接。请添加 [IP 允许列表](/zh/admin/common-issues#ip-allowlisting)中列出的 IP，切勿凭记忆填写。专用租户使用各自独立的出站 IP，请与你的账户团队确认。

```bash theme={null}
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`。

<h2 id="step-2-create-devins-identities">
  步骤 2：创建 Devin 的身份
</h2>

<h3 id="database-user">
  数据库用户
</h3>

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

```bash theme={null}
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 无法限定所需的访问范围，请使用[自定义数据库角色](https://www.mongodb.com/docs/atlas/security-add-mongodb-roles/)。请使用密码管理器生成密码，切勿让密码留在 shell 历史记录中。请复制该用户的连接字符串；不要将集群管理员用户提供给 Devin。

<h3 id="service-account-only-if-devin-needs-the-control-plane">
  服务账号 (仅当 Devin 需要访问控制平面时)
</h3>

在 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 能够自行扩大访问权限 |

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

<h2 id="step-3-connect-devin">
  步骤 3：连接 Devin
</h2>

<h3 id="option-a-cli-in-a-blueprint">
  方案 A：在蓝图中使用 CLI
</h3>

<h4 id="1-add-devin-secrets">
  1. 添加 Devin Secrets
</h4>

在蓝图的 **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` 中创建该文件。

<h4 id="2-add-the-blueprint">
  2. 添加蓝图
</h4>

```yaml theme={null}
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` (一个没人能完成的浏览器流程) ，或者向你索要一个环境中早已存在的连接字符串。

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

<h4 id="3-build-the-snapshot">
  3. 构建快照
</h4>

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

<h3 id="option-b-mongodb-mcp-server">
  选项 B：MongoDB MCP 服务器
</h3>

官方的 [`mongodb-mcp-server`](https://github.com/mongodb-js/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 添加到蓝图中：

```yaml theme={null}
initialize:
  - name: Install Node.js for the MongoDB MCP server
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "22"
```

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

<h3 id="option-c-mongodb-atlas-plugin">
  选项 C：MongoDB Atlas plugin
</h3>

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

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

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

<h3 id="rebuilds-and-version-pinning">
  重建与版本固定
</h3>

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

<h2 id="step-4-set-permissions">
  步骤 4：设置权限
</h2>

身份验证确定 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`，因此结果为空可能是角色配置问题。

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

<h2 id="step-5-verify">
  步骤 5：验证
</h2>

启动一个新会话，并让 Devin 运行以下检查：

**连通性。** 确认当前用户、所拥有的 Roles，以及 (如已配置) Atlas CLI 能否成功完成身份验证：

```bash theme={null}
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]`) ；第二次插入应成功：

```bash theme={null}
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` 的聚合操作会被拒绝。

<h2 id="troubleshooting">
  故障排查
</h2>

| 症状 | 适用于 | 原因与修复方法 |
| - | - | - |
| 连接超时，或错误信息提到 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` 生成的过期配置文件。请将其从蓝图中移除并重建。 |

<h2 id="limitations">
  限制
</h2>

**必须使用已存储的凭据。** Devin 的短期 [OIDC 令牌](/zh/product-guides/oidc)目前无法用于 MongoDB：Administration API 仅接受服务账号 secrets 或 API 密钥。Atlas [工作负载身份联合](https://www.mongodb.com/docs/atlas/workload-oidc/)可用于专用集群的数据平面，但需要在驱动层实现令牌回调，且尚未针对 Devin 的签发方进行测试。如需试用，请联系你的账户团队。

**自托管 MongoDB。** 数据平面相关步骤 (数据库用户、`MONGODB_URI`、`mongosh`、MCP 服务器) 同样适用，无需改动。自托管环境中没有 Atlas 服务账号或 IP 访问列表，网络访问需通过你的 [VPN](/zh/onboard-devin/vpn) 或你自己的允许列表实现。

<h2 id="support">
  支持
</h2>

Atlas 相关问题，请参阅 [Atlas 安全文档](https://www.mongodb.com/docs/atlas/setup-cluster-security/)和 [MongoDB MCP 服务器文档](https://www.mongodb.com/docs/mcp-server/)。Devin 相关问题，请联系 [support@cognition.ai](mailto:support@cognition.ai) 或你的账户团队。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.