> For the complete documentation index, see [llms.txt](https://docs.p0.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.p0.dev/agentic-access/agentic-gateway/mcp-server/mongodb-atlas.md).

# MongoDB Atlas MCP server

Install the MongoDB Atlas agentic integration and its MCP server so agents behind the P0 AI Gateway can request project roles in your Atlas projects.

The **MongoDB Atlas** agentic integration lets agents behind the AI Gateway, part of [P0 Runtime Access for AI](https://docs.p0.dev/readme/agentic-control-plane.md), request time-bound Atlas project roles, such as `GROUP_DATA_ACCESS_READ_ONLY`. For each grant, P0's connector creates an MCP configuration in your Atlas project with the approved roles, and stores a token for it in your secret manager. The gateway calls MongoDB's hosted [Atlas MCP server](https://www.mongodb.com/docs/mcp-server/overview/) with that token, and Atlas allows only what the roles allow. When access ends, P0 deletes the MCP configuration.

{% hint style="info" %}
The MongoDB Atlas agentic integration is in beta. Functionality and configuration may change.
{% endhint %}

Setup has four parts, in this order:

1. Install the Atlas project in P0, which deploys P0's connector in AWS or Google Cloud.
2. Create a service account in Atlas and give P0 its credentials.
3. Add the MongoDB Atlas MCP server to your gateway.
4. Write the policies that decide which agents get which roles.

## Prerequisites

* A registered [Gateway](https://docs.p0.dev/agentic-access/agentic-gateway/gateway.md) component, with the gateway deployed in your environment. The gateway must be able to reach `https://mcp.mongodb.com` and your secret manager.
* One of these, with permission to apply Terraform where it's installed. P0's connector runs there, and agents' Atlas tokens are stored there.
  * On AWS:
    * The [AWS Secrets Manager](https://docs.p0.dev/integrations/resource-integrations/aws-secrets-manager.md) integration installed on an AWS account. The connector runs there on AWS Lambda. Applying its Terraform also needs Docker and the AWS CLI, signed in to that account, to copy P0's connector image into your Amazon ECR.
    * [AWS OIDC](https://docs.p0.dev/agentic-access/credential-sources/aws-oidc.md) installed for that same account. The gateway uses it to read each grant's token.
  * On Google Cloud:
    * The [Google Cloud](https://docs.p0.dev/integrations/resource-integrations/google-cloud.md) integration installed for your Google Cloud organization.
    * The [Google Secret Manager](https://docs.p0.dev/integrations/resource-integrations/google-secret-manager.md) integration installed on the Google Cloud project where the connector will run. The connector runs there on Cloud Run.
    * [GCP Workload Identity Federation](https://docs.p0.dev/agentic-access/credential-sources/gcp-wif.md) installed for that same project. The gateway uses it to read each grant's token.
* An Atlas user with the Project Owner role in the project, who can create service accounts.

## Install the project in P0

1. Navigate to **Integrations** on [p0.app](https://p0.app), select **MongoDB Atlas**, and choose the **Credential provisioning** component.
2. Click **Add Project**, and enter an identifier for it, such as `acme-prod`. Agents and policies use this name for the project. Use letters, digits, and hyphens.
3. Fill in the project details, then click **Next**:
   * **Atlas project ID**: the 24-character project ID, from **Project Settings** in Atlas.
   * **Secret manager provider**: choose where the connector will run:
     * **AWS Secrets Manager**: choose the installation for the AWS account, and enter the region that stores the secrets.
     * **Google Secret Manager**: choose the installation for the project.
4. P0 generates a Terraform configuration. Copy it into your Terraform project, `apply` it, then click **Next**.

   On AWS, the configuration creates:

   * An Amazon ECR repository with a copy of P0's connector image, and a Lambda function, `p0-connector-mongodb-atlas-ai-aws`, that runs it with its own IAM role.
   * A secret for the service account's client secret, `p0/install/mongodb-atlas/<identifier>/client-secret`, which only the connector can read.
   * Permission for the connector to create and manage the secrets that hold grant tokens. Their names start with `p0/access-token/mongodb-atlas/<identifier>/`, and the connector can touch no other secret.
   * A policy on P0's IAM role in the account that lets P0 invoke the function.

   On Google Cloud, it creates:

   * A Cloud Run service, `p0-connector-mongodb-atlas-ai`, that runs P0's connector under its own service account, `p0-mongodb-atlas`.
   * A secret for the service account's client secret, `p0_install_mongodb-atlas_<identifier>_client-secret`, which only the connector can read.
   * Permission for the connector to create and manage the secrets that hold grant tokens. Their names start with `p0_access-token_mongodb-atlas_<identifier>_`, and the connector can touch no other secret.
   * Bindings that let P0's Google Cloud service account call the connector and read its URL. The connector accepts calls from that service account only.
   * The Cloud Run, Secret Manager, IAM, and Resource Manager APIs, turned on in the project.

   When you click **Next**, P0 checks that the connector is deployed. A new connector can take a minute to start. If the check fails, wait a minute and click **Next** again.

{% hint style="warning" %}
Install each Atlas project in its own AWS account or Google Cloud project. The Terraform for a second Atlas project in the same account or project conflicts with the first.
{% endhint %}

## Set up Atlas

1. **Create a service account** for P0 in the Atlas project, under **Access Manager** > **Applications** > **Service Accounts**, with the **Project Owner** role. P0 uses it to create and delete an MCP configuration for each grant. See [Service Accounts Overview](https://www.mongodb.com/docs/atlas/api/service-accounts-overview/).
2. **Allow the connector to reach the Atlas Administration API.** If your organization requires an IP access list for the Administration API, add the connector's egress addresses to the service account's access list.
3. **Store the client secret.** Set `ATLAS_CLIENT_SECRET` to the service account's client secret, and run the command P0 shows. On AWS:

   ```bash
   printf '%s' "$ATLAS_CLIENT_SECRET" | aws secretsmanager put-secret-value \
     --secret-id p0/install/mongodb-atlas/<identifier>/client-secret \
     --region <secrets-region> --secret-string file:///dev/stdin
   ```

   On Google Cloud:

   ```bash
   printf '%s' "$ATLAS_CLIENT_SECRET" | gcloud secrets versions add \
     p0_install_mongodb-atlas_<identifier>_client-secret \
     --project=<project-id> --data-file=-
   ```

   P0 never sees the client secret: only your connector reads it. The connector can't grant access until the secret holds it.
4. **Enter the Client ID** of the service account in P0. It starts with `mdb_sa_id_`.
5. Review the summary and click **Finish**. The project now appears with the state **Installed**.

P0's MCP configurations appear in the Atlas project, named `p0-` followed by a hash of the grant. Don't edit or delete them: P0 creates, changes, and deletes them as grants start, change, and end.

## Add the MongoDB Atlas MCP server

You can add the MongoDB Atlas MCP server once at least one project is installed.

1. Follow the shared steps in [MCP server](https://docs.p0.dev/agentic-access/agentic-gateway/mcp-server.md#add-an-mcp-server) to name the server and choose its gateway. On the configuration screen, set the following fields, then click **Finish**:
   * **Credential source**: choose **Vaulted credential**.
   * **Definition**: choose **P0**, then select **MongoDB Atlas**.
2. The server now appears with the state **Installed**.

One MongoDB Atlas MCP server serves every project you install. Each grant names the project it is for.

## How agents request access

An agent requests access with the server's `access` tool. It names the project by its P0 identifier, and one or more Atlas project roles. For example:

* `GROUP_DATA_ACCESS_READ_ONLY`: read data in the project's clusters.
* `GROUP_DATA_ACCESS_READ_WRITE`: read and write data in the project's clusters.
* `GROUP_READ_ONLY`: view the project's settings, clusters, and users.

The agent's `list` tool shows the installed projects and the 11 project roles that an agent can request. See [Atlas User Roles](https://www.mongodb.com/docs/atlas/reference/user-roles/) for what each role allows.

Access usually works within 5 seconds of approval. Agents see every Atlas tool whether or not their roles cover it. Atlas refuses a call that the roles don't allow: with `GROUP_DATA_ACCESS_READ_ONLY`, `find` works and `insert-many` fails.

To work with data, an agent calls `remote-atlas-connect` with the Atlas project ID and a cluster name, then passes the connection ID it returns to the data tools.

A new grant on the same project adds its roles to the agent's MCP configuration. When access ends, P0 deletes the MCP configuration, and Atlas stops accepting its token at once.

{% hint style="warning" %}
An Atlas token lasts 1 hour. A grant longer than that stops working after an hour, until the agent requests access again. Keep grants to 1 hour or less.
{% endhint %}

{% hint style="warning" %}
Roles such as `GROUP_OWNER` and `GROUP_DATABASE_ACCESS_ADMIN` let an agent create database users and other credentials in the project. Those credentials outlive the grant. Grant them only to agents you trust with that.
{% endhint %}

See [Requesting access](https://docs.p0.dev/agentic-access/using-the-gateway/requesting-access.md) for how agents submit and use requests.

## Supported tools

These are the tools of the Atlas MCP server that agents see. A data tool needs a data access role. An Atlas tool that changes the project, such as `atlas-create-db-user`, needs a role that allows that change in Atlas.

### Read tools

| Tool                            | What it does                                                                   |
| ------------------------------- | ------------------------------------------------------------------------------ |
| `remote-atlas-connect`          | Connects to a cluster, and returns the connection ID that the data tools take. |
| `list-databases`                | Lists the databases of a cluster.                                              |
| `list-collections`              | Lists the collections of a database.                                           |
| `find`                          | Runs a find query against a collection.                                        |
| `aggregate`                     | Runs an aggregation against a collection.                                      |
| `aggregate-db`                  | Runs an aggregation against a database.                                        |
| `count`                         | Counts the documents in a collection.                                          |
| `collection-schema`             | Describes the schema of a collection.                                          |
| `collection-indexes`            | Describes the indexes of a collection.                                         |
| `collection-storage-size`       | Gets the size of a collection.                                                 |
| `db-stats`                      | Gets statistics for a database.                                                |
| `explain`                       | Explains the plan of a query.                                                  |
| `atlas-list-orgs`               | Lists Atlas organizations.                                                     |
| `atlas-list-projects`           | Lists Atlas projects.                                                          |
| `atlas-list-clusters`           | Lists clusters.                                                                |
| `atlas-inspect-cluster`         | Gets a cluster's details.                                                      |
| `atlas-inspect-access-list`     | Lists the IP addresses and CIDR ranges that can reach the project's clusters.  |
| `atlas-list-db-users`           | Lists database users.                                                          |
| `atlas-list-alerts`             | Lists triggered alerts.                                                        |
| `atlas-get-performance-advisor` | Gets performance advisor suggestions and recent slow queries.                  |
| `atlas-get-regions`             | Lists the regions of a cloud provider.                                         |
| `atlas-streams-discover`        | Lists Atlas Stream Processing resources.                                       |

### Write tools

| Tool                         | What it does                                                            |
| ---------------------------- | ----------------------------------------------------------------------- |
| `insert-many`                | Inserts documents into a collection.                                    |
| `update-many`                | Updates the documents that match a filter.                              |
| `delete-many`                | Deletes the documents that match a filter.                              |
| `create-collection`          | Creates a collection.                                                   |
| `rename-collection`          | Renames a collection.                                                   |
| `drop-collection`            | Drops a collection.                                                     |
| `drop-database`              | Drops a database.                                                       |
| `create-index`               | Creates an index.                                                       |
| `drop-index`                 | Drops an index.                                                         |
| `atlas-create-project`       | Creates an Atlas project.                                               |
| `atlas-create-cluster`       | Creates a dedicated cluster.                                            |
| `atlas-create-free-cluster`  | Creates a free cluster.                                                 |
| `atlas-upgrade-cluster`      | Upgrades or scales a cluster.                                           |
| `atlas-pause-resume-cluster` | Pauses or resumes a dedicated cluster.                                  |
| `atlas-create-access-list`   | Adds IP addresses or CIDR ranges that can reach the project's clusters. |
| `atlas-create-db-user`       | Creates a database user.                                                |
| `atlas-load-sample-dataset`  | Loads a sample dataset into a cluster.                                  |
| `atlas-streams-build`        | Creates Atlas Stream Processing resources.                              |
| `atlas-streams-manage`       | Starts, stops, and changes Atlas Stream Processing resources.           |
| `atlas-streams-teardown`     | Deletes Atlas Stream Processing resources.                              |

## Write policies for MongoDB Atlas

Match MongoDB Atlas requests in an agentic access policy ([Agentic access policies](https://docs.p0.dev/agentic-access/agentic-access-policies.md)) with `service: mongodb-atlas-ai` and `accessType: permission`. Two filters narrow them:

* `project`: the project, keyed on `name`, the identifier you gave the project in P0.
* `policy`: the role, keyed on `name`. A rule covers a request only if it matches every role in it.

Patterns are regular expressions, so a rule can match one role (`^GROUP_DATA_ACCESS_READ_ONLY$`), or every data access role (`^GROUP_DATA_ACCESS_.*$`).

For example, auto-approve read access to data for one agent, but only in the `acme-prod` project:

```yaml
- requestor:
    type: agentic
    actor:
      type: agent-client
      clientId: reporting-agent
    subject:
      type: any
  resource:
    type: integration
    service: mongodb-atlas-ai
    accessType: permission
    filters:
      project:
        effect: keep
        key: name
        pattern: ^acme-prod$
      policy:
        effect: keep
        key: name
        pattern: ^GROUP_DATA_ACCESS_READ_ONLY$
  approval:
    - type: persistent
      maxDuration: { time: 1, unit: h }
```

The `maxDuration` keeps auto-approved grants within the 1-hour token lifetime.
