Build Agents with MongoDB Agent Templates

Available Templates

The MongoDB agents repository includes the following templates:

Prerequisites

Before you use the MongoDB Agent Templates, you need the following prerequisites:

• Node.js 24 or later.

• pnpm.

• Atlas CLI 1.58 or later.

• The agentengine CLI. To learn how to install the CLI, see Install and Authenticate in the MongoDB Atlas Agent Engine documentation.

• A MongoDB Atlas project that contains the data you want the agent to explore.

• An API key for your large language model (LLM) provider. By default, the templates use OpenAI.

Configure Credentials and Access

MongoDB Agent Templates connect to your MongoDB Atlas project through a project-level MongoDB MCP configuration. To configure access, use the following steps:

1. Create a project-level MCP configuration in MongoDB Atlas with the Atlas CLI.

   1. Run the following command to create a project-level MCP configuration. Use the --groupId option to specify your project ID and the --file option to specify the path to your request file.

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

   2. Assign the least-privilege MongoDB Atlas roles that the agent needs, such as GROUP_DATA_ACCESS_READ_ONLY.

   3. In the MCP configuration file, add your local public IP address and the IP addresses of MongoDB Atlas Agent Engine. The two addresses 34.196.57.85 and 54.227.181.25 are the Atlas Agent Engine IP addresses. Replace YOUR_LOCAL_PUBLIC_IP with your own address and keep both Atlas Agent Engine addresses so that deployed agents can connect. The following example shows a sample request file:

      {
        "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. Create a client secret for the MCP configuration. The secret inherits the roles of the configuration.

   1. Run the following command to create a client secret. Use the --groupId option to specify your project ID, the --mcpConfigId option to specify the ID of your MCP configuration, and the --file option to specify the path to your secret metadata file.

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

   2. In the metadata file, set the secret expiration time. The following example shows a secret metadata file that expires after 8760 hours (one year):

      {
        "secretExpiresAfterHours": 8760
      }

   3. Copy and save the client secret immediately. The command returns the client secret only once.

3. Store the client ID, client secret, and your LLM provider API key.

   1. For local development, store them in a .env file. For a deployed agent, store them in the Atlas Agent Engine secret store with the agentengine secret set command.

Create a separate MCP configuration and secret for each environment, such as local development, staging, and production. Do not share credentials across environments.

Everyone who uses the agent shares the same MongoDB Atlas access, because the client secret inherits the roles of the MCP configuration. Therefore, grant only the MongoDB Atlas roles that every user of the agent needs.

For each template's complete commands and configuration files, see the MongoDB Agent Templates README. To learn more about storing secrets in Atlas Agent Engine, see Provision Secrets in the MongoDB Atlas Agent Engine documentation.

Run and Deploy a Template

After you configure credentials for an agent, run the template locally to test it, then deploy it to MongoDB Atlas Agent Engine.

agentengine dev up

agentengine deploy --auto

Security and Data

The following list contains security and data considerations for the MongoDB Agent Templates:

• Read-only by default. MongoDB Atlas Explorer writes to MongoDB Atlas only if you grant its MCP configuration write roles and set the ALLOW_WRITE_OPERATIONS environment variable to true. Every write pauses for human approval. MongoDB Atlas Query Insights can't write to MongoDB Atlas.

• Traces and conversations include your data. MongoDB Atlas Agent Engine stores each trace and conversation in your project. Traces and conversations might include database, collection, and field names, and documents the agent reads. Only people with access to your project can see them. You are responsible for governing your data. To learn more, see Inspect Traces in the MongoDB Atlas Agent Engine documentation.

• Your LLM provider sees prompts and tool results. This includes query results the agent reads. Choose an LLM provider whose data handling policies fulfill your organization's data policy.

• No shell access. The agents can't run shell commands in their sandbox.

• You host any Slack bot. The Slack bot is an example, not a managed service. You host, secure, and maintain it yourself.

Limitations

MongoDB Agent Templates have the following limitations:

• The templates require MongoDB Atlas. They don't support MongoDB Enterprise Advanced, on-premises deployments, or MongoDB Atlas for Government.

• Official deployment workflows only support MongoDB Atlas Agent Engine. Self-hosted runtimes are not supported.

• The agents don't track changes to your MongoDB Atlas environment over time.

• Each MCP configuration has an hourly capacity limit. A MongoDB Atlas service account can have a maximum of 100 active access tokens, and each token lasts one hour. Every workspace and client that uses the same MCP configuration shares that limit. MongoDB Atlas Agent Engine creates two tokens each time a conversation starts, or resumes after the idle timeout. Follow-up messages within that window reuse the session's processes and create no tokens. This allows 40 to 50 new or resumed conversations per hour. When the agent reaches the token limit, new conversations fail until older tokens expire, which takes up to one hour. For details, see access token limits in the MongoDB agents repository.

Each template also has individual limitations that this list does not cover. For the most up-to-date limitation information, see the MongoDB agents repository.

Learn More

To learn more about agents that work with MongoDB, see the following resources:

• MongoDB Agents Repository

• MongoDB Agent Skills

• MongoDB MCP Server Documentation

• MongoDB Atlas Agent Engine Documentation