How to Configure OpenAI Agents SDK MongoDB Approval

Published
Length
3 min read

Luis Felipe Dias

All posts

You set up an openai agents sdk mongodb approval workflow by pairing scoped database roles with human review checks. The agent pauses before running a database tool until a reviewer approves the action. Many teams start by giving an agent a single database login with broad rights. That setup lets the agent read and change data across every collection in the database. If the model misinterprets a prompt, it can delete records or pull sensitive fields. How openai agents sdk mongodb approval work

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 an openai agents sdk mongodb approval workflow by pairing scoped database roles with human review checks. The agent pauses before running a database tool until a reviewer approves the action. Many teams start by giving an agent a single database login with broad rights. That setup lets the agent read and change data across every collection in the database. If the model misinterprets a prompt, it can delete records or pull sensitive fields.

How openai agents sdk mongodb approval works in practice

In the OpenAI Agents SDK, you give an agent Python functions to use as tools. Each tool wraps a specific task, such as reading a document or updating a record. To reach a database, the tool uses a standard database driver and a login credential. When the model decides to call a tool, the SDK triggers that function with arguments.

MongoDB controls database access through role-based rules that grant actions on specific resources. A role applies to the database where you define it. You can scope a role down to the individual collection level. The built-in read role allows actions like find, listCollections, listIndexes, dbStats, collStats, and changeStream. It applies to all non-system collections in that database. It leaves out actions that change data, such as insert, update, remove, and dropCollection.

When an agent must change data, teams assign the built-in readWrite role or custom roles. The readWrite role includes all read actions plus insert, update, remove, and dropCollection. It also grants createCollection, createIndex, and dropIndex on that database. Because those actions alter state, teams wrap write tools in an approval step. The agent builds the tool call, stops execution, and waits for a person to approve.

What native roles solve and what they leave open

Combining scoped database roles with app-level checks solves basic permission issues. A read-only agent with the read role cannot run a remove or dropCollection action. Splitting read tools from write tools also clarifies which agent steps need a human check. App-level checks let a team member inspect the tool arguments before the Python function runs.

Still, static database roles only check who logs in at the start of a session. They do not inspect what individual queries or commands do in flight. Even a read role lets an agent run find across every non-system collection in the database. If a collection holds emails, phone numbers, card numbers, or national IDs, the query returns them. Data masking rewrites matched fields in results so raw values do not reach the model.

Approval Chains & Escalation + MongoDB Authentication & Authorization: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

App-level approval code also lives inside the agent codebase itself. Each developer must remember to add the pause check to every new database tool. If an agent gets a general query tool, the reviewer only sees raw query text. Native database roles also mean the app holds static database keys in its local settings. A strong setup moves command checks, field masking, and human review outside the agent code.

Separating read and write tools for safer agent runs

Good agent design splits database tasks into narrow, single-purpose tools. Give your search tools a database user that holds only the read role. Build separate write tools for actions like insert or update on one specific collection. Require a human approval check whenever the agent calls any tool that changes records.

Keep your approval prompts clear so reviewers know what the agent plans to do. Show the target collection name, the action type, and the exact fields being changed. Log every approval decision alongside the database query that ran after the check. This audit trail helps your team review how agents use database permissions over time.

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

Can a MongoDB role restrict an agent to a single collection?

Yes, MongoDB roles grant privileges to run specific actions on defined resources. You can scope a custom role down to an individual collection in a database. This stops the agent from touching other collections during its run.

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

The read role allows read actions like find and listCollections on non-system collections. The readWrite role adds write actions like insert, update, remove, createIndex, and dropCollection. Assign readWrite only when an agent tool must change data.

Why do read-only agent tools still need field controls?

The read role still lets an agent query sensitive fields inside allowed collections. Without field masking, queries return raw emails, phone numbers, card numbers, and national IDs. Masking rewrites matched fields in results before the agent processes the output.

The query runs. The emails stay hidden.