MongoDB Agents

Agent templates for MongoDB Atlas that you can deploy to MongoDB Atlas Agent Engine.

Each template already includes what an Atlas agent needs beyond a prompt: credential handling, access scoping, tool orchestration, and approval flows. The templates are built on the MongoDB MCP Server and MongoDB Agent Skills. You bring a model API key, choose what the agent can access, and deploy it.

Note

Atlas Agent Engine is in Public Preview. Review the Agent Engine limitations before you deploy an agent against a production workload.

Agents

Agent	What it does	Status
MongoDB Atlas Explorer	A conversational agent for questions and everyday workflows across your Atlas environment, such as clusters, alerts, schemas, and data.	Available
MongoDB Atlas Query Insights	A workflow agent that produces a slow-query report for an Atlas cluster, based on Performance Advisor.	Available

Get started

These steps deploy Atlas Explorer. Atlas Query Insights follows the same steps from agents/atlas-query-insights. Each agent's README covers every step in detail: Atlas Explorer, Atlas Query Insights.

Prerequisites

• An Atlas account and a project that holds the data you want to explore
• The agentengine CLI, installed and authenticated
• Atlas CLI 1.58 or later
• Node.js 24 or later, and pnpm
• Docker, to run the agent locally
• An API key for your model provider

1. Clone and install

git clone https://github.com/mongodb/agents.git
cd agents/agents/atlas-explorer
cp .env.example .env
cp mcp-config.example.json mcp-config.json
pnpm install

2. Set the agent's boundaries

Create an Atlas MCP configuration for one Atlas project with the Atlas CLI. The roles you give that configuration decide what the agent can see and do. The example grants read-only access. Before you create it, add your IP addresses to the access list in mcp-config.json. Add the client ID and secret it returns to .env, along with your model API key. The example config and the Atlas CLI steps are in each agent's README: Atlas Explorer or Atlas Query Insights.

The agents use OpenAI by default. OpenAI and Anthropic Claude models are the verified providers. To switch provider, see the README for each agent in agents/.

3. Test it locally

pnpm build
agentengine dev up

Open the Playground at http://localhost:3000 and ask a question, such as "Which of my clusters have alerts?"

4. Deploy to Atlas Agent Engine

Store the same credentials as platform secrets, then build and deploy. If you use another model provider, set its API key instead of OPENAI_API_KEY.

agentengine secret set ATLAS_MCP_CLIENT_ID
agentengine secret set ATLAS_MCP_CLIENT_SECRET
agentengine secret set OPENAI_API_KEY
agentengine build
agentengine deploy

Then call the deployed agent:

agentengine invoke "List the databases in my cluster and their sizes."

To learn more, see Deploy your build and the agentengine CLI reference.

The agents

MongoDB Atlas Explorer

Atlas Explorer answers questions about your Atlas environment and helps with everyday Atlas tasks. It connects to Atlas through the MongoDB MCP Server. When it needs specialist guidance, such as query optimization or schema design, it loads the matching MongoDB Agent Skill.

Try asking:

• "What does the schema of the orders collection look like?"
• "Why is this query slow, and what index would help?"
• "How many orders have no shipping address?"

See the Atlas Explorer README for setup and configuration details.

MongoDB Atlas Query Insights

Atlas Query Insights explains which slow queries on a cluster matter most and what to look at next. It reads slow query logs and index suggestions from Performance Advisor, then reports on the highest-impact query shapes. It's read-only by design. It can recommend an index, but it can't create one. Performance Advisor requires an M10 or larger cluster.

For how the report is built, what it's based on, and how to configure it, see the Atlas Query Insights README.

Built-in guardrails

Agents that can see production data need clear limits. Both agents set those limits from the start.

• Their own Atlas identity. Each agent connects to Atlas with its own programmatic identity for one Atlas project, and you choose its roles. Atlas authorizes that identity, not the person chatting with the agent, so anyone who can reach an agent can use everything its roles allow. Give the agent only the roles that all of its users should have. The Atlas MCP Server doesn't currently support per-user sign-in (OIDC) for custom clients like these agents.
• Read-only by default. The example configurations grant read-only access. Atlas Explorer can be set up to write, with your approval for each write tool. Atlas Query Insights can't write.
• No shell access. Neither agent can run shell commands in its sandbox.
• Prompt injection can't be fully prevented. Text in your data or in chat messages can contain instructions aimed at the model. The templates limit what such text can do: the agent reads only what its roles allow, every write needs approval, and the egress policy blocks traffic to hosts that agent.yaml doesn't list. You decide what each agent can access, so review its roles and allowed hosts before you deploy it.
• Input guard. Each agent redacts pasted credentials from the user's message before the model sees it, and refuses messages that are too long to screen. It doesn't screen tool output. See Input guard.

Why MongoDB Atlas Agent Engine

Atlas Agent Engine is the managed runtime for these agents. It handles the infrastructure you would otherwise build and maintain yourself:

Capability	How the templates use it
Secrets and sandboxing	Atlas credentials and model API keys are stored as platform secrets, not in your code. Model and MCP calls run in a tool sandbox, separate from the agent.
Network egress policies	Outbound traffic is blocked by default. Each sandbox can reach only the hosts that agent.yaml allows, such as Atlas and your model provider.
Durable sessions	Agent Engine checkpoints each session. An agent can pause for your approval and resume where it left off.
Traces and monitoring	You can inspect each run's model calls, tool calls, and errors.

Agent Engine also offers a local Playground, service accounts for calling agents from other apps, agent memory, a policy engine, and more. See the Agent Engine documentation for the full list.

Example: talk to MongoDB Atlas Explorer from Slack

apps/atlas-explorer-slack-bot is an example of how to connect a deployed agent to the tools your team already uses. It is a thin Slack app for Atlas Explorer built on packages/agent-engine-chat (@repo/agent-engine-chat), the general-purpose library that connects any Agent Engine workspace to Chat SDK platforms. It calls Atlas Explorer on Agent Engine with a service account. You can ask questions in a channel or DM, approve or reject proposed writes, and post read-only reports on a schedule with Slack Workflow Builder.

To connect Atlas Query Insights or another agent to Slack (for example, for on-demand slow-query questions or scheduled Workflow Builder reports), build a small app around packages/agent-engine-chat using apps/atlas-explorer-slack-bot as a template.

This bot is an example to learn from and adapt. It isn't a managed Slack app. You host and operate it yourself. Read these limitations before you use it:

Important

The Slack bot connects to Atlas with one shared programmatic identity. It does not use each Slack user's own Atlas permissions.

• An allowlist of Slack users controls who can message the bot. The bot won't start without one.
• Anyone on the allowlist can reach everything that the shared identity can reach. Give that identity only the roles every allowlisted user should have.
• Only the user who requested a write can approve or reject it.
• When deployed, the bot needs its own host and its own MongoDB database to store thread state. Run locally, it can start a temporary database instead.

What to expect

These templates are for teams that want to run their own agents and control how they're set up.

• You set it up, and you own it. There's no setup option in the Atlas UI. You choose the agent's Atlas access and model provider, then deploy it to your own Agent Engine project with the agentengine CLI. You keep control of the code, the credentials, and where the agent runs.
• Atlas only. The agents depend on Atlas-hosted services such as the Atlas MCP Server. They don't support MongoDB Enterprise Advanced, on-premises deployments, or Atlas for Government.
• Built for Atlas Agent Engine. You can fork the code and adapt it under the Apache 2.0 license. However, the deployment steps in this repository cover only Atlas Agent Engine and the agentengine CLI.
• Each MCP configuration has an hourly capacity limit. Atlas limits how many access tokens one service account can have active. Agent Engine mints two tokens each time a new conversation starts, and a conversation that has been idle for 10 minutes starts new processes when its next message arrives. That works out to an expected 40 to 50 new or resumed conversations per hour, shared by every user of the configuration. When the limit is reached, new conversations fail until older tokens expire, about an hour later. The Slack bot caps new sessions per hour and replies with a clear message instead of failing. For details, see Access token limit and the Slack bot's session limit.
• Slack is an optional example. apps/atlas-explorer-slack-bot is a self-hosted Slack app built on packages/agent-engine-chat and Chat SDK, so you can connect other Agent Engine workspaces or adapt it to other chat platforms. See Example: talk to MongoDB Atlas Explorer from Slack.

Your data

• Traces and conversations include your data. Agent Engine stores every conversation and trace in your project. They can include database and collection names, field names, and documents the agent reads. Only people with access to your project can see them, and you are responsible for governing that data. See Inspect traces.
• Your model provider sees prompts and tool results. That includes query results the agent reads. Choose a provider that meets your data policy.

Skills for your coding agent

The repository includes skills in .agents/skills for working with Atlas Explorer and Atlas Query Insights, plus general skills for Atlas Agent Engine:

Skill	Use it to
deploy-mongodb-agents	Deploy or troubleshoot Atlas Explorer or Atlas Query Insights: create the MCP configuration, set secrets, build, deploy, and diagnose a failed deploy or new conversations that fail to start.
atlas-agent-engine	Edit the TypeScript agents in this repo (atlas-explorer, atlas-query-insights): agent.yaml, tool allowlists, approval middleware, and the agent libraries.
atlas-agent-engine-docs	Answer general questions about the agentengine CLI and platform from current documentation.
agent-engine-troubleshoot-deploy	Diagnose a failed or stuck deployment for other Agent Engine workspaces from status, deploy events, and runtime logs (for Atlas Explorer or Atlas Query Insights, use deploy-mongodb-agents).
agent-engine-feature-validations	Check Python agent framework code (LangGraph and Google ADK) against the shapes the SDK supports before you build or deploy.

Contributing

To learn about the repository layout, local development, and tests, see CONTRIBUTING.md.

Feedback

We want to hear what worked and what didn't, including setup friction and use cases you'd like covered. Open an issue.

License

Apache 2.0