Neon MCP Server

About

The Neon MCP Server (neondatabase/mcp-server-neon) is Neon's official, open-source bridge between natural language and the Neon serverless Postgres platform. It translates conversational requests into Neon API and SQL calls, letting Claude, Cursor, VS Code, and other MCP clients create projects and branches, run queries, inspect schemas, and perform database migrations without hand-writing SQL or hitting the API directly. A standout capability is migration support built on Neon's branching: the server can spin up a branch, apply and test a schema change there, and only then merge it — so an assistant can safely run "add a created_at column to the users table" against an isolated copy first. The easiest setup is the remote hosted server at https://mcp.neon.tech/mcp, which supports both OAuth (no API key to manage) and API-key auth via the Authorization header; run `npx neon@latest init` for one-command configuration of Cursor, VS Code (Copilot), and Claude Code, or `npx add-mcp https://mcp.neon.tech/mcp` to register it across all detected editors. Requires Node.js 18+ and a free Neon account; if IP Allow is enabled, whitelist the mcp.neon.tech static IPs. Neon explicitly scopes this server to local development and IDE workflows — its README warns against production use since natural-language commands can execute powerful, irreversible database operations, so always review actions before authorizing them.

Installation

npx add-mcp https://mcp.neon.tech/mcp

Connecting the Neon MCP server

1. 1.One command, if your editor is Cursor, VS Code or Claude Code

   neon init authenticates over OAuth, mints an API key for you, and writes the MCP config plus Neon's agent skills and the VS Code extension. It is the fastest path and the one to use unless you need a specific scoped URL.

   shell

   npx neon@latest init

2. 2.Or register the hosted server everywhere at once

   add-mcp detects the agents and editors in the workspace and adds the entry to each. It is project-scoped by default; add -g to write it to the global MCP server list instead. On first connect a browser window opens for the OAuth grant.

   shell

   npx add-mcp https://mcp.neon.tech/mcp

3. 3.Or write the config by hand

   Streamable HTTP, so there is no command and no args. Any client that speaks it takes this verbatim.

   json

   {
     "mcpServers": {
       "Neon": {
         "type": "http",
         "url": "https://mcp.neon.tech/mcp"
       }
     }
   }

4. 4.Constrain it in the URL before you connect anything real

   readonly=true removes the write tools and leaves run_sql available for read-only queries. projectId confines every operation to one project — and note that in project-scoped mode the docs-search tools search and fetch become unavailable. Config in the URL travels with each request and takes effect immediately, with no re-auth.

   url

   https://mcp.neon.tech/mcp?readonly=true&projectId=proj-123

5. 5.Cut the tool list with category=

   category takes repeated params or a CSV, drawn from projects, branches, schema, querying, neon_auth, data_api, observability and docs. Dropping to two categories is the cheapest way to shrink both the risk and the tokens the tool list costs on every turn.

   url

   https://mcp.neon.tech/mcp?category=querying&category=schema

6. 6.Check what a URL actually exposes before you trust it

   The server will tell you which tools a given configuration yields, without authenticating. Worth running once after you write a scoped URL, rather than assuming the params did what you meant.

   shell

   curl "https://mcp.neon.tech/api/list-tools?readonly=true&category=querying"

7. 7.API-key auth, where no browser exists

   Create the key in the Neon Console and pass it as a bearer header. Use an organization key to confine access to that organization's projects. In this flow there is no OAuth scope exchange, so readonly=true in the URL is the only way to get read-only mode.

   shell

   npx add-mcp https://mcp.neon.tech/mcp \
     --header "Authorization: Bearer <$NEON_API_KEY>"

Tool categories

Roughly thirty tools, grouped by the scope category used for filtering and for the OAuth consent screen.

What people use it for

Which one should you use?

Categories

Works With

Frequently Asked Questions

Related Guides