How to Configure Mastra MongoDB Read Only Access

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up mastra mongodb read only access by giving your agent a database user with the built-in read role. Then you pass those user keys to your Mastra app so the agent can only run read queries. Many teams start by reusing a shared admin or readWrite user during agent testing. When that broad role reaches live apps, one bad prompt can change or drop whole collections. How mastra mongodb read only access works with database roles MongoDB controls access through role-based rules. A role give

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

You set up mastra mongodb read only access by giving your agent a database user with the built-in read role. Then you pass those user keys to your Mastra app so the agent can only run read queries. Many teams start by reusing a shared admin or readWrite user during agent testing. When that broad role reaches live apps, one bad prompt can change or drop whole collections.

How mastra mongodb read only access works with database roles

MongoDB controls access through role-based rules. A role gives a user the right to run specific actions on a resource. Each role applies to the database where you define it. You can also scope custom roles down to the collection level. Self-hosted databases and MongoDB Atlas have different built-in roles, but both use the same privilege actions.

To lock down an AI agent, you create a dedicated database user for Mastra. You assign the built-in read role to that user on the target database. The read role lets the user read all non-system collections and the system.js collection. It allows actions like find, listCollections, listIndexes, dbStats, collStats, and changeStream.

The read role leaves out write actions. It blocks insert, update, remove, and dropCollection commands. In contrast, the readWrite role includes everything in the read role plus data change rights. A readWrite user can also run createCollection, createIndex, and dropIndex. Keeping your Mastra user on the read role stops the agent from changing records.

Why collection-level read roles still leave data gaps

Setting up a read-only database user solves the first half of the agent safety problem. It stops an agent from altering rows or dropping tables when a tool call goes wrong. Database roles decide who can log in and which collections they can read.

Still, MongoDB roles do not inspect what individual queries return in flight. A role can grant access down to a single collection, not to safe fields inside a document. Once the Mastra user has the read role on a collection, the find action returns full documents.

Auditor Read-Only Access + Customer Support Access to Production: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Customer collections often hold mixed data in the same document. An order document might store product totals right next to emails, phone numbers, card numbers, or national IDs. When the Mastra agent runs a find query, all of those fields enter the model context. Also, storing static database keys inside the Mastra app means the app holds permanent login rights. If a key leaks, anyone can pull every collection tied to that role.

Separating agent tool calls from raw database keys

Teams running AI agents in live apps need controls that act on each query. First, you should keep static database keys out of the agent host. The agent should run queries without holding long-lived passwords in local memory.

Second, you need a way to check and filter query results before the agent reads them. Masking rules can rewrite matched fields like emails or card numbers in the query output. This lets the Mastra agent answer user questions using live MongoDB data while keeping sensitive fields redacted. You also get a clear log of every query the agent runs.

Inspect MongoDB wire traffic in flight

Built-in MongoDB roles govern collection access at setup time. They cannot score command risk per call or mask sensitive document values on the fly. By design, hoop.dev is an open-source proxy that sits next to MongoDB as a sidecar for your MongoDB. It reads every command from mongosh, drivers, or agent tools.

First, hoop.dev guardrails block bad deletes, drops, and write pipelines. Next, hoop.dev data masking rewrites sensitive values in returned documents based on your rules and logs each decision. Explore the repo on GitHub.

Frequently asked questions

What is the difference between the MongoDB read and readWrite roles for Mastra?

The read role allows query actions like find, listCollections, and changeStream on non-system collections. The readWrite role adds data change actions like insert, update, remove, createIndex, and dropCollection. For a read-only Mastra agent, always assign the read role so tool calls cannot modify data.

Can a MongoDB role restrict Mastra to a single collection?

Yes, MongoDB roles can grant access down to the collection level. While the built-in read role covers all non-system collections in a database, you can define a custom role. That custom role can grant the find action on one specific collection only.

Does the MongoDB read role hide sensitive fields from Mastra agents?

No, MongoDB roles work at the database and collection level, not the document field level. If a Mastra user has read rights on a collection, a find query returns the whole document. You need query result masking to rewrite sensitive fields like phone numbers or card numbers in results.

The query runs. The emails stay hidden.