Back to Blog

How to Connect Cursor to Neon with MCP

Connect Cursor to your Neon serverless Postgres database with MCP. Use a branch for AI queries, paste one endpoint URL, get schema-aware answers in chat and Composer.

Neon gives you serverless Postgres with a branch per PR and a normal-looking connection string. Cursor is where you're writing the migrations and API code. What usually fails is the middle: the agent invents columns because it never saw the branch you're actually on.

This walkthrough connects Cursor to Neon over MCP. The parts that aren't generic Postgres: which branch you point at, pooled vs direct, and what a cold start looks like from the editor. For RDS / Railway / self-hosted, use Connect Cursor to PostgreSQL. Claude instead of Cursor? Connect Claude to Neon. New to MCP? What is an MCP server.

What you can ask once the branch is wired in

With a real Neon branch behind MCP, questions stop being schema guesses:

  • "Compare this migration to the users table on my staging branch — will it fail on existing nulls?"
  • "On the feat/billing branch, how many subscriptions rows have status = 'trialing' older than 14 days?"
  • "Our seed assumes three orgs. What's actually on this Neon branch right now?"
  • "List indexes on orders — is there anything covering (org_id, created_at)?"

Pasting a one-off psql dump into chat doesn't keep up when the branch moves.

Local MCP vs managed

You can point a local Postgres MCP server at Neon's connection string. Fine for a throwaway project on one laptop. Gets messy when that string sits in plaintext on every machine, or when half the team is on a different branch.

With Synra you paste the Neon string once, get an MCP URL, put that URL in Cursor. Credentials stay encrypted, default is read-only, queries get logged. Tradeoffs: self-hosted vs managed. Below assumes Synra.

Step 1 — Pick a branch, copy its connection string

In the Neon Console, open the project → click Connect (top right).

You'll get a string like:

postgresql://your_user:your_password@ep-cool-name-12345.us-east-2.aws.neon.tech/your_database?sslmode=require

Pick the branch in that dialog before you copy. Neon will hand you a different host/endpoint per branch. For AI access:

| Branch | Usually OK for Cursor? | |--------|-------------------------| | Staging / dev | Yes — default choice | | Feature branch from a PR | Yes — good for "does my migration match this branch" | | Production main | Only if you're careful — prefer a read replica or a branch reset from prod | | Empty new branch | Fine for smoke-testing the connector |

If you're unsure, create a branch named cursor-ai from staging, connect that, and leave production alone. Same habit as staging-first AI database access, just with Neon's branching instead of a separate host.

Copy the full string (including sslmode=require if Neon includes it).

Step 2 — Save it in Synra

  1. Sign in at mcpserver.design (7-day free trial covers getting started)
  2. Connections → Add new connection
  3. Pick Neon if you see it, otherwise PostgreSQL — Neon is Postgres under the hood either way
  4. Paste the connection string
  5. Name it after the branch (Neon staging, Neon feat/billing) so you don't mix endpoints later
  6. Test connection → Save

If the test fails on a project that was idle, wait a few seconds and try again. Neon may still be waking compute. Synra encrypts credentials at rest — Cursor never gets the password.

Step 3 — Copy the MCP endpoint

From Endpoints, copy a URL like:

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

Treat the token like a password. Anyone with that URL can read the Neon branch you connected. Rotate it from the same screen if it leaks.

Step 4 — Add it to Cursor's MCP config

Cursor reads ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project). Per-project is nicer when different repos talk to different Neon branches — still don't commit the real token.

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

Name the key after the branch. If you add a second branch later, give it a different key — Cursor lists each as its own tool source. (Leave production off this list unless you mean it.)

Older Cursor builds that don't accept "url" can use mcp-remote:

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

Skip that if your Cursor already supports remote URLs.

Step 5 — Restart and verify

Quit Cursor fully (Cmd+Q on Mac), reopen, then:

  1. Settings → MCP
  2. Confirm synra-neon-staging (or whatever you named it) is green
  3. Open tools — you should see something like list_tables, describe_table, query_table, execute_sql

In chat (Cmd+L), try:

  • "List the tables on this Neon database."
  • "Describe users — columns and types."
  • "How many rows in orders?"

If the first call hangs after a long idle, retry once. Neon cold compute is real — Synra can't warm it for you.

Neon-specific gotchas

Pooled vs direct. Pooled strings are for apps that open lots of short connections. An MCP gateway usually keeps a steadier session. If tests flake, swap to the direct (non-pooled) string for that branch in Synra and re-test.

Branch reset / recreate. Reset the branch and the data changes; the Synra endpoint URL does not. If Neon rotated the password on recreate, update the string in Synra. Leave mcp.json alone unless you regenerated the Synra endpoint itself.

Multiple branches in one Cursor window. Add two entries under mcpServers. When it matters, @-mention the right one — otherwise the agent may grab the wrong tool source.

Autoscaling lag. First query after sleep can take an extra second or two. That's Neon, not Synra. If the agent gives up, ask again once compute is up.

Security

On Synra, write SQL dies at the gateway even if Composer invents an UPDATE. Cursor only ever sees the MCP URL, not the Neon password. Queries show up in the Synra audit log.

Don't use production main for casual chat. Prefer a branch or read replica. Don't share one endpoint with people who shouldn't see each other's query history.

Troubleshooting

Green in Synra, red in Cursor. Almost always a bad mcp.json (trailing comma) or a stale URL. Validate with cat ~/.cursor/mcp.json | jq ., then recopy from Endpoints.

Test connection fails in Synra. Confirm you copied the string for the branch that's actually running. Check IP allowlists if you enabled them in Neon. Retry once after cold start.

Empty schema / wrong tables. Wrong branch — easy mistake in Neon. Fix the connection string in Synra. Don't keep editing Cursor config for this.

Agent won't use the tools. Type @ in chat and pick the MCP server once. It usually sticks after that.

FAQ

Which Neon branch should I connect? Staging or a dedicated cursor-ai branch. Production main only if you've thought about it — replica or branch-from-prod is safer.

Multiple branches at once? Yes — one Synra connection (and one mcp.json entry) per branch connection string.

Cold starts? First query after idle can be slow. Retry once.

Pooled or direct string? Start with what Neon shows under Connect. Switch to direct if the session flakes.

Composer / Agent? Same MCP tools as chat.

Can Cursor mutate Neon data? Not through Synra's default read-only gateway. Self-hosted connectors with write creds are a different story.

Branch connection string into Synra, endpoint into mcp.json, then ask something you already know the answer to and check the number.

7-day free trial at mcpserver.design — one connection is enough against a staging branch.

Related guides:

← Back to Blog