How to Configure Mastra MongoDB Least Privilege

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up mastra mongodb least privilege by assigning database roles scoped to single collections. You then bind each agent tool to a dedicated user with read or write limits. Many teams start by giving their agent workflow a single admin database user. That broad role lets one bad prompt modify records or drop whole collections. How mastra mongodb least privilege works in practice Mastra runs agent workflows that call external tools and query data stores. When an agent interacts with a data

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 least privilege by assigning database roles scoped to single collections. You then bind each agent tool to a dedicated user with read or write limits. Many teams start by giving their agent workflow a single admin database user. That broad role lets one bad prompt modify records or drop whole collections.

How mastra mongodb least privilege works in practice

Mastra runs agent workflows that call external tools and query data stores. When an agent interacts with a database, it uses the credentials you provide. If those credentials hold wide permissions, every tool in that workflow inherits those rights. Limiting what the database user can do is the foundation of safe agent design.

MongoDB uses role-based authorization to control what a user can do after logging in. A role grants privileges to perform specific actions on defined resources. Each role applies to the database where you define it. Roles can grant access down to a collection level of granularity.

Note that MongoDB Atlas database users have different built-in roles than self-hosted deployment users. Still, both platforms build their roles from the same set of privilege actions. You can pick built-in roles or create custom roles for specific collections.

For agent tools that only fetch context, the built-in read role is the right starting point. The read role gives read access to all non-system collections in its database. It also covers the system.js collection. It allows actions like find, listCollections, listIndexes, dbStats, collStats, and changeStream.

The read role does not include insert, update, remove, or dropCollection actions. If an agent only needs one collection, a custom role is even safer. You can grant the find action on that single collection alone. That stops the agent from reading other tables in the same database.

Splitting read and write roles across agent tools

Some agent workflows must save state, log results, or update customer records. For those tasks, teams often look at the built-in readWrite role. The readWrite role includes everything in the read role plus the ability to modify data. Its actions include insert, update, remove, createCollection, createIndex, dropIndex, and dropCollection.

Least Privilege Principle + MongoDB Authentication & Authorization: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Notice that the built-in readWrite role includes the dropCollection and remove actions. An agent tool that only needs to insert new items should not hold drop rights. Instead of using the full readWrite role, build a custom role for that tool. Grant only insert and update actions on the target collection.

You should also split credentials across your Mastra tools rather than sharing one user. Give your search and retrieval tools a user with collection-scoped read privileges. Give your state update tools a separate user that only allows insert or update actions. This split ensures a read tool can never alter data if a prompt goes wrong.

What native database roles solve and what they leave open

Native database roles decide which user can log in and which collections they can touch. They stop an agent with read permissions from running a remove or dropCollection action. They also block a scoped user from querying collections outside its assigned list. This setup reduces the blast radius of a confused or hijacked agent.

Still, static roles do not inspect what individual queries do once the session starts. A role that grants find on a customer collection allows any read query on it. The agent can still pull every document in that collection with one broad command. Native roles also cannot rewrite sensitive fields in query results on the fly.

If a collection holds emails, phone numbers, card numbers, or national IDs, find returns them all. A static role cannot mask those fields in results before they reach the model. Also, shared app credentials make it hard to tie a query back to one person. Teams need runtime controls to check queries in flight and rewrite sensitive output fields.

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

Should I give my Mastra agent the built-in readWrite role?

No, the built-in readWrite role is too broad for most agent tools. It includes dropCollection, dropIndex, and remove actions along with insert and update. Create a custom role that grants only insert or update on the specific target collection.

Can MongoDB roles restrict an agent to a single collection?

Yes, MongoDB roles can grant access down to a collection level of granularity. You can define a custom role on a database and name the exact collection. The agent will only be able to run permitted actions on that one collection.

Why are read-only roles not enough to protect sensitive data from agents?

A read role still allows the find action across every field in an allowed collection. If documents contain emails, phone numbers, or card numbers, the query returns those raw values. You need data masking in flight to rewrite matched fields in results before the agent reads them.

The query runs. The emails stay hidden.