使用MongoDB 助手模板构建助手

可用模板

MongoDB助手存储库包括以下模板：

先决条件

在使用MongoDB 助手模板之前，您需要满足以下先决条件：

• Node.js 24 或更高版本。

• pnpm.

• Atlas CLI 1.58 或更高版本。

• agentengine CLI。要学习；了解如何安装CLI，请参阅MongoDB Atlas Agent Engine 文档中的安装和身份验证。

• 一个MongoDB Atlas项目，其中包含您希望代理探索的数据。

• 大型语言模型 (LLM)提供商的API密钥。默认下，模板使用 OpenAI。

配置凭证和访问权限

MongoDB 助手模板通过项目级MongoDB MCP 配置连接到MongoDB Atlas项目。要配置访问权限，请执行以下步骤：

1. 使用Atlas CLI在MongoDB Atlas中创建项目级 MCP 配置。

   1. 运行以下命令以创建项目级 MCP 配置。使用 --groupId 选项指定项目ID ，使用 --file 选项指定请求文件的路径。

      atlas api remoteMcpConfigurations createGroupMcpConfig --groupId <your-group-id> --file <your-request-file-path>

   2. 分配代理所需的最低权限MongoDB Atlas角色，例如 GROUP_DATA_ACCESS_READ_ONLY。

   3. 在 MCP 配置文件中，添加本地公共IP解决和MongoDB Atlas助手引擎的IP地址。 34.196.57.85 和 54.227.181.25 这两个地址是Atlas助手引擎IP地址。将 YOUR_LOCAL_PUBLIC_IP 替换为您自己的解决，并保留两个Atlas助手引擎地址，以便部署的助手可以进行连接。以下示例显示了一个示例请求文件：

      {
        "mcpConfigName": "{template-name-environment}",
        "roles": [
          "GROUP_DATA_ACCESS_READ_ONLY"
        ],
        "ipAccessList": [
          {
            "ipAddress": "YOUR_LOCAL_PUBLIC_IP"
          },
          {
            "ipAddress": "34.196.57.85"
          },
          {
            "ipAddress": "54.227.181.25"
          }
        ]
      }

2. 为 MCP 配置创建客户端密钥。密钥继承配置的角色。

   1. 运行以下命令以创建客户端密钥。使用 --groupId 选项指定项目ID，使用 --mcpConfigId 选项指定 MCP 配置的ID ，使用 --file 选项指定密钥元元数据文件的路径。

      atlas api remoteMcpConfigurations createGroupMcpSecret --groupId <your-group-id> --mcpConfigId <your-mcp-id> --file <your-metadata-file-path>

   2. 在元数据文件中，设立密钥过期时间。以下示例显示了在 8760 小时（一年）后过期的密钥元元数据文件：

      {
        "secretExpiresAfterHours": 8760
      }

   3. 立即复制并保存客户端密钥。该命令仅返回客户端密钥一次。

3. 存储客户端ID、客户端密钥 和 LLM提供商API密钥。

   1. 对于本地开发，请将它们存储在 .env文件中。对于已部署的代理，请使用 agentengine secret set 命令将其存储在Atlas Agent Engine 密钥存储中。

为每个环境（例如本地开发、暂存和生产）创建单独的 MCP 配置和密钥。请勿跨环境股票凭证。

使用该代理的每个人都共享相同的MongoDB Atlas访问权限，因为客户端密钥会继承 MCP 配置的角色。因此，仅授予代理的每个用户都需要的MongoDB Atlas角色。

有关每个模板的完整命令和配置文件，请参阅MongoDB 助手模板自述文件。要学习；了解有关在Atlas助手引擎中存储密钥的更多信息，请参阅MongoDB Atlas助手引擎文档中的预配密钥。

运行和部署模板

为代理配置凭证后，在本地运行模板进行测试，然后将其部署到MongoDB Atlas助手引擎。

agentengine dev up

agentengine deploy --auto

安全和数据

以下列表包含MongoDB 助手模板的安全和数据注意事项：

• 默认为只读。仅当您授予 MongoDB Atlas Explorer 的 MCP 配置写入角色并将 ALLOW_WRITE_OPERATIONS 环境变量设立为 true 时， MongoDB Atlas Explorer 才会写入MongoDB Atlas 。每次写入都会暂停以供人工批准。 MongoDB Atlas Query Insights 无法写入MongoDB Atlas。

• 跟踪和对话包括您的数据。 MongoDB Atlas Agent Engine 会将每个跟踪和对话存储在项目中。跟踪和对话可能包括数据库、集合和字段名称以及代理读取的文档。只有有权访问权限您的项目的人员才能看到它们。您有责任管理您的数据。要学习；了解更多信息，请参阅MongoDB Atlas助手引擎文档中的检查跟踪。

• 您的 LLM提供商会看到提示和工具结果。这包括代理读取的查询结果。选择数据处理政策符合贵组织数据政策的法学硕士提供商。

• 无Shell访问权限。代理无法在其沙箱中运行Shell命令。

• 您托管任何Slack机器人。 Slack机器人只是一个示例，而不是托管服务。您可以自行托管、保护和维护。

限制

MongoDB 助手模板具有以下限制：

• 模板需要MongoDB Atlas。不支持MongoDB Enterprise Advanced、本地部署部署或MongoDB Atlas for Government。

• 官方部署工作流程仅支持MongoDB Atlas Agent Engine。不支持自托管运行时。

• 这些代理不会追踪MongoDB Atlas环境随时间的变化。

• 每个 MCP 配置都有每小时容量限制。一个MongoDB Atlas服务帐户最多可以有 100 个活动访问权限令牌，每个令牌的有效期为一小时。使用相同 MCP 配置的每个工作区和客户端都有该限制。每次对话开始或在空闲超时后恢复时， MongoDB Atlas Agent Engine 都会创建两个令牌。该窗口中的后续消息会重复使用会话的进程，并且不创建令牌。这允许 40 每小时 50 个新的或恢复的对话。当代理达到令牌限制时，新的对话将失败，直到旧令牌过期，这需要长达一小时的时间。有关详细信息，请参阅MongoDB助手存储库中的访问权限令牌限制。

每个模板还具有此列表未涵盖的单独限制。有关最新的限制信息，请参阅MongoDB助手存储库。

了解详情

要学习；了解有关使用MongoDB 的代理的更多信息，请参阅以下资源：

• MongoDB助手存储库

• MongoDB Agent 技能

• MongoDB MCP 服务器文档

• MongoDB Atlas助手引擎文档