How to Configure OpenHands Postgres MCP Server

Published
Length
3 min read

Luis Felipe Dias

All posts

To set up an openhands postgres mcp server, point the agent to your local MCP process. Next, pass a dedicated database connection string with read-only permissions to that server process. Many teams start by giving the agent their main app database role to move fast. That broad role lets an autonomous coding agent alter schemas or read sensitive user rows. Scoping the database role before the agent runs is the safest way to start. How the openhands postgres mcp server architecture works OpenH

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 postgres mcp server, point the agent to your local MCP process. Next, pass a dedicated database connection string with read-only permissions to that server process. Many teams start by giving the agent their main app database role to move fast. That broad role lets an autonomous coding agent alter schemas or read sensitive user rows. Scoping the database role before the agent runs is the safest way to start.

How the openhands postgres mcp server architecture works

OpenHands runs as an autonomous coding agent that can execute tasks across your workspace. The Model Context Protocol lets the agent call external tools through a standard local interface. When you add a Postgres MCP server, OpenHands spawns or talks to that server process. The MCP server holds the database credentials and runs SQL queries on the agent's behalf.

Your first step in the database is creating a dedicated role for the agent. In PostgreSQL, you can set up group roles to manage privileges for multiple users. You then grant your new agent user membership in that read-only group role. The SELECT privilege allows reading from specific columns of a table, view, or materialized view. You can grant SELECT on only the non-sensitive columns your agent needs to inspect.

You must also check the default rights that PostgreSQL gives to every new role. The special role name PUBLIC grants privileges to every role on the database system. By default, PUBLIC gets CONNECT and TEMPORARY on databases, plus EXECUTE on functions and procedures. The object owner can revoke these default PUBLIC privileges to lock down the database. In PostgreSQL 15 and later, default settings stop all users from creating public schema objects. On older or upgraded databases, an admin must revoke CREATE on the public schema from PUBLIC.

Why native roles are not enough for agent queries

Native PostgreSQL privileges are essential for basic hygiene, and they control who can log in. They also decide which tables or columns a database role is allowed to read. Still, static database grants do not inspect what individual SQL statements do in flight. Once the MCP server connects, every query from the agent runs with that role's full power.

Even with column grants, a table might hold emails, phone numbers, or card numbers. If the agent needs to query that table for debugging, raw rows come back. The agent then sends those raw emails or national IDs straight into the model prompt. Data masking at the query level rewrites matched fields in results before the agent reads them.

Kubernetes API Server Access + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Static credentials in an MCP config file also create a secret management problem for teams. Developers often store plain database passwords on their laptops to make the local MCP server work. If you allow write queries for schema migrations, a bad prompt can drop production data. Native roles cannot pause a risky statement and ask a human to approve it first.

Managing schema changes and multi-agent workflows

Teams often run multiple OpenHands sessions at once to fix bugs and build new features. When every agent shares one static role, your database logs show one single user name. You cannot tell which agent task or developer triggered a slow or broken query. Tying each query to an individual user identity fixes this audit gap right away.

Sometimes an agent needs to test a new index or run a table migration. Giving the MCP server permanent write rights leaves your tables open to accidental deletes all day. Instead, teams should keep the agent read-only by default and approve write queries per task. This approach stops unreviewed schema edits while keeping the agent useful for daily coding work.

Run guardrails and masking on the Postgres connection

Role grants and firewall rules are needed setup. Setup alone cannot check single SQL statements or mask sensitive rows in a response. By design, hoop.dev is an open-source proxy that sits beside Postgres, RDS, or Aurora as a sidecar for your Postgres. Clients and agent tools keep their credentials and point their connection string at the listener.

On each query, hoop.dev guardrails refuse disallowed drops, deletes, or table reads before they run. Next, hoop.dev data masking rewrites sensitive fields in returned rows that match your rules. Furthermore, hoop.dev holds SOC 2 Type II and logs every statement and verdict per resource. Check out the project on GitHub.

Frequently asked questions

How does the OpenHands agent talk to PostgreSQL through MCP?

OpenHands sends tool requests to the Postgres MCP server over a local communication channel. The MCP server translates those tool calls into SQL queries and runs them against PostgreSQL.

Can I restrict the agent to specific columns in PostgreSQL?

Yes, PostgreSQL lets you grant the SELECT privilege on specific columns of a table or view. You should also revoke default PUBLIC privileges so the agent role only reads approved objects.

Why is a read-only role still risky for an AI coding agent?

A read-only role still returns raw text from any column the role is allowed to query. Without runtime data masking, sensitive emails, phone numbers, or card numbers enter the model context.

The query runs. The emails stay hidden.