How to Configure OpenAI Agents SDK MongoDB Read Only Access

Published
Length
3 min read

Luis Felipe Dias

All posts

To set up openai agents sdk mongodb read only access, create a dedicated database user with the built-in read role. Pass that user's credentials to the tool functions that your agent runs. Teams often start by reusing an app's standard read and write account for agent tests. If a prompt causes the model to send a write or delete command, a broad role lets that change happen right away. How openai agents sdk mongodb read only access works In the OpenAI Agents SDK, an agent calls Python functio

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.

To set up openai agents sdk mongodb read only access, create a dedicated database user with the built-in read role. Pass that user's credentials to the tool functions that your agent runs. Teams often start by reusing an app's standard read and write account for agent tests. If a prompt causes the model to send a write or delete command, a broad role lets that change happen right away.

How openai agents sdk mongodb read only access works

In the OpenAI Agents SDK, an agent calls Python functions that you define as tools. The agent picks a tool and sends arguments based on the user prompt. Your tool code holds the database client and runs the actual query against MongoDB. The SDK itself does not manage database users or check query permissions.

MongoDB controls what that client can do through role-based rules. A role gives a user permission to run specific actions on a set resource. The built-in read role applies to the database where you define it. It lets the user read all non-system collections and the system JavaScript collection. This role permits actions like finding documents, listing collections, listing indexes, checking stats, and opening change streams.

It leaves out actions that change data, such as insert, update, remove, or drop collection. If you need tighter limits, MongoDB roles can grant access down to a single collection. Notice that self-hosted deployments and MongoDB Atlas use different built-in role lists, though both use the same privilege actions.

What native read roles solve and what they miss

Using the read role stops an agent from altering or deleting records. Even if a bad prompt tricks the agent into running a remove action, the database rejects it. This setup protects data integrity without adding extra checks inside your Python tool code.

Still, a database role only checks who logs in and which action type runs. It does not inspect the content of individual queries or the data coming back in flight. A read role still lets an agent pull every document in an allowed collection.

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.

If that collection holds emails, phone numbers, card numbers, or national IDs, the query returns those values to the agent. The agent then sends those raw fields to the model provider in the conversation history. Native roles also do not stop an agent from running a heavy find query that scans millions of documents.

How to reduce risk in agent database tools

Before you put an agent in production, narrow the scope of its database user. Create a custom role in MongoDB that only grants find actions on the exact collections the agent needs. Avoid giving the agent a role that spans every database in your cluster.

Next, keep your tool inputs strict. Instead of letting the model write raw query filters, give the tool fixed parameters. Your Python function can build a safe query from those inputs and cap the number of returned rows. While fixed tools help, teams building data exploration agents still need open query tools. Those open tools require runtime controls over the queries and the returned 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

Does the MongoDB read role block all data changes?

Yes, the built-in read role omits insert, update, remove, and drop collection actions. Any attempt by the agent's tool to modify data will fail at the database level.

Can I limit an agent to a single MongoDB collection?

Yes, MongoDB roles can grant permissions down to the collection level. You can create a custom role that allows find actions on one specific collection only.

Does a read-only role hide sensitive fields from the agent?

No, a read role allows the user to read entire documents in permitted collections. If documents contain emails, phone numbers, or card numbers, those fields are returned in the query results.

The query runs. The emails stay hidden.