mcp-server-neon: driving Neon Postgres from an MCP client

A translation layer between requests and the Neon API

The Neon MCP Server is described as an open-source tool that lets you interact with your Lakebase Postgres databases on Neon in natural language.

The mechanism is stated plainly. The Model Context Protocol is a standardized protocol for managing context between large language models and external systems, and this repository provides a remote MCP Server for Neon. The server acts as a bridge between natural language requests and the Neon API, translating requests into the API calls needed to manage tasks such as creating projects and branches, running queries, and performing database migrations.

That translation is the whole value proposition, and the feature list makes the intended audience clear. Natural language interaction means managing Neon databases with conversational commands. Simplified database management means performing complex actions without writing SQL or using the Neon API directly. Accessibility for non-developers covers people who cannot write SQL. And database migration support leans on Neon's branching capability, so a schema change can be initiated through a natural language request against a branch rather than against the main database.

The examples in the README read like a session transcript. One asks to create a Postgres database called my-database and then a users table with id, name, email and password columns. Another asks for a migration on a project called my-project that alters the users table to add a created_at column. A third asks for a summary of all Neon projects and what data is in each.

Three ways to connect, and two of them need no local install

The setup section offers three options, and the difference between them is about who hosts the server and how you authenticate.

Option 1 is the quick setup with an API key, run as:

npx neon@latest init

The README describes this as the route for people who do not want to manually create an API key. It automatically configures Neon's MCP Server, the agent skills and the VS Code extension with one command, and it works with Cursor, VS Code with GitHub Copilot, and Claude Code. It authenticates via OAuth, creates a Neon API key for you, and configures the editor.

Option 2 is Neon's remote hosted server with OAuth authentication, which the README calls the easiest setup. It requires no local installation of this server and no Neon API key configured in the client, and the benefit it highlights is that you automatically receive the latest features and improvements as soon as they are released.

Option 3 is the same hosted server with API key authentication, described as useful when connecting a remote agent to Neon where OAuth is not available. It carries the same always-current advantage.

The practical difference between the three is where the code runs and whose credentials are in play. The hosted options mean Neon runs the server, and you get updates without touching your machine. The init command still results in a local configuration, but the setup work is done for you.

Category parameters decide which tools the model can call

The remote server URL carries category parameters, and that is the mechanism for controlling what the assistant is allowed to do.

The filtered URL publishes projects, branches, compute endpoints, querying and schema:

npx add-mcp "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema"

The unfiltered URL publishes every category:

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

The add-mcp command registers the server for all detected agents and editors in the workspace, and the -g flag adds it to the global MCP server list instead of the project scope.

This is a real control surface, and it is worth understanding how it works rather than assuming it. The README gives a way to preview what a URL publishes, by requesting the list-tools endpoint with the same categories, which is the quickest way to see the tool surface an assistant will be given before pointing it at a real database.

Note what is not in the default set. The published categories are projects, branches, endpoints, querying and schema, and the unfiltered URL publishes everything the server implements, which may be more than the five named ones.

Configuring the server by hand in a client file

If you would rather not use the add-mcp helper, the configuration is a small JSON object that goes into your client's MCP server configuration file, with mcp.json and mcp_config.json given as the examples.

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp?category=projects&category=branches&category=endpoints&category=querying&category=schema"
    }
  }
}

The type is http and the url is the same category-filtered endpoint, so the manual entry and the helper produce the same result.

Kiro is called out separately because its configuration path is different. The entry goes into the Kiro MCP config file, either ~/.kiro/settings/mcp.json for a global setup or .kiro/settings/mcp.json for a project-scoped one. The README also shows a Kiro badge at the top of the page for adding the server from the editor.

For the self-hosted path, this JSON is the shape to copy, with the url pointing at your own deployment of the server in this repository instead of the hosted endpoint.

Prerequisites, and two static IP addresses to allowlist

The prerequisites list is short: an MCP client application, a Neon account, and Node.js at version 18.0.0 or later.

The Node requirement is for running the server yourself, and for development the README asks for Node 22 or newer, with pnpm provided through Corepack, activated by running corepack enable. The repository uses pnpm as its package manager, pinned at pnpm 10.33.0 in the package manifest, and the lockfile is pnpm-lock.yaml.

The fourth item is the one that catches people out. If IP Allow is enabled on the Neon project, then 34.192.103.46 and 23.22.233.166 have to be added to the allowlist, and those are the static IPs for mcp.neon.tech.

That requirement only exists because the hosted server runs on Neon's side, so the connection arrives from Neon's addresses rather than from yours. A self-hosted deployment removes the constraint entirely, since the request originates from wherever you run the server. Which is a good illustration of the general shape of hosted MCP servers: the convenience comes with a fixed network footprint that your own security configuration has to accommodate.

The security warning is the part to read twice

The README carries a warning box, and it deserves to be quoted at length because it defines the acceptable use of the whole project.

The Neon MCP Server grants broad database management capabilities through natural language requests, and you should always review and authorize actions requested by the LLM before execution, ensuring that only authorized users and applications have access to the server. Then comes the boundary: the server is intended for local development and IDE integrations only, and the README does not recommend using it in production environments, because it can execute sensitive operations that may lead to accidental or unauthorized changes.

The mechanism explains the risk better than the warning does. A request to create a table, run a query or alter a schema is turned into an API call without a second look from a human in the loop unless you build one. That is what makes the tool useful and what makes it dangerous, and the difference between a development branch and a production database is the difference between a mistake you can throw away and an incident.

The README points to Neon's own MCP security guidance for the details, and the review step it asks for is the whole mitigation. If your client can be configured to require confirmation for tool calls, that setting is worth enabling before the first request.

The repository is a Next.js app with an MCP handler

Behind the hosted endpoint there is a conventional modern web application, and the layout tells you how it is built.

The package is @neondatabase/mcp-server-neon, version 1.0.0, type module, licensed MIT, authored by Neon, Inc. The runtime is Next.js 16 with React 19, and the app/ directory sits next to mcp/ where the server logic lives, with lib/ for shared code, e2e/ for end to end tests, scripts/, public/ and an ai-notes/ directory. There is a vercel.json, a next.config.ts and a postcss.config.mjs, which is what a deployment to Vercel looks like. The homepage field points at the mcp-server-neon-jet.vercel.app deployment.

The dependencies describe the server's job. The Model Context Protocol SDK is the protocol layer, @neon/sdk and @neon/tools are the Neon API clients, and mcp-handler is what serves MCP over HTTP. For authentication there is oauth2-server and openid-client, and for state there is keyv with @keyv/postgres alongside redis, which is a reasonable way to make an OAuth flow work across serverless instances. Winston handles logging, Sentry the node SDK handles errors, and @segment/analytics-node the analytics.

The test setup is unusually thorough for a project of this size. The test script chains unit, integration and end to end suites, with vitest doing the unit and integration work, a separate integration configuration with 30 second timeouts, an end to end suite against the MCP implementation, a live suite, and a web suite that runs an e2e-setup script and then playwright. Knip is wired in for unused code detection, alongside eslint, prettier and a typecheck script.

Editorial conclusion

Adopt mcp-server-neon if you want an assistant to create branches, run queries and prepare schema changes against a Neon Postgres database during development, and you are comfortable reviewing every action it proposes. Skip it if the target database is a production one, since the README says the server is intended for local development and IDE integrations only, or if your client cannot speak remote MCP over HTTP. Before the first session, decide whether to use the hosted server or run the repository yourself, and if the hosted one, decide whether to connect by OAuth or with an API key, and check whether your Neon project has IP Allow enabled, because the hosted endpoint needs 34.192.103.46 and 23.22.233.166 in the allowlist. The last push was on 2026-10-16 and the repository has no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. neondatabase/mcp-server-neon on GitHub
4. Project website
5. README