Back to Blog

How to Connect Cursor to PostgreSQL with MCP

Step-by-step guide to connecting Cursor to your PostgreSQL database using a managed MCP server. Get schema-aware code completion, real query results in chat, no local install.

You're already in Cursor. Your Postgres database is somewhere else — Neon, RDS, Railway, a Docker container on your laptop. Every time you want to ask the AI a question grounded in your real data, you're copy-pasting query results back and forth.

There's a better way. Cursor supports the Model Context Protocol (MCP), the same standard Claude Desktop uses. Wire your database in once, and Cursor's agent can read your schema, run queries, and reason about your actual production rows — inside the editor, alongside the code that uses them.

This guide gets you from zero to a working Cursor + Postgres MCP setup in a couple of minutes. (New to MCP? Read what is an MCP server first.)

What This Actually Unlocks

Once Cursor can see your Postgres database, the things you can ask change shape. A few examples that go beyond what plain context-window pasting gets you:

  • "Write a migration to add a last_login_at column to users, but only if every existing row has at least one entry in login_events. Otherwise tell me which user IDs are missing one." — Cursor inspects both tables, runs the count, and only then writes the migration.
  • "Look at the orders table. The amount column has some negative values. Write me a SQL query that lists those rows with the customer email joined in, then explain what business logic might've allowed it."
  • "Refactor this function to use the same WHERE clause our analytics dashboard uses for active users — go check what that query looks like." — works when the dashboard query lives in a queries/ folder or a stored view.
  • "This test is flaking. The seed data sets up three orgs. Compare the seed to what's actually in our staging DB — what's different?"

You stop being the translator between your AI and your data.

The Two Ways to Connect

Option 1 — Self-hosted. Install a local Postgres MCP server (the official Node package, a community Python one, whatever). Put your DATABASE_URL in a JSON config file on your machine. Restart Cursor every time the credentials change. This works for solo developers running against a local DB. It falls apart the moment you want to share access across a team, or connect to a real database whose credentials shouldn't live in a plaintext config file on every dev's laptop.

Option 2 — Managed gateway (Synra). You save your database connection string once in a secure dashboard. Synra encrypts it with AES-256, generates a personal MCP endpoint URL, and stands between Cursor and your database every time the AI asks a question. Read-only by default — no INSERT, UPDATE, DELETE, or DROP can get through, even if Cursor's agent tries. Every query is logged. No local install. No config drift.

If you want the longer comparison, the self-hosted vs managed MCP server post breaks down the tradeoffs in detail.

For most people — and especially for teams — the managed path is the right call. Here's how it goes.

Step 1 — Get Your PostgreSQL Connection String

You need a Postgres URL in the standard format:

postgresql://username:password@host:port/database

Where to find it depending on your provider:

  • Neon — Project dashboard → Connect button (top right) → copy the connection string. Works with any branch you've created.
  • Supabase — Project Settings → Database → Connection string → URI tab. Use the direct connection (port 5432) for MCP — the pooled connection on 6543 is for serverless apps.
  • Railway — Click your Postgres service → Variables → copy DATABASE_URL.
  • AWS RDS — Console → your instance → Connectivity & security → grab the endpoint, then assemble postgresql://<user>:<password>@<endpoint>:5432/<dbname> yourself.
  • Render / DigitalOcean — Database dashboard → Connection details → copy the external connection string.
  • Local Docker — Whatever you set in your docker-compose.yml, usually postgresql://postgres:postgres@localhost:5432/postgres.

Hold onto that string. You'll paste it into Synra once and never touch it again.

Step 2 — Save the Connection in Synra

  1. Sign in at mcpserver.design (free tier covers getting started)
  2. Go to Connections → Add new connection
  3. Pick PostgreSQL (or Neon / Supabase if you're using those — same backend, friendlier label)
  4. Paste your connection string
  5. Click Test connection — Synra opens a one-shot query against your database and confirms it works
  6. Click Save

Your credentials are now encrypted at rest with AES-256. The plaintext password never leaves Synra's vault.

Step 3 — Copy Your MCP Endpoint URL

After saving, head to the Endpoints tab. You'll see a URL that looks like this:

https://app.mcpserver.design/api/mcp/aB3xY7zQ9mNpLkRv2wTs

The trailing token is unique to your account and acts as the authorization. Treat it like a password — anyone with that URL can read from the database you connected. (You can rotate it from the same screen if it ever leaks.)

Copy it.

Step 4 — Add the MCP Server to Cursor

Cursor reads MCP configuration from ~/.cursor/mcp.json (global, applies to every project) or .cursor/mcp.json inside a specific project. Pick whichever fits — global is fine for personal use, per-project is better if your team checks the config into git.

Open the file (create it if it doesn't exist) and add:

{
  "mcpServers": {
    "synra-postgres": {
      "url": "https://app.mcpserver.design/api/mcp/aB3xY7zQ9mNpLkRv2wTs"
    }
  }
}

Replace the URL with your own from Step 3. Save the file.

On older Cursor versions that don't support the "url" field directly, use a stdio bridge instead:

{
  "mcpServers": {
    "synra-postgres": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.mcpserver.design/api/mcp/aB3xY7zQ9mNpLkRv2wTs"]
    }
  }
}

mcp-remote is a small published package that proxies a remote HTTP MCP server over stdio. Same effect, slightly more setup. If your Cursor is up to date, you don't need this.

Step 5 — Restart Cursor and Verify

Quit Cursor fully (Cmd+Q on Mac, not just closing the window) and reopen it. Then:

  1. Open Cursor Settings → MCP (or Features → MCP in older builds)
  2. You should see synra-postgres listed with a green status indicator
  3. Click it to see the tools it exposes — list_tables, describe_table, query_table, execute_sql

If the entry shows a red status or "no tools found", jump to the troubleshooting section below.

What to Try First

Open Cursor's chat (Cmd+L). Try one of these to confirm it's working:

  • "List the tables in my database."
  • "What does the users table look like? Show me the columns and types."
  • "How many rows are in orders?"

Cursor's agent should pick the right tool, run a query, and return real results. Once you trust it, you'll naturally start asking bigger questions — "find me the 10 customers with the most failed payments in the last week", "are there any orphaned order_items rows", "what's the average order value by month".

When you ask Cursor to write code that touches the database, it'll often check the schema first instead of guessing field names. That alone is worth the setup.

Security: What's Actually Happening

A few things worth knowing if you're connecting a real production database (you should still probably point this at a read replica, but we'll get there):

  • Read-only by default. Synra blocks every write statement at the gateway: INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, GRANT. Even if Cursor's agent generates an UPDATE, the gateway rejects it before it reaches your database. You can override this per-connection from the dashboard if you genuinely want write access, but the default is safe.
  • Credentials never reach Cursor. Cursor only ever sees the MCP endpoint URL. The actual Postgres password lives encrypted in Synra's vault. If your laptop is stolen, your DB password isn't on it.
  • Every query is logged. The audit log in your Synra dashboard shows every SQL statement that ran, who triggered it, when, and how long it took. Useful both for debugging "wait, what did the AI do" moments and for compliance.
  • The endpoint token rotates. If you accidentally commit mcp.json to a public repo (it happens), regenerate the endpoint URL from the dashboard. The old URL stops working immediately.

For production data, the standard advice still applies: connect to a read replica instead of the primary, use a dedicated database user with SELECT-only grants, and don't share the endpoint URL across people who shouldn't see each other's queries.

Troubleshooting

Cursor doesn't list synra-postgres after restart. The mcp.json file probably has a syntax error. Run cat ~/.cursor/mcp.json | jq . (or paste into jsonlint.com) to validate. The single most common mistake is a trailing comma after the URL line.

Status shows red, "Server transport closed" or similar. Open the URL from your config in a browser. You should see a JSON response (something like {"jsonrpc":"2.0","error":{...}} is normal — that just means the browser made a GET without the right MCP headers). If you instead get a 404 or a connection error, the endpoint URL is wrong — recopy it from Synra's Endpoints tab.

Tools list shows nothing, or query returns "credentials not configured". The connection in Synra is probably in a failed state. Go to Connections → click your Postgres entry → click Test connection. If the test fails, the credentials need fixing in Synra first, not in Cursor.

"SSL connection required" or similar Postgres error. Some managed Postgres providers (Neon, Heroku, Supabase) require SSL. Add ?sslmode=require to the end of your connection string in Synra and re-test. Most providers include this by default in the string they give you.

Cursor's agent refuses to use the database tools. In Cursor's chat, type @ and pick the MCP server explicitly the first time. Once it's seen the tool surface, the agent will use it automatically on subsequent prompts.

Frequently Asked Questions

Does this work with Cursor Composer / Agent mode? Yes. Composer and the autonomous agent use the same MCP tool surface as chat. Once the server is registered, every Cursor mode can use it.

Can I connect more than one database? Yes. Add additional entries under mcpServers in your mcp.json, each pointing at a different Synra endpoint URL. Cursor will list all of them as available tools.

Does Cursor's agent send my database contents to Anthropic / OpenAI? When Cursor uses the MCP tools, it sends query results back to the underlying model so it can reason over them — same as if you'd pasted them into the chat manually. If that's not acceptable for your data, don't connect production. Connect a sanitized staging copy instead.

Will this work with self-hosted Postgres behind a VPN / no public IP? Not directly — Synra needs network access to your database. Options: open an inbound rule limited to Synra's outbound IPs (contact us for the current list), or use a Postgres provider with a public TLS endpoint.

What if my Postgres needs custom CA certificates? Standard SSL works out of the box. For custom CA bundles, contact us — we'll set you up with a per-account configuration.

That's the whole thing. You should now have Cursor talking to your Postgres database with no local server to babysit. The setup takes longer to read about than to actually do.

Ready to try it? Free tier at mcpserver.design covers one database connection — plenty for exploring whether this fits your workflow.

Related guides:

← Back to Blog