Bridge Neon

Bridge Claude Code to the Neon serverless Postgres platform for database provisioning, branching, and management through a remote MCP endpoint.

When to Use This MCP Server

Connect this server when you need to:

• Create, manage, and query Neon serverless Postgres databases directly from your Claude Code session without opening the Neon console
• Leverage Neon database branching for development workflows, creating isolated database copies for feature testing alongside your code changes
• Provision new Neon projects, configure compute endpoints, and manage connection pooling as part of your infrastructure-as-code workflow

Consider alternatives when:

• You need to connect to a self-hosted PostgreSQL instance or a non-Neon managed Postgres service, where the standard PostgreSQL MCP server is more appropriate
• Your workflow only requires running SQL queries against an existing database without needing Neon platform management features like branching or scaling

Quick Start

Configuration

Copy
name: bridge-neon
type: mcp
category: database

Example Connection

Copy
claude mcp:connect bridge-neon

Available Tools

create-project:     Provision a new Neon project with region and compute settings
list-projects:      Enumerate all Neon projects in your account with status info
create-branch:      Create a database branch from any point in time for isolated dev work
query:              Execute SQL against a specific branch or main database endpoint
manage-compute:     Scale compute endpoints up or down, configure autoscaling ranges

Core Concepts

Neon Platform Overview

Aspect	Details
Transport	Remote MCP via mcp-remote proxy connecting to https://mcp.neon.tech/mcp
Architecture	Serverless Postgres with separation of storage and compute layers
Branching	Copy-on-write database branches for dev, staging, and testing isolation
Autoscaling	Compute endpoints scale from 0.25 to 8 vCPU based on workload demand
Connection Pooling	Built-in PgBouncer-based pooling at the platform level

Neon MCP Integration Architecture

Claude Code IDE
    |
    v
[MCP Client] --npx mcp-remote--> [Neon MCP Endpoint]
                                       |
                                       v
                               [Neon Control Plane]
                                /       |        \
                          Projects  Branches  Compute
                               \       |        /
                                v      v       v
                            [Neon Storage Layer]
                            (Copy-on-Write Pages)

Configuration

Parameter	Type	Default	Description
neon_api_key	string	required	Neon API key for authenticating platform management operations
default_region	string	aws-us-east-2	Default cloud region for new project provisioning
compute_min_cu	float	0.25	Minimum compute units for autoscaling endpoints
compute_max_cu	float	4.0	Maximum compute units the autoscaler can provision
branch_timeout	integer	300	Seconds before idle branch compute endpoints are suspended

Best Practices

1. Use Branches for Every Feature - Create a Neon database branch for each feature branch in your code repository. This gives you an isolated copy of your database schema and data, allowing safe experimentation with migrations and test data without affecting the main branch.

2. Leverage Point-in-Time Branching - When debugging data issues, create branches from a specific point in time to reconstruct database state as it existed before a problematic change. This is faster and safer than restoring from backups.

3. Configure Autoscaling Conservatively - Start with low compute limits and increase them only as your workload demands. Neon scales to zero when idle, so setting a low minimum compute unit keeps development costs minimal while still providing instant availability.

4. Clean Up Development Branches - Delete database branches when their corresponding code branches are merged. Orphaned branches consume storage and can create confusion about which database states are current and relevant.

5. Use Connection Pooling for Application Code - When testing application code against Neon branches, always use the pooled connection endpoint rather than direct connections. This mirrors production behavior and prevents connection exhaustion during development testing.

Common Issues

1. Remote MCP Connection Timeout - The mcp-remote proxy may time out on first connection while establishing the secure tunnel. Retry the connection, and ensure your network allows outbound HTTPS traffic to mcp.neon.tech on port 443.

2. Branch Creation Fails with Storage Limit - Free-tier Neon accounts have a 500MB storage limit across all branches. Delete unused branches or upgrade your plan to increase the storage allocation before creating new branches.

3. SQL Query Returns Connection Error on Suspended Compute - Neon suspends idle compute endpoints to save resources. The first query after suspension may fail or take several seconds while the endpoint wakes up. Retry the query after a brief pause.