---
title: MongoDB connector
description: Use the MongoDB connector to query and write to MongoDB collections using find, aggregate, count, listCollections, insertOne, updateOne, and deleteOne.
url: https://docs-v3-preview.elastic.dev/elastic/kibana/pull/279607/reference/connectors-kibana/mongodb-action-type
products:
  - Kibana
applies_to:
  - Elastic Cloud Serverless: Preview
  - Elastic Stack: Planned
---

# MongoDB connector
The MongoDB connector provides access to MongoDB collections using the native MongoDB driver. Use it to query documents, run aggregation pipelines, discover collection structure, and insert, update, or delete documents from workflows. AI agents can only use the read-only actions (find, aggregate, count, listCollections) — write actions (insertOne, updateOne, deleteOne) are workflow-only and never exposed to agents. It supports any MongoDB deployment reachable through a connection URI, using either the `mongodb://` or `mongodb+srv://` (DNS seedlist) scheme: replica sets, sharded clusters, and standalone instances.

## Create connectors in Kibana

You can create connectors in **Stack Management > Connectors**.

### Connector configuration

MongoDB connectors have the following configuration properties:
<definitions>
  <definition term="Connection URI">
    The MongoDB connection URI, without credentials. Supports `mongodb://` and `mongodb+srv://` schemes. Include the database name in the path (for example, `mongodb://hostname:27017/mydb`) to use it as the default for actions that omit a `database` input. Credentials are authenticated against the `admin` database by default; append `?authSource=yourDbName` to the URI to override.
  </definition>
  <definition term="Username">
    The username for MongoDB Basic authentication.
  </definition>
  <definition term="Password">
    The password for MongoDB Basic authentication.
  </definition>
</definitions>


### Test connectors

You can test connectors when you create or edit the connector in Kibana. The test verifies connectivity by pinging the MongoDB deployment.

## Connector actions

<definitions>
  <definition term="List collections">
    List all collections in a database. Returns collection names and types. Use this first to discover what data is available before calling find, aggregate, or count.
    - `database` (optional): Database to list collections from. Defaults to the database in the connection URI path if omitted.
    - `nameFilter` (optional): Substring to filter collection names (case-sensitive). Omit to return all collections.
  </definition>
  <definition term="Find">
    Query documents in a MongoDB collection. Supports filter, projection, sort, limit, and skip. Returns an array of matching documents. Maximum 1000 documents per call. Code-execution operators (`$where`, `$expr` containing `$function`/`$accumulator`) are rejected in both the filter and the projection.
    - `collection` (required): Name of the collection to query. Use *List collections* first to discover available names.
    - `database` (optional): Database to query. Defaults to the database in the connection URI path if omitted.
    - `filter` (optional): MongoDB query filter (MQL). Omit or pass `{}` to return all documents. Examples: `{"status": "active"}`, `{"age": {"$gt": 30}}`.
    - `projection` (optional): Fields to include (`1`) or exclude (`0`). Example: `{"name": 1, "email": 1, "_id": 0}`. Omit to return all fields.
    - `sort` (optional): Sort order. `1` = ascending, `-1` = descending. Example: `{"createdAt": -1}` returns newest first.
    - `limit` (optional): Maximum number of documents to return (1–1000). Defaults to 100.
    - `skip` (optional): Number of documents to skip before returning results. Use with `limit` for pagination.
  </definition>
  <definition term="Aggregate">
    Run a MongoDB aggregation pipeline on a collection. Supports all read-only pipeline stages (`$match`, `$group`, `$sort`, `$project`, `$lookup`, `$unwind`, `$limit`, `$skip`, `$count`, and others). Write stages (`$out`, `$merge`) and code-execution operators (`$where`, `$function`, `$accumulator`) are rejected anywhere in the pipeline, including nested inside stage expressions (for example, `$project` or `$group`) and sub-pipelines (`$facet`, `$lookup`, `$unionWith`). A `$limit` stage is appended automatically unless the pipeline already ends with one, including separately inside every `$facet` branch and every `$lookup`/`$unionWith` sub-pipeline, so none of them can be used to return more than the limit's worth of documents.
    - `collection` (required): Name of the collection to aggregate.
    - `database` (optional): Database to query. Defaults to the database in the connection URI path if omitted.
    - `pipeline` (required): MongoDB aggregation pipeline — an ordered array of stage objects (maximum 100 stages, maximum 100 fields per stage). Example: `[{"$match": {"status": "active"}}, {"$group": {"_id": "$region", "count": {"$sum": 1}}}]`.
    - `limit` (optional): Maximum number of documents to return, per `$facet` branch or `$lookup`/`$unionWith` sub-pipeline if present (1–1000). Defaults to 100.
  </definition>
  <definition term="Count">
    Count documents in a MongoDB collection matching an optional filter. Returns the total document count. Use this to understand data volume before running a find or aggregate. Code-execution operators (`$where`, `$expr` containing `$function`/`$accumulator`) are rejected in the filter.
    - `collection` (required): Name of the collection to count documents in.
    - `database` (optional): Database to query. Defaults to the database in the connection URI path if omitted.
    - `filter` (optional): MongoDB query filter. Omit or pass `{}` to count all documents. Example: `{"status": "active"}`.
  </definition>
</definitions>

<tip>
  Follow the discovery pattern before querying: *List collections* → *Find* with a small limit to inspect document shape → *Count* to understand data volume → *Aggregate* to group or transform data.
</tip>

The following actions are workflow-only — they are never exposed to AI agents:
<definitions>
  <definition term="Insert one">
    Insert a single document into a MongoDB collection. Use this to create a new record from a workflow, such as logging an event or saving a processed result. Returns the inserted document ID and whether the write was acknowledged.
    - `collection` (required): Name of the collection to insert into.
    - `database` (optional): Database to write to. Defaults to the database in the connection URI path if omitted.
    - `document` (required): Document to insert. Don't include `_id` unless you want to set it explicitly. Example: `{"name": "Alice", "status": "active"}`.
  </definition>
  <definition term="Update one">
    Update the first document matching a filter in a MongoDB collection. Use this to modify an existing record from a workflow, such as changing a status field or applying a partial update. Returns matched and modified counts, the upserted document ID (if any), and whether the write was acknowledged.
    - `collection` (required): Name of the collection to update.
    - `database` (optional): Database to write to. Defaults to the database in the connection URI path if omitted.
    - `filter` (required): Filter to match the document to update. Example: `{"_id": "abc"}`.
    - `update` (required): Update operators or replacement document. Example: `{"$set": {"status": "inactive"}}`.
    - `upsert` (optional): If `true`, insert a new document when no document matches the filter.
  </definition>
  <definition term="Delete one">
    Delete the first document matching a filter from a MongoDB collection. Use this to remove a single record from a workflow, such as cleaning up a processed item. Returns the number of documents deleted and whether the write was acknowledged.
    - `collection` (required): Name of the collection to delete from.
    - `database` (optional): Database to write to. Defaults to the database in the connection URI path if omitted.
    - `filter` (required): Filter to match the document to delete. Example: `{"_id": "abc"}`.
  </definition>
</definitions>


## Connector networking configuration

The MongoDB connector talks to MongoDB over its native wire protocol, not HTTP. Even so, every host is checked against [`xpack.actions.allowedHosts`](/elastic/kibana/pull/279607/reference/configuration-reference/alerting-settings#action-settings) before connecting, the same allowlist enforced for HTTP-based connectors. For a `mongodb://` URI, that means every host listed (including every host in a multi-host replica-set or sharded-cluster URI). For a `mongodb+srv://` URI, the connector resolves the DNS SRV records itself, checks every resolved target host, and connects directly to those validated hosts rather than the DNS seed name — the MongoDB driver never performs a second, unvalidated SRV lookup of its own. After the initial connection, the MongoDB driver performs replica-set topology discovery (SDAM): it reads the member list from each server's `hello` response and may open connections to additional members advertised there. Those discovered hosts are not re-checked against `allowedHosts`, so the allowlist implicitly trusts that allowlisted MongoDB endpoints do not advertise internal hostnames. On standalone instances, you can prevent topology discovery entirely by appending `?directConnection=true` to the connection URI.
[`xpack.actions.ssl`](/elastic/kibana/pull/279607/reference/configuration-reference/alerting-settings#action-settings) and any per-host override in `xpack.actions.customHostSettings` are applied to MongoDB connections the same way they're applied to HTTP-based connectors. [`xpack.actions.proxyUrl`](/elastic/kibana/pull/279607/reference/configuration-reference/alerting-settings#action-settings) is not supported for MongoDB connections — the MongoDB driver only supports a SOCKS5 proxy, not the HTTP(S) forward proxy that setting configures — so a MongoDB connector whose host isn't covered by `xpack.actions.proxyBypassHosts` fails to connect rather than silently bypassing the configured proxy.

## Get connection credentials

The MongoDB connector authenticates with a separate connection URI (host, port, and optional database path — no credentials) plus a username and password.
1. Get the connection URI for your deployment from your MongoDB provider or admin. It uses either the `mongodb://` scheme (host and port, or a comma-separated host list for a replica set or sharded cluster) or the `mongodb+srv://` scheme (a single DNS seed name, for providers that publish SRV records — for example [MongoDB Atlas](https://cloud.mongodb.com/)'s **Database → Connect → Drivers** page).
2. If the connection string includes `<username>:<password>@`, remove it — credentials go in the separate Username and Password fields, not the URI.
3. In Kibana, create a MongoDB connector, and enter the connection URI, username, and password of a database user with the access your workflows and agents need.

<note>
  The username and password are stored as encrypted secrets and never exposed in Kibana UI or logs. Agent-facing tool actions (find, aggregate, count, listCollections) are read-only; insertOne, updateOne, and deleteOne are workflow-only and are never exposed to agents.If you are using this connector primarily with agents, use a MongoDB database user with read-only permissions (for example, the built-in `read` role in MongoDB). This limits the blast radius if an agent issues unexpected queries.
</note>