Cursor Postgres

Postgres Editor MCP Setup License

The failure mode this fixes

You ask Cursor for a query. It writes:

SELECT species_name, planted_date
FROM trees
WHERE health_status = 'poor';

Three of those five identifiers are invented. Your column is species, not species_name. Your date column is planted_on. health_status exists but its values are integers from a condition survey, not the string 'poor'. The SQL is syntactically perfect and completely useless, and you find out only when you paste it into psql.

This happens because the model is pattern-matching on what a tree table usually looks like. It has never seen yours. Nothing in your open editor tabs tells it, either — the schema lives in the database, and the database is the one thing an editor cannot see.

Giving Cursor an MCP connection to the database changes the order of operations. The agent calls grove_list_tables, then reads the actual column list, and only then writes SQL. Same model, one extra round trip, and the identifiers are now observed rather than assumed.

Fix, in three steps

1. Get a PostgreSQL instance and a token at freebase.cloud — sign up, create a session, choose PostgreSQL 16.2. Then Settings → MCP → New Token, pick the connection, copy the URL. It looks like https://freebase.cloud/api/mcp/YOUR_TOKEN.

2. Write ~/.cursor/mcp.json (or .cursor/mcp.json in the repo, if the database belongs to the project rather than to you).

3. Open Cursor Settings → MCP, confirm the entry is green, and turn on agent mode. Ask mode does not invoke tools.

The config

{
  "mcpServers": {
    "grove": {
      "url": "https://freebase.cloud/api/mcp/YOUR_TOKEN"
    }
  }
}

Two things people get wrong here.

Cursor does not take a "type" key. Claude Code's .mcp.json requires "type": "http" and will error without it; Cursor decides from whether you supplied url or command. Copying a working Claude Code entry across, type and all, produces a server that never turns green and never explains why.

And there is no auth block. The token is a path segment of the URL, so there is no headers, no env, no Authorization. That also means the file is a secret — gitignore it, or commit a version with YOUR_TOKEN left in place and let each developer fill it in from the token settings page.

Teaching the agent your schema

grove_list_tables gives structure. It does not give meaning, and meaning is where the second class of bad query comes from — correct columns, wrong assumption about what they hold.

grove_annotate_table attaches a description that the model reads before planning:

Annotate the inspections table: one row per site visit, condition is the 1–5 municipal condition rating where 1 is dead and 5 is excellent, and dbh_cm is trunk diameter at breast height in centimetres.

Do this once per table that has any non-obvious column. It sticks, and it is the highest-leverage five minutes in this whole setup. examples/schema_reality_check.py talks to the same connection Cursor uses and will list which of your tables still have no annotation.

A rules file helps too

Cursor reads .cursor/rules/*.mdc. A short one keeps the agent from falling back to guesswork when it is in a hurry:

---
description: Database access
alwaysApply: true
---

- Before writing SQL against Postgres, call grove_list_tables and inspect the real columns.
- Never invent a column name. If a column you expect is missing, say so instead of guessing.
- Use grove_query for reads. Use grove_store for writes, and only when explicitly asked.
- Target PostgreSQL 16 syntax.

The tools you get

Tool	Notes
grove_list_tables	Table list for the connected database
grove_query	Read-only SQL, returns rows
grove_store	Inserts and upserts
grove_annotate_table	Stores a human description against a table

PostgreSQL connections additionally surface pg_tables, pg_dump and pg_restore helpers, which is what makes an "export this before I migrate it" request work end to end.

psql still works

MCP is for the agent. Your application should use a driver, and PostgreSQL here is a real server on the real wire protocol:

postgresql://freebase@HOST:5432/DBNAME

psql, libpq, pgx, SQLAlchemy, Prisma, Sequelize, pgAdmin, DBeaver — none of them need to know MCP exists. examples/tree_inventory.sql is a plain psql script; run it with psql -f, then ask Cursor about the tables it created and watch the agent discover them.

Window functions, CTEs, JSONB with GIN indexes, materialized views, EXPLAIN ANALYZE — the PostgreSQL 16.2 feature set is intact, not a subset.

Troubleshooting

The server never turns green. Validate the JSON first (python3 -m json.tool ~/.cursor/mcp.json); a stray comma fails silently. Then remove "type" if you pasted it in. Then use the refresh control next to the server entry rather than restarting Cursor — it re-runs the handshake and surfaces the error.

It is green but the agent never uses it. You are probably in Ask mode. Also check the tool toggles for the current conversation, and the number of MCP servers you have registered — Cursor limits how many tools it will present at once, and a crowded list pushes the database tools out.

Tools appear but every call returns an error. Run python examples/schema_reality_check.py. It performs the same handshake outside the editor, so it separates "Cursor is misconfigured" from "the token is dead". If it is dead, mint a replacement from the dashboard.

Queries succeed but return nothing. Confirm the token points at the connection you think it does. One token maps to one connection; if you created several sessions, it is easy to have wired up the empty one.

FAQ

Is this a real PostgreSQL server? Yes — 16.2, wire-protocol compatible. Existing drivers, ORMs and migration tools connect without modification.

Can I export my data? pg_dump and pg_restore both work over the standard protocol, and the MCP connection exposes them as tools as well.

Does the agent get write access? grove_store exists, so yes. If that makes you uncomfortable, disable that single tool in Cursor's per-server tool list and leave the read tools on.

What is the free tier actually for? Development, prototyping and small production workloads. There is no published SLA or managed backup product, so schedule your own pg_dump for anything you would miss.

Does this work with TimescaleDB or CockroachDB too? Yes — both speak PostgreSQL SQL and are available as separate engines, TimescaleDB and CockroachDB. The MCP config is identical apart from the connection name.

Repo contents

• examples/cursor-mcp.json — the config above, ready to copy
• examples/schema_reality_check.py — handshakes, lists tools, dumps the live table list and flags tables with no annotation
• examples/tree_inventory.sql — a municipal street-tree schema with seed data and three analytical queries
• examples/README.md — how to run both

Links

• Free PostgreSQL cloud instance
• Connecting Claude to PostgreSQL
• The engine list
• MCP specification
• PostgreSQL 16 documentation

---

freebase.cloud is an independent service and is not affiliated with Anysphere (Cursor) or the PostgreSQL Global Development Group.