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.

The important 2026 change is that Neon now treats AI coding assistants as a first-class onboarding surface. The init command does more than install a CLI helper: it can connect supported editors to the Neon MCP Server and install Neon agent skills so the assistant has database-specific setup guidance.

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. Create a Neon API key for MCP/API-key auth
# 3. Let you choose which supported editor or assistant to configure
# 4. Install the Neon extension for Cursor or VS Code where applicable
# 5. Configure Claude Code in ~/.claude.json when selected
# 6. Install Neon agent skills at the project level

# 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. Neon's current docs describe this as a development and testing workflow, so database writes should stay behind human review until your team has its own approval policy.

Claude Code

For Claude Code, the init wizard configures the Neon MCP server in ~/.claude.json. After configuration, Claude Code can create database branches, run SQL queries, and manage schemas directly from the conversation, subject to your approval of tool actions.

// ~/.claude.json (manual API-key shape)
{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <NEON_API_KEY>"
      }
    }
  }
}

Cursor

For Cursor, the init flow installs the Neon Local Connect extension where applicable and configures MCP support. Restart Cursor after the setup, then ask the assistant to get started with Neon.

VS Code with GitHub Copilot

For VS Code, the init flow expects GitHub Copilot and Copilot Chat to be available and installs the Neon Local Connect extension where applicable. Copilot can then use the Neon MCP server for database-aware setup and operational prompts after the editor restarts.

Client Support Matrix

Neon's support surface expanded in 2026 through add-mcp. Use this matrix as the practical current routing guide, and run npx add-mcp list-agents when you need the live list for a machine.

Safety Checklist Before You Let an Agent Touch a Database

The Neon MCP Server exposes powerful project, branch, and SQL operations. Treat it like any other database admin surface: useful in development, risky without review in production.

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 from the project root, complete the MCP setup, then retrieve the connection string and store it in your app environment. For Prisma, keep a pooled URL for application traffic and a direct URL for migrations:

# .env.local (store these through your normal secret workflow)
DATABASE_URL="postgresql://user:pass@ep-cool-name-123.us-east-2.aws.neon.tech/neondb?sslmode=require"

# For Prisma, add the pooled URL for serverless
DATABASE_URL_UNPOOLED="postgresql://user:pass@ep-cool-name-123.us-east-2.aws.neon.tech/neondb?sslmode=require"
DATABASE_URL="postgresql://user:pass@ep-cool-name-123-pooler.us-east-2.aws.neon.tech/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 your assistant to propose database operations. Review the requested action before approving anything that changes schema, data, branches, or access:

• “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 natural language requests into Neon API and database operations, making routine tasks easier without forcing you to leave the editor. The convenience is the reason to use it; the review step is the reason it remains safe.

Troubleshooting

Frequently Asked Questions