How to Connect PostgreSQL MCP to an AI Agent
Auth setup
1. Create a read-only Postgres role: CREATE ROLE agent_ro LOGIN PASSWORD '...'; GRANT pg_read_all_data TO agent_ro; 2. Connection string: postgres://agent_ro:***@host:5432/db. 3. Run: npx @anthropic/postgres-mcp 'postgres://...' — the server enforces read-only at the protocol level.
Key facts
| Base URL | https://www.postgresql.org/docs/current/libpq.html |
|---|
| API version | PostgreSQL protocol (MCP server wraps libpq) |
|---|
| Auth | Connection string with PostgreSQL credentials (user/password/host/db). The official MCP server by Anthropic (npx @anthropic/postgres-mcp) is strictly read-only and accepts a PostgreSQL connection URL as its argument. Authentication is delegated to Postgres itself (password, scram, client cert, or peer). |
|---|
| Scopes | read-only (enforced by MCP server — no INSERT/UPDATE/DELETE) |
|---|
| Request body | MCP tool call (JSON-RPC over stdio) |
|---|
| Pagination | SQL LIMIT/OFFSET in query text. No built-in pagination at the MCP layer. |
|---|
| Rate limit | No MCP-level rate limit. Postgres-side: respect statement_timeout, max_connections, and any pg_stat_statements throttling. Agents should honor statement_timeout (recommended 30s) to prevent runaway queries. |
|---|
| Error format | SQL errors returned as JSON: {"error":{"code":"42P01","message":"relation \"x\" does not exist","position":"15"}} |
|---|
Key endpoints
| Method | Path | Description |
|---|
TOOL | query | Execute a read-only SQL query and return rows. Blocks any statement that isn't SELECT/WITH. |
TOOL | list_schemas | List all schemas in the database (excluding system schemas) |
TOOL | list_tables | List tables in a given schema with row count estimates |
TOOL | describe_table | Get columns, types, constraints, and indexes for a table |
Quickstart
Tool call: {"name":"query","arguments":{"sql":"SELECT table_name, n_live_tup FROM pg_stat_user_tables ORDER BY n_live_tup DESC LIMIT 10"}}
Response: [{"table_name":"orders","n_live_tup":1234567},...]
Agent pitfalls & tips
- The official MCP server is READ-ONLY by design — attempting INSERT/UPDATE/DELETE returns an error at the MCP layer before hitting Postgres.
- Always set statement_timeout in the connection string (e.g., ?options=-c%20statement_timeout%3D30s) to prevent runaway queries from blocking other agents.
- Use pg_stat_user_tables and pg_stat_statements for schema and performance inspection — these are the agent's main windows into DB health.
- For multi-tenant databases, create a dedicated read-only role per tenant and pass the correct connection string — don't try to filter at the query level.
- Avoid SELECT * on large tables — always project specific columns and use LIMIT. Postgres-MCP doesn't truncate responses.
- EXPLAIN (FORMAT JSON, ANALYZE false) is safe read-only and gives agents plan info without actually running the query.
- Information_schema and pg_catalog are the canonical sources for schema metadata. Prefer them over vendor-specific tables.
- For very large result sets, use server-side cursors via DECLARE CURSOR ... WITH HOLD, then FETCH in batches.
Source: curated by KanseiLink from official documentation (docs) and registry checks. Last reviewed: 2026-04-10. Specs change — verify against the official docs before production use.
Frequently Asked Questions
What is PostgreSQL MCP's AEO score?
▼
PostgreSQL MCP has an AEO score of 0.90 and is rated AA (Strong agent support with minor gaps). AEO (Agent Engine Optimization) measures how well a SaaS service works with AI agents. Scores range from 0.00 to 1.00, with grades from AAA (best) to D (not agent-ready).
Is PostgreSQL MCP AI-agent-ready?
▼
PostgreSQL MCP is currently ✓ verified for AI agent use. It offers an official MCP (Model Context Protocol) server, which means AI agents can connect directly. For detailed connection guides, auth setup, and known pitfalls, use the KanseiLink MCP tool.
How does PostgreSQL MCP compare to other Database services?
▼
In the Database category, PostgreSQL MCP is rated AA. KanseiLink evaluates services based on MCP availability, API quality, documentation, auth-guide clarity, and integration recipe availability (methodology published). Visit the full rankings at kansei-link.com to see how PostgreSQL MCP compares.
How can I integrate PostgreSQL MCP with an AI agent?
▼
The fastest way to integrate PostgreSQL MCP with an AI agent is through KanseiLink MCP. Install it with: npx @kansei-link/mcp-server — then use the search_services and get_service_detail tools to get the current auth setup, endpoints, rate limits, and agent-specific tips. This data is kept fresh from registry checks, curated official-doc guides, and agent reports.
How do I authenticate with PostgreSQL MCP?
▼
Connection string with PostgreSQL credentials (user/password/host/db). The official MCP server by Anthropic (npx @anthropic/postgres-mcp) is strictly read-only and accepts a PostgreSQL connection URL as its argument. Authentication is delegated to Postgres itself (password, scram, client cert, or peer). Setup: 1. Create a read-only Postgres role: CREATE ROLE agent_ro LOGIN PASSWORD '...'; GRANT pg_read_all_data TO agent_ro; 2. Connection string: postgres://agent_ro:***@host:5432/db. 3. Run: npx @anthropic/postgres-mcp 'postgres://...' — the server enforces read-only at the protocol level.
What are PostgreSQL MCP's API rate limits?
▼
No MCP-level rate limit. Postgres-side: respect statement_timeout, max_connections, and any pg_stat_statements throttling. Agents should honor statement_timeout (recommended 30s) to prevent runaway queries.