How to Configure OpenHands MongoDB MCP Server

Published
Length
3 min read

Luis Felipe Dias

All posts

To set up an openhands mongodb mcp server, link your agent to a database role. Then pass the database credentials to the server runtime so the agent can run queries. Teams often start by giving the agent a broad role to test fast. This shortcut creates risk when the agent runs bad commands or reads private fields. How the openhands mongodb mcp server setup works OpenHands uses the Model Context Protocol to talk to outside tools and data stores. The server acts as a bridge between the agent an

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 an openhands mongodb mcp server, link your agent to a database role. Then pass the database credentials to the server runtime so the agent can run queries. Teams often start by giving the agent a broad role to test fast. This shortcut creates risk when the agent runs bad commands or reads private fields.

How the openhands mongodb mcp server setup works

OpenHands uses the Model Context Protocol to talk to outside tools and data stores. The server acts as a bridge between the agent and your document database. When the agent needs data, it sends a tool request to the server. The server translates that request into a database action and returns the result.

To make this work, you first create a dedicated user in your database. MongoDB grants access through role-based rules that allow specific actions on defined resources. A role applies to its home database and can limit actions down to one collection. Note that Atlas database users have different built-in roles than self-hosted users. Still, both types of roles build on the same set of basic privilege actions.

For a safe start, assign the built-in read role to the agent user. The read role lets the server read all non-system collections in that database. It allows actions like find, listCollections, listIndexes, dbStats, collStats, and changeStream. It blocks write actions such as insert, update, remove, and dropCollection.

Once the user is ready, you place the login string into the OpenHands settings. The agent starts the server process in its workspace and logs in with those keys. Every command the agent chooses to run will now use that single database role.

What native roles solve and what they leave open

Native database roles are great at controlling who can log in to a cluster. They also set a hard ceiling on which collections a user can touch. If you give the server a read role, the agent cannot drop a collection. This stops basic accidents where a confused model tries to delete test data.

Still, a database role does not inspect individual commands while they run in flight. If the agent needs to fix data, you must give it the readWrite role. The readWrite role includes everything in read plus the power to change data. It allows insert, update, remove, createCollection, createIndex, dropIndex, and dropCollection. Once the agent has readWrite, it can wipe a whole collection with one command.

MongoDB Authentication & Authorization + Kubernetes API Server Access: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Even a strict read role leaves a major gap around sensitive customer data. Because roles stop at the collection level, the agent reads every field in a document. If a collection holds emails, phone numbers, card numbers, or national IDs, the agent gets them. Those raw values flow right into the model context window and external model logs. Native roles also place raw login keys inside the agent runtime space. If a bad prompt tricks the agent, it can read and leak those stored keys.

Why static credentials fail for autonomous agents

Human developers usually run one query at a time and check the output. An autonomous coding agent can fire dozens of database calls in a few seconds. When you bind a static user to the server, every call shares the same trust. You cannot pause a single risky update for human review before it hits the database.

Database logs also struggle to show why an agent ran a specific command. All traffic from the server arrives under one shared service account name. Security teams see the database action, but they cannot link it to the user prompt. To run agents safely in production, teams need controls that work per query and field. For sensitive collections, dynamic data masking rewrites matched fields like card numbers in query results.

Check MongoDB commands and documents on the wire

MongoDB roles and SCRAM login decide who opens a session. They do not check single commands or redact sensitive fields inside returned documents. With hoop.dev, you run an open-source proxy, a sidecar for your MongoDB. It reads the MongoDB wire protocol and checks commands and bulk writes as JSON while passing login through untouched.

Before a command runs, hoop.dev guardrails check its effect and refuse banned drops or writes with MongoDB error code 13. On the way back, hoop.dev data masking rewrites sensitive fields in returned documents that match your rules. Every command and verdict is logged. See the open-source code on GitHub.

Frequently asked questions

What database role should I give an OpenHands agent?

Start with the built-in read role scoped to a single database or collection. This role lets the agent run find and listCollections without allowing data changes. Only grant readWrite if the task requires inserts or updates, and watch those sessions closely.

Can native MongoDB roles hide specific document fields from the agent?

No, native built-in roles only control access down to the collection level. If an agent can run find on a collection, it gets every field in the document. You need field-level masking to rewrite emails, phone numbers, or card numbers in results.

What is the biggest risk of giving the MCP server a readWrite role?

The readWrite role grants destructive actions like remove, dropIndex, and dropCollection alongside normal updates. An autonomous agent can misread a prompt and delete an entire collection in seconds. Without command-level checks or human approval, the database will run that drop command right away.

The query runs. The emails stay hidden.