Neon MCP Server overview

The Neon MCP Server implements the Model Context Protocol (MCP), letting AI assistants interact with your Neon projects on your behalf. Your AI agent can interact with Neon via MCP tools or by running Neon CLI commands directly.

Quick setup

Install the Neon MCP server into your coding agents with neon mcp:

npx neon@latest mcp

It prompts for where to write the config, which agents to install into, and how to authenticate, then writes it for you.

For agents that support plugins (such as Cursor, Claude Code, and Codex), neon plugins installs the Neon plugin, which bundles the MCP server and agent skills:

npx neon@latest plugins

To set up the MCP server together with agent skills and a linked Neon project, run neon init in a terminal:

npx neon@latest init

Config generator

Use the generator to build an MCP config for your editor and auth method, including the Authorization header for API key or remote agent setups.

npx add-mcp@latest https://mcp.neon.tech/mcp \
  --name Neon

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

Claude connector

The Neon MCP server is an official Claude connector, so you don't need a custom connector URL. To add it in Claude.ai or Claude Desktop:

1. Open Settings from your profile menu (bottom-left of the sidebar).
2. Select Connectors (sometimes shown under Customize > Connectors).
3. Click Browse connectors (top-right of that page), find Neon, and add it.
4. Authorize access to your Neon account.

For other clients, use Quick setup or the config generator above.

Access control

The Neon MCP Server supports URL parameters to restrict scope and permissions. Append them to the MCP URL (https://mcp.neon.tech/mcp).

Read-only mode

Append ?readonly=true to restrict the server to read operations:

https://mcp.neon.tech/mcp?readonly=true

SELECT queries and schema inspection remain available. Write operations (creating branches, running migrations, modifying auth config) are disabled.

With OAuth, you can also choose read-only scope during the authorization flow instead of using the URL parameter.

Project-scoped mode

Scope all operations to a single project:

https://mcp.neon.tech/mcp?projectId=<your-project-id>

Cross-project search and navigation are disabled in this mode.

Category filtering

Restrict active tools to specific categories using ?category=<name> (repeatable):

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

See Available tools for the full category list. To verify which tools are active for a given config without authenticating:

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

MCP security guidance

We recommend MCP for development and testing only, not production environments.

• Use MCP only for local development or IDE-based workflows
• Never connect MCP agents to production databases
• Avoid exposing production or PII data; use anonymized data only
• Always review and authorize LLM-requested actions before execution
• Restrict MCP access to trusted users and regularly audit access

Allowlist IP addresses

The hosted Neon MCP Server (mcp.neon.tech) connects to your Neon databases from the following static IP addresses:

• 34.192.103.46
• 23.22.233.166

If IP Allow is enabled on your project, add these addresses to your allowlist so the MCP server can connect.

Database diagnostics

When you ask why a branch is slow, large, or behind, the MCP server can run inspect_database instead of inventing catalog SQL. It exposes the same 15 read-only checks as neon inspect db: table and index sizes, unused indexes, sequential scans, long-running and stalled queries and locks, heavy and frequent statements, cache hit rate and working set, autovacuum and bloat, and replication state. The stalled-queries check reports active queries running longer than 30 seconds, with their waits, blockers, parallel workers, query IDs, and query text.

Pick a check with the check parameter (for example table-sizes or unused-indexes). The tool runs inside a read-only transaction, so it works with ?readonly=true. It belongs to the querying category, not observability. Some checks need pg_stat_statements or the neon extension; the tool reports that and asks before suggesting installation.

Troubleshooting

For per-client setup instructions, see Connect MCP clients.

Deprecated local stdio

{
  "mcpServers": {
    "Neon": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.neon.tech/mcp"]
    }
  }
}

{
  "mcpServers": {
    "Neon": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.neon.tech/mcp",
        "--header",
        "Authorization:${NEON_AUTH_HEADER}"
      ],
      "env": {
        "NEON_AUTH_HEADER": "Bearer <YOUR_NEON_API_KEY>"
      }
    }
  }
}

Deprecated HTTP+SSE transport

Resources

• MCP Protocol
• Neon API Reference
• Neon API Keys
• Neon MCP server GitHub