MongoDB Atlas

​

Requirements

• An Atlas cluster. This page was tested on the free M0 tier.
• A database user with a password.
• Docker on a host with a static public IP.
• A MongoDB client, such as mongosh.

​

Setup

1

Find the primary member

An Atlas connection string starts with mongodb+srv://. Its host is a DNS record that lists the cluster members, not a server. The Sidecar connects to one member: the primary.Ask the cluster which member is primary:

mongosh "mongodb+srv://<user>:<password>@cluster0.<id>.mongodb.net/" --quiet --eval 'db.hello().primary'

ac-<prefix>-shard-00-01.<id>.mongodb.net:27017

The Atlas UI shows the same. Open the cluster, then the Metrics tab. Each member carries P for primary or S for secondary.

Host	Use with the Sidecar
The primary member, port 27017	Yes.
A secondary member	No. Writes fail with NotWritablePrimary.
The mongodb+srv:// host	No. It is a DNS record, not a server.
A private endpoint host	Not covered on this page yet. M0 and Flex clusters have no private endpoints.

The primary changes during failovers and maintenance. See Behavior to know.

2

Write the config

Save this as config.yaml. Replace the upstream host with your primary.

config.yaml

admin:
  listen: 0.0.0.0:19000

audit:
  file: "-"
  query_sessions: 500

guardrails:
  rules:
    - name: no-destructive-commands
      type: operation
      operations: [drop, delete]
      message: destructive commands are blocked by Hoop

mask:
  rules:
    - {name: emails, columns: [email], strategy: redact}

listeners:
  - name: atlas
    protocol: mongodb
    listen: 0.0.0.0:27017
    upstream: ac-<prefix>-shard-00-01.<id>.mongodb.net:27017
    upstream_tls: {}

• guardrails blocks drop and delete commands.
• mask replaces the value of every email field in results, nested fields included.
• audit writes every command to stdout as JSON lines, and query_sessions turns on the /api/sessions endpoint.
• upstream_tls encrypts the hop to Atlas. Atlas certificates come from a public CA, so the Sidecar verifies them with no extra file.
• admin serves health checks and the audit API. It has no authentication, so the next step publishes it on loopback only.

The config holds no database password. The Sidecar relays the login from the client to Atlas.

3

Validate and start the Sidecar

docker run --rm \
  -v "$PWD/config.yaml:/etc/hoop-inspect/config.yaml:ro" \
  hoophq/hoopsidecar:<version> hoop start sidecar --validate

docker run -d --name hoop-atlas \
  -p 127.0.0.1:27017:27017 -p 127.0.0.1:19000:19000 \
  -v "$PWD/config.yaml:/etc/hoop-inspect/config.yaml:ro" \
  hoophq/hoopsidecar:<version>

--validate prints config OK: 1 listener(s) and the rule counts. Versions are on the releases page.

4

Point your clients at the Sidecar

Replace the mongodb+srv:// string with a mongodb:// string to the Sidecar. The user and password stay the same. Every client takes the same string: the MongoDB MCP server an AI agent uses (MDB_MCP_CONNECTION_STRING), mongosh, Compass and application drivers.

before: mongodb+srv://<user>:<password>@cluster0.<id>.mongodb.net/<db>
after:  mongodb://<user>:<password>@127.0.0.1:27017/<db>?authSource=admin&directConnection=true

• authSource=admin was set for you by the +srv string. Atlas keeps database users in admin.
• directConnection=true keeps the driver on the Sidecar. Without it, the driver reads the member list from the server, dials Atlas directly and fails.
• Leave out compressors= and loadBalanced=. The Sidecar supports neither.

The new string has no tls=true. That applies only to the hop from the client to the Sidecar on the same host. When clients reach the Sidecar over a network, put TLS in front of it. See TLS on each leg.

​

Verify

mongosh "mongodb://<user>:<password>@127.0.0.1:27017/shop?authSource=admin&directConnection=true"

db.customers.insertOne({ name: "Ana Souza", email: "ana.souza@example.com" })

db.customers.find()

[
  {
    _id: ObjectId('...'),
    name: 'Ana Souza',
    email: '[REDACTED:column:email]'
  }
]

db.customers.drop()

MongoServerError: destructive commands are blocked by Hoop

curl -s '127.0.0.1:19000/api/sessions?denied=true'

{"sessions":[{"principal":"anonymous","protocol":"mongodb","connection":"atlas","denied_count":1,"masked_count":1,"verdict":"denied"}],"total":1}

​

Allow only the Sidecar with the IP access list

1. In the Atlas UI, open Security, then Database & Network Access, then IP Access List.
2. Click Add IP Address and add the Sidecar’s IP.
3. Delete every other entry, including 0.0.0.0/0.

atlas accessLists create <ip> --type ipAddress --projectId <project-id> --comment "Hoop Sidecar"
atlas accessLists list --projectId <project-id>
atlas accessLists delete <entry> --projectId <project-id>

MongoServerSelectionError: ... SSL alert number 80
. It looks like this is a MongoDB Atlas cluster. Please ensure that your Network Access List allows connections from your IP.

​

Behavior to know

• A denied command closes the connection. The client reads the rule’s message as error code 13, Unauthorized, and an open transaction rolls back. Drivers retry reads and retryable writes on a new connection. Other commands, such as createIndex, can fail once with connection closed.
• A failover leaves the Sidecar on the old member. Atlas elects a new primary during failovers, maintenance and upgrades. Writes then fail with NotWritablePrimary, and reads come from a secondary, until you set upstream to the new primary and restart the Sidecar. Rule edits reload live; an upstream change needs a restart.
• Sessions show principal: anonymous. The Sidecar relays the login to Atlas and does not read the user name from it, so its audit does not name the database user. Atlas database auditing does, on clusters above the Free and Flex tiers.
• This page covers password users. A client’s X.509 certificate does not reach Atlas, because the Sidecar opens its own TLS connection.

​

Free and Enterprise

• More rules: an Enterprise license with the guardrails and data-masking features lifts the one-rule caps, with or without a Control Plane. In Docker, pass it with -e HOOP_LICENSE="$(cat license.json)". See Licensing.
• Reviews and central management: connect the Sidecar to a Control Plane, which also needs an Enterprise license. It adds reviews, shared rule sets and one view of many Sidecars.

​

Next