PostgreSQL MCP connector

What agents can do

The server has 8 actions: 7 read and 1 write.

• Explore the schema: list_schemas lists schemas, list_tables lists tables, views, sequences or extensions, and get_table_schema returns a table's columns.
• Table details: get_table_metadata returns constraints, indexes, estimated row count and size.
• Run SQL: run_query runs SQL with $1-style parameters and returns up to 10,000 rows.
• Query plans: explain_query shows EXPLAIN plans, or EXPLAIN ANALYZE when analyze is requested.
• Health and performance: analyze_db_health reports connections, vacuum age, sequences, replication slots, cache hit rates and invalid constraints, and get_top_queries lists the slowest queries from pg_stat_statements.

Before you connect

• A database role just for InsightfulPipe with only the privileges agents need, for example SELECT for read-only use. Never reuse a superuser.
• A public hostname or IP address. Private, loopback and link-local addresses are rejected.
• TLS enabled on the server, with a certificate that matches the hostname or a CA certificate you can provide.
• If the database is firewalled, allowlist InsightfulPipe's outbound IP addresses, shown in your workspace settings, in your firewall and pg_hba.conf.

Connect PostgreSQL

1. In the InsightfulPipe app, open Connectors, choose PostgreSQL and click Connect.
2. Enter a Connection name. InsightfulPipe generates the connection's MCP identifier from it.
3. Choose String connection URI and paste a URI such as postgresql://user:[email protected]:5432/mydb?sslmode=require, or choose Enter fields manually.
4. For manual entry, fill in Host, Port, Database, Username and Password, and pick an SSL mode.
5. If the server uses a private CA or client certificates, open Advanced: client TLS certificates and add the server CA certificate, client certificate and client private key in PEM format.
6. Click Connect PostgreSQL. InsightfulPipe runs one short SELECT 1 to verify the connection before saving it.

Add the MCP server to your AI client

Server URL: https://postgresql.insightfulmcp.com/ and server name: postgresql-mcp.

• Claude: open Claude Connectors Settings, scroll to the bottom and click Add custom connector, paste the URL, click Add, then click Connect.
• ChatGPT: in ChatGPT Security Settings turn on Developer mode, click Create on the Connectors page, paste the URL, click Create, then click Connect. Turn the connector on in each new chat with + → More.
• Claude Code: run claude mcp add --transport http postgresql-mcp https://postgresql.insightfulmcp.com/, then type /mcp, select postgresql-mcp and click Authenticate.
• Cursor: in the app, open MCP Servers, choose PostgreSQL and click Install PostgreSQL MCP, click Open Cursor then Install, then click Connect and Open.
• Gemini CLI: run gemini mcp add --transport http postgresql-mcp https://postgresql.insightfulmcp.com/, then /mcp auth postgresql-mcp.
• Codex CLI: run codex mcp add postgresql-mcp --url https://postgresql.insightfulmcp.com/; authorization starts automatically.

Each client opens a browser window where you log in to InsightfulPipe and click Authorize access. Step-by-step guides: Claude, ChatGPT, Claude Code, Cursor, Gemini CLI and Codex CLI. To reach every connected platform through one server, use the unified server.

Permissions and safety

• No Read Only mode: PostgreSQL connections have no Read Only or Read + Write choice in InsightfulPipe. The GRANTs on the database role decide whether a statement succeeds.
• What counts as a write: a request is a read only when it is a single SELECT statement with no INTO and no data-changing CTE. Anything else, such as INSERT, UPDATE, DELETE, CREATE or DROP, or several statements in one request, is a write.
• Where writes run: the read-only query_data tool refuses writes, so they run only through execute_action, and only for members with the Owner, Administrator or Operator role. InsightfulPipe does not limit which statement types run.
• On by default: run_query is enabled on a new connection.
• EXPLAIN ANALYZE runs the statement: explain_query counts as a read action, but with analyze it executes the statement it explains. To stop agents running SQL, turn off both run_query and explain_query in Configure actions for this account, which leaves schema discovery and health checks.
• Keep it read-only: connect with a role that has only SELECT privileges, so PostgreSQL rejects writes.
• Restricted members: members with the User role only get the read actions enabled on databases granted to them.

Limits

• Rows: up to 10,000 rows per query, 1,000 by default.
• Timeout: statements time out after at most 60 seconds.
• Query size: query text can be up to 256 KB.
• TLS: the disable, allow and prefer SSL modes are refused, and connections are upgraded to verify-full, so the server certificate is checked against the hostname.
• Network: databases on private networks without a public address are not supported.
• Top queries: get_top_queries needs the pg_stat_statements extension.
• Lost write responses: if the response to a write is lost, the result is reported as an unknown outcome instead of being retried. Check the database before running the statement again.

Example prompts

• "List the tables in the public schema."
• "What columns and indexes does the orders table have?"
• "Which queries use the most total execution time?"
• "Show the query plan for this report query without running it."

Troubleshooting

• The connection test fails: check the host, port and database name, that the host is public, that your firewall and pg_hba.conf allow InsightfulPipe's outbound IP addresses, and that TLS is on with a certificate that matches the hostname or a CA certificate you added.
• "This action modifies data and cannot run through the read-only query_data tool. Send the same body through execute_action instead." The SQL is not a single SELECT, so it must run through execute_action.
• "Your role does not have permission to execute write actions. Only operators, admins, and owners can execute write operations." Members with the User role can't run writes. Ask a workspace admin to change your role.
• PostgreSQL returns a permission denied error: the database role lacks that privilege. Grant it on the server, or leave the role read-only on purpose.
• A query times out: add filters or a LIMIT, check the plan with explain_query without analyze, or allow a longer timeout of up to 60 seconds.

FAQ

Which SQL statements can agents run?

Any statement the database role is allowed to run. A single SELECT runs as a read. INSERT, UPDATE, DELETE, DDL, SELECT INTO, data-changing CTEs and multiple statements are writes, limited to owners, administrators and operators.

How do I keep the connection read-only?

Connect with a role that has only SELECT privileges. You can also turn off run_query and explain_query for the connection, which leaves schema discovery and health checks.

Can I connect a database on a private network?

No. The database must be reachable on a public hostname or IP address over TLS. If it is firewalled, allowlist InsightfulPipe's outbound IP addresses from your workspace settings.

Can I connect several databases?

Yes. Each connection is one database on one host with its own name, and each counts toward your plan's connection limit.

Related

• PostgreSQL MCP server
• MySQL, SQL Server and BigQuery connectors
• Google Sheets connector
• Roles and permissions
• MCP troubleshooting