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

# MongoDB integration

[Back to list of enterprise systems](https://koreai.mintlify.site/agent-platform/integrations/enterprise-systems.md)

Use the MongoDB integration to find, insert, update, replace, delete, and aggregate documents in a collection through Action Tools. The connector provides seven actions and no triggers.

| Authentication | Actions | Triggers |
| - | - | - |
| API Key | [7](#supported-actions) | None |

## Supported actions

| Action | Use it to |
| - | - |
| [Find Documents](#find-documents) | Find documents with a filter, projection, sort order, and pagination. |
| [Insert Documents](#insert-documents) | Insert one document or multiple documents. |
| [Update Documents](#update-documents) | Update documents that match a filter. |
| [Delete Documents](#delete-documents) | Delete documents that match a filter. |
| [Find and Update Documents](#find-and-update-documents) | Update matching documents and optionally return them. |
| [Find and Replace Documents](#find-and-replace-documents) | Replace matching documents with a new document. |
| [Aggregate Documents](#aggregate-documents) | Run an aggregation pipeline on a collection. |

## Triggers

MongoDB has no triggers in the current Studio integration catalog.

## Prerequisites

* A MongoDB deployment, such as MongoDB Atlas or a self-managed server, reachable from the platform runtime.
* A MongoDB database user with permissions for the databases and collections the selected actions need.
* The MongoDB host, username, password, and authentication database. For Atlas SRV connections, note whether the host uses the `mongodb+srv://` format.

## Set up the integration

**1. Prepare the MongoDB connection**

Create or select a MongoDB database user and confirm it can access the target database and collections. Note the host without a protocol, username, password, and authentication database. For an Atlas `mongodb+srv://` connection, enable **Use Atlas SRV URL** in the profile.

**2. Create the auth profile**

In **Integrations**, select **MongoDB** > **Connect**. On **Project Auth Profiles**, select **New Profile** > **Integration Profile** > **MongoDB** > **Continue**. Select **API Key**, enter the connection details, and select **Create Profile**. Enter the MongoDB password in the profile's **API Key** field.

**3. Create the action tool**

In **Tools**, select **New Tool** > **Action** > **MongoDB** > **Continue**. Select the **Action** and **Auth Profile**, configure the inputs, and choose whether to return the complete connector response or define custom output parameters. Select **Create Tool**, then [assign the tool to an agent](https://koreai.mintlify.site/agent-platform/tools/actions.md#assign-an-action-to-an-agent).

## Auth profile reference

Studio provides **API Key** authentication with **Preconfigured** usage mode. **Visible to project members** is enabled by default. Configure these fields:

| Field | Required | Description |
| - | - | - |
| **Host** | Yes | MongoDB host without a protocol, for example `cluster.example.mongodb.net` or `localhost:27017`. |
| **Username** | Yes | MongoDB database username. |
| **Default Database** | No | Default database for actions. An action can override it. |
| **Auth Source** | No | Authentication database. Defaults to `admin`. |
| **Use Atlas SRV URL** | No | In **Use a custom URL**, set this to `true` for Atlas `mongodb+srv://` clusters; otherwise use `false`. |
| **API Key** | Yes | MongoDB password. Studio displays the credential header name as `MongoDB-Password`. |

The profile also has a name and description. The **Usage Mode** is fixed to **Preconfigured**; the admin supplies credentials when setting up the profile, and end users do not authorize separately.

## Action reference

Each action has an optional `database` string. Leave it empty to use the profile's default database, or provide a database to override that default. The required `collection` field identifies the collection the action uses.

> [accordion] Find Documents
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database to query; overrides the profile default. |
> | `collection` | enum | Yes | Collection to search. |
> | `query` | object | No | MongoDB filter document, for example `{"status":"active"}`. |
> | `projection` | object | No | Fields to include or exclude, for example `{"name":1,"_id":0}`. |
> | `sort` | object | No | Sort criteria, for example `{"createdAt":-1}`. |
> | `limit` | number | No | Maximum documents to return. Defaults to `100`; values above `500` are capped at `500`. |
> | `skip` | number | No | Number of matching documents to skip. Defaults to `0`; use `nextSkip` from the previous response to request the next page. |
>
> The response includes pagination values such as `limit`, `skip`, `nextSkip`, and `hasMore`.

> [accordion] Insert Documents
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database to write to; overrides the profile default. |
> | `collection` | enum | Yes | Collection where documents are inserted. |
> | `documents` | object | Yes | One document object or an array of documents to insert. |

> [accordion] Update Documents
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database to update; overrides the profile default. |
> | `collection` | enum | Yes | Collection to update. |
> | `filter` | object | Yes | MongoDB filter selecting the documents to update. |
> | `update` | object | Yes | MongoDB update operations, for example `{"$set":{"status":"complete"}}`. |
> | `upsert` | boolean | No | Insert a document if none match the filter. Defaults to `false`. |

> [accordion] Delete Documents
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database to update; overrides the profile default. |
> | `collection` | enum | Yes | Collection to delete from. |
> | `filter` | object | Yes | MongoDB filter selecting the documents to delete. |

> [accordion] Find and Update Documents
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database to update; overrides the profile default. |
> | `collection` | enum | Yes | Collection to update. |
> | `filter` | object | Yes | MongoDB filter selecting the documents to update. |
> | `update` | object | Yes | MongoDB update operations. |
> | `upsert` | boolean | No | Insert a document if none match the filter. Defaults to `false`. |
> | `returnUpdated` | boolean | No | Return documents after applying updates. Defaults to `true`. |

> [accordion] Find and Replace Documents
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database to update; overrides the profile default. |
> | `collection` | enum | Yes | Collection to replace documents in. |
> | `filter` | object | Yes | MongoDB filter selecting the documents to replace. |
> | `replacement` | object | Yes | New document that replaces the matched document. |
> | `upsert` | boolean | No | Insert the replacement if none match the filter. Defaults to `false`. |
> | `returnDocument` | enum | No | Return `Before Update` or `After Update`. Defaults to `After Update`. |

> [accordion] Aggregate Documents
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `database` | string | No | Database to query; overrides the profile default. |
> | `collection` | enum | Yes | Collection to aggregate. |
> | `pipeline` | object | Yes | Aggregation pipeline array. `$out` and `$merge` stages are blocked. The final `$limit` is added or capped at `500`. |

## Troubleshoot common issues

| Issue | Resolution |
| - | - |
| The connection fails | Check the host, username, password in **API Key**, and **Auth Source**. Confirm the deployment is reachable from the platform runtime. |
| Atlas SRV connection fails | Enable **Use Atlas SRV URL** for `mongodb+srv://` hosts. Enter the host without the protocol. |
| A database or collection is missing | Check the profile's default database, any action-level `database` override, the collection selection, and the database user's access. |
| A query returns no documents | Verify the collection and filter object. Check `skip` and `limit` when paging through results. |
| An aggregation pipeline is rejected or returns fewer documents | `$out` and `$merge` are blocked. Aggregation results are capped at `500` documents. |

## Related articles

* [Auth profiles](https://koreai.mintlify.site/agent-platform/administration/integrations-settings.md#auth-profiles)
* [Action Tools](https://koreai.mintlify.site/agent-platform/tools/actions.md)
* [MongoDB Atlas connection strings](https://www.mongodb.com/docs/atlas/connect-your-application/)
* [MongoDB query documents](https://www.mongodb.com/docs/manual/tutorial/query-documents/)
* [MongoDB aggregation pipelines](https://www.mongodb.com/docs/manual/core/aggregation-pipeline/)


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