Last Verified: October 2026 — commands checked against Neon’s official MCP docs
You ask Claude Code why a query is slow, and it guesses. It can’t see your tables, your indexes, or which statements actually eat the time, so you paste \d output into the chat one table at a time.
The Neon MCP server is Neon’s official hosted server. It lets Claude Code read your schema, run SQL, and run 15 built-in database health checks on your Neon Postgres. Setup is one command plus an OAuth sign-in, and one URL parameter keeps it read-only.
Already connected? Check your URL. Neon’s old /sse endpoint was retired on October 1, 2026 and now returns 410 Gone. If your config still ends in /sse, replace it with the command below.
On Supabase instead? See Supabase MCP setup.
How it works
Quick Start
Run this in your project folder:
claude mcp add --scope project --transport http neon "https://mcp.neon.tech/mcp?readonly=true"Start Claude Code, run /mcp, pick neon, and approve access in the browser. Total time: about 1 minute. No API key to paste.
⚡ Copy This Prompt: Let Claude Code Install and Verify It For You
Skip the manual steps below and hand the whole job to the agent instead:
You have shell access and the `claude mcp` CLI on my machine. Connect Neon's official MCP server to Claude Code for this project and report back. Do not tell me it's done unless step 4 actually confirms it.
1. Run `claude mcp list`. If a neon entry already exists, show me its URL and stop instead of adding a second one. If the URL ends in /sse, tell me it is retired and must be replaced.
2. Run: `claude mcp add --scope project --transport http neon "https://mcp.neon.tech/mcp?readonly=true"`
3. Tell me to run `/mcp`, pick neon, and sign in. Wait until I confirm.
4. Using only read tools, list my Neon projects with their region and branch count. Do not create, reset, or delete anything.The last step only reads, so you see what Claude can reach before it touches a branch.
On this page (8 sections)
What You’ll Need
| Requirement | Why You Need It | Time |
|---|---|---|
| Claude Code installed | The client that calls the Neon tools | 0 min |
| A Neon account with a project | The server acts on the projects your login can see | 0 min |
| A browser on the same machine | For the one-time OAuth sign-in | 0 min |
Step-by-Step Setup
Prefer to do it by hand instead of delegating to the agent? Here’s the manual version.
Step 1 — Add the server, read-only
~10 sec
?readonly=true limits Claude to SELECT queries and schema inspection. Creating branches, running migrations, and changing auth settings are switched off. --scope project writes the entry to .mcp.json, and since OAuth has no static secret, that file is safe to commit:
claude mcp add --scope project --transport http neon "https://mcp.neon.tech/mcp?readonly=true"
?readonly=true part of the URL, but .mcp.json keeps it, so check the file, not the message. Pending approval is normal for a project-scoped server: start claude, approve it, then run /mcp to sign in.Step 2 — Sign in
~30 sec
Inside Claude Code, run /mcp, select neon, and authenticate. Neon also lets you pick a read-only scope on the sign-in screen, which is a second lock on top of the URL parameter.
Step 3 — Narrow it further (optional)
~10 sec
Two more URL parameters shrink what the agent can see. Pin it to one project:
claude mcp add --scope project --transport http neon "https://mcp.neon.tech/mcp?readonly=true&projectId=YOUR_PROJECT_ID"Or load only the tool groups you use, which also saves context:
claude mcp add --scope project --transport http neon "https://mcp.neon.tech/mcp?readonly=true&category=querying&category=schema"Remove the old entry first with claude mcp remove neon. You can preview exactly which tools a URL turns on, no login needed:
curl "https://mcp.neon.tech/api/list-tools?readonly=true&category=querying"
Which URL Should You Use?
| URL Ending | What Claude Can Do | Use It When |
|---|---|---|
/mcp?readonly=true | Read schema, run SELECT, run health checks | Default for most people |
/mcp?readonly=true&projectId=… | Same, but only one project | You have client or side projects in the same account |
/mcp | Also create branches, run migrations, manage roles and compute | Dev projects where you want Claude to build schema |
/sse | Nothing, returns 410 Gone | Never, retired October 1, 2026 |
What It Can Do
| Job | Example Ask | Works Read-Only? |
|---|---|---|
| Find slow queries | “Which statements use the most total time on main? Suggest indexes.” | Yes |
| Clean up indexes | “List unused indexes and how much space each one takes” | Yes |
| Explain the schema | “Describe the orders table and every table that references it” | Yes |
| Check health | “What’s the cache hit rate, and which tables need vacuum?” | Yes |
| Try a migration safely | “Add a status column to orders on a temporary branch and show the diff” | No |
The health checks come from a tool called inspect_database. It runs the same 15 checks as neon inspect db: table and index sizes, unused indexes, sequential scans, locks, queries stuck longer than 30 seconds, heavy statements, cache hit rate, bloat, and replication. It runs inside a read-only transaction, so it works with ?readonly=true. A few checks need the pg_stat_statements extension, and Claude asks before suggesting you install it.
Verify It’s Actually Working
claude mcp list! neon Needs authentication → run
/mcp and sign in (Step 2)✘ neon Failed to connect → check the URL ends in
/mcp, not /sse
Then ask something only your account knows:
List my Neon projects and the tables in the main branch of the first one.If the table names match your database, it’s working.
Common Mistakes to Avoid
- Leaving an
/sseURL in your config. That endpoint was retired on October 1, 2026. Old tutorials still show it, and it now fails with410 Gone. - Installing the old npm package.
@neondatabase/mcp-server-neonis deprecated. Use the hosted URL. If a client only supports local servers, bridge withnpx -y mcp-remote@latest https://mcp.neon.tech/mcp. - Pointing it at production. Neon itself recommends the MCP server for development and testing only. Connect a dev project or a branch with anonymized data.
- Dropping
readonly=truewithout a guard. Full access includes deleting projects and branches. If you switch to write mode, keep manual approval on; a Claude Code hook can block delete tools outright. - Forgetting IP Allow. If your project restricts IPs, add Neon’s MCP addresses
34.192.103.46and23.22.233.166, or every query fails.
Q&A
Can I use an API key instead of OAuth, e.g. in CI?
Yes. Create a key in the Neon console under account settings, then add the server with --header "Authorization: Bearer $NEON_API_KEY". Keep the key out of .mcp.json in a shared repo; a user-scope entry is safer.
What does npx neon@latest init do?
It is Neon’s all-in-one setup: it adds the MCP server, installs Neon agent skills, and links a Neon project to your folder. npx neon@latest plugins installs just the Claude Code plugin with the server and skills. The one-line claude mcp add above is enough if you only want the tools.
Can Claude change my schema without breaking main?
With write access, yes. The SQL tools can apply a schema change on a temporary branch first, show you the result, and only then apply it to the real branch.
Does it work in Claude Desktop or claude.ai too?
Yes. Neon is an official Claude connector: Settings → Connectors → Browse connectors → Neon. That connection is separate from the one in Claude Code.
Official Resources
- Neon MCP Server overview — URL parameters, tool categories, security guidance
- neondatabase/mcp-server-neon on GitHub — source and changelog
- Claude Code MCP docs —
claude mcp add, scopes, and OAuth with/mcp
If this saved you a setup headache, follow @quickpromptco on X for the next MCP guide.