npx neonctl@latest init: Set Up Neon Serverless Postgres with MCP Integration

What Is Neon and neonctl

Neon is an open-source serverless Postgres platform that separates storage and compute. This architecture enables three features that traditional Postgres hosting cannot match: instant database branching (copy-on-write, under 1 second), autoscaling to zero (no charges when idle), and built-in connection pooling (up to 10,000 pooled connections per project via PgBouncer).

neonctl is Neon's official CLI tool. It provides terminal access to the same operations available in the Neon dashboard and API: managing projects, creating branches, provisioning databases, and configuring roles. The init subcommand is a guided setup wizard that handles authentication, project selection, and optionally configures MCP Server integration for AI assistants.

After Neon was acquired by Databricks in May 2025, pricing improved significantly: compute costs dropped 15-25% and storage costs fell approximately 80% (now $0.35/GB-month). The free tier includes 0.5 GB storage and 190 compute hours per month — enough for most development and side project workloads.

How to Run npx neonctl@latest init

Run this command from your project root directory. The init wizard is interactive and walks you through each step. Here is the complete sequence:

Prerequisites

• Node.js 18+ installed
• A Neon account (free tier works — sign up at neon.tech)
• A project directory where you want to add Neon

Step-by-Step Setup

# Step 1: Run the init command
npx neonctl@latest init

# The wizard will:
# 1. Open your browser for OAuth authentication
# 2. Ask you to select or create a Neon project
# 3. Generate an API key for this session
# 4. Write connection string to .env
# 5. Offer to configure MCP for your AI assistant

# Step 2: Verify your connection
npx neonctl@latest connection-string

# Step 3: Test with psql (optional)
psql "$(npx neonctl@latest connection-string --pooled)"

# Step 4: Check project status
npx neonctl@latest projects list --output json

The --pooled flag returns the connection string with PgBouncer pooling enabled (port 5432 with the -pooler hostname suffix). Use pooled connections for serverless applications (Next.js API routes, Vercel functions, Cloudflare Workers) and direct connections for long-running processes like migration scripts.

MCP Server Configuration for AI Assistants

One of neonctl init's most useful features is automatic MCP (Model Context Protocol) Server setup. This lets AI coding assistants directly query, create branches, and manage your Neon database through natural language. The init wizard detects which assistants you have installed and offers to configure them.

Claude Code

For Claude Code (Anthropic's CLI), the init wizard adds the Neon MCP server to yourclaude_desktop_config.json. After configuration, Claude Code can create database branches, run SQL queries, and manage schemas directly from the conversation.

// claude_desktop_config.json (auto-generated)
{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": ["-y", "@neondatabase/mcp-server-neon"],
      "env": {
        "NEON_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

For Cursor, configuration goes to .cursor/mcp.json in your project root. This enables Cursor's AI to manage Neon operations within your workspace context.

VS Code with GitHub Copilot

For VS Code, the MCP config is written to .vscode/mcp.json. GitHub Copilot can then use the Neon MCP server for database-aware code suggestions and direct SQL execution.

Database Branching Workflow

Neon branching is the feature that separates it from every other managed Postgres service. A branch is an instant, copy-on-write clone of your database — it shares storage with the parent until data diverges. Creating a branch takes under 1 second regardless of database size.

Common Branching Commands

# Create a branch for your PR
npx neonctl@latest branches create --name "feature/user-auth"

# List all branches
npx neonctl@latest branches list --output table

# Get connection string for a specific branch
npx neonctl@latest connection-string --branch "feature/user-auth"

# Delete a branch when PR is merged
npx neonctl@latest branches delete "feature/user-auth"

# Reset a branch to parent state
npx neonctl@latest branches reset "feature/user-auth" --parent

Per-PR Branch Strategy

The most powerful pattern is creating a database branch for every pull request. Each PR gets its own isolated Postgres instance with real data (copied from main). Developers can run migrations, test schema changes, and seed test data without affecting other branches. When the PR merges, delete the branch.

# GitHub Actions: Create branch on PR open
- name: Create Neon branch
  run: |
    npx neonctl@latest branches create \
      --name "pr-${GITHUB_PR_NUMBER}" \
      --api-key ${NEON_API_KEY}

# GitHub Actions: Delete branch on PR close
- name: Cleanup Neon branch
  run: |
    npx neonctl@latest branches delete "pr-${GITHUB_PR_NUMBER}" \
      --api-key ${NEON_API_KEY}

Worked Examples

Example 1: Next.js App with Prisma + Neon

You have a Next.js project and want serverless Postgres. Run npx neonctl@latest init, select your project, and the wizard writes your DATABASE_URL to .env. Then configure Prisma:

# .env (auto-generated by neonctl init)
DATABASE_URL="postgresql://user:[email protected]/neondb?sslmode=require"

# For Prisma, add the pooled URL for serverless
DATABASE_URL_UNPOOLED="postgresql://user:[email protected]/neondb?sslmode=require"
DATABASE_URL="postgresql://user:[email protected]/neondb?sslmode=require"

The pooled URL goes through PgBouncer and handles connection limits for serverless functions. The unpooled URL is for migrations (prisma migrate deploy) which need direct connections.

Example 2: CI Pipeline with Ephemeral Branches

Your team runs integration tests against a real database. Instead of a shared staging DB, each CI run creates a Neon branch, runs migrations and tests, then deletes the branch:

# CI script
BRANCH_NAME="ci-run-$GITHUB_RUN_ID"

# Create isolated branch (instant, ~1 second)
npx neonctl@latest branches create --name "$BRANCH_NAME"

# Get connection string
export DATABASE_URL=$(npx neonctl@latest connection-string --branch "$BRANCH_NAME" --pooled)

# Run migrations and tests
npm run db:migrate
npm test

# Cleanup
npx neonctl@latest branches delete "$BRANCH_NAME"

Example 3: MCP-Powered Database Management

After configuring MCP via init, you can ask Claude Code to manage your database directly:

• “Create a new branch called staging-v2 from main”
• “Run this SQL on the staging branch: ALTER TABLE users ADD COLUMN avatar_url TEXT”
• “Show me the schema of the orders table”
• “Delete all branches older than 7 days”

The MCP server translates these natural language requests into neonctl API calls, making database operations accessible without leaving your editor.

Troubleshooting

Frequently Asked Questions