How to Set Up an MCP Server for Neon Postgres

The Neon MCP server is a first-party, open-source bridge between AI agents and Neon's serverless Postgres platform. It implements the Model Context Protocol standard, so any MCP-compatible client (Claude Desktop, Cursor, VS Code with Copilot, Windsurf, Claude Code) can manage Neon databases through conversation instead of SQL.

Neon built and maintains this server directly. It is not a community wrapper or third-party integration. The repository lives at github.com/neondatabase/mcp-server-neon under an MIT license and has over 590 stars.

The server exposes tools across six categories:

• Project management: Create, list, describe, and delete Neon projects and organizations
• Branch operations: Create branches, compare schemas between parent and child, reset branches from parent
• SQL execution: Run queries, run transactions, get connection strings, list tables, describe schemas
• Database migrations: Prepare migrations on temporary branches, test them, then commit to the main branch
• Performance: List slow queries, explain query plans, tune queries with before/after comparison
• Authentication and API provisioning: Set up Neon Auth and the Neon Data API directly from your AI client

The serverless architecture simplifies the MCP connection. There is no connection pooler to configure, no persistent server to manage. Neon scales to zero when idle and wakes on demand, which means the MCP server can connect, run operations, and disconnect without worrying about idle timeouts or connection limits eating into a pool.

You need three things before starting:

1. A Neon account. Sign up at neon.com. The free tier gives you 0.5 GB of storage per project, 100 compute-unit hours per month, and up to 20 projects. No credit card required.
2. Node.js 18 or later. The MCP server runs as an npx package. Check your version with node --version.
3. An MCP-compatible client. Claude Desktop, Claude Code, Cursor, VS Code (with GitHub Copilot), Windsurf, Zed, or Cline all work.

Neon offers two authentication paths for the MCP server:

OAuth (recommended for individual developers). The remote MCP server at https://mcp.neon.tech/mcp handles authentication through your browser. No API key to manage, and you automatically get the latest server features without updating a local package.

API key (better for automation and remote agents). Generate a key in the Neon Console under Settings > API Keys. This approach works for CI pipelines, headless agents, or any environment where browser-based OAuth is not practical. You can also create organization-scoped API keys that restrict access to only that organization's projects.

Both methods give access to the full set of MCP tools. OAuth is simpler for getting started. API keys give you more control over access scope.

The fast path for any supported client is a single command:

npx neonctl@latest init

This creates a Neon API key, configures the MCP server, installs the VS Code/Cursor extension where applicable, and wires up Claude Code. It handles everything in one step.

If you prefer OAuth or want manual control, here are the client-specific instructions.

Claude Desktop

OAuth method:

npx add-mcp https://mcp.neon.tech/mcp -a claude-desktop

Restart Claude Desktop, then authorize when the browser window opens.

API key method:

npx @neondatabase/mcp-server-neon init $NEON_API_KEY

Replace $NEON_API_KEY with your actual key. This modifies your claude_desktop_config.json automatically.

Claude Code

OAuth method:

npx add-mcp https://mcp.neon.tech/mcp -a claude-code

API key method:

claude mcp add neon -- npx -y @neondatabase/mcp-server-neon start "$NEON_API_KEY"

Cursor

OAuth method:

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

API key method: Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": [
        "-y",
        "@neondatabase/mcp-server-neon",
        "start",
        "YOUR_NEON_API_KEY"
      ]
    }
  }
}

VS Code (with GitHub Copilot)

Make sure the GitHub Copilot and GitHub Copilot Chat extensions are installed. Run:

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

Then switch to Agent mode in the Copilot Chat panel. For the API key method, add the server configuration to your User Settings JSON under the mcp.servers key.

Verifying the Connection

After restarting your client, test with a simple prompt: "List my Neon projects." If the MCP server is connected, your AI client will call the list_projects tool and return your project names, IDs, and regions. If you see an error about tools not being found, double-check that Node.js 18+ is installed and that your config file syntax is valid JSON.

Give your database agent a persistent workspace

Pair Neon MCP with Fast.io for query results, reports, and migration logs that outlast the session. 50 GB free storage, MCP-ready endpoint, no credit card.

Sign Up Free

The most useful Neon MCP workflow is branch-based schema migration. Instead of running ALTER TABLE directly on your main branch, the MCP server creates a temporary branch, applies the migration there, lets you inspect the result, and only commits to the main branch after you approve.

Here is how it works in practice. Say you ask Claude: "Add a deleted_at timestamp column to the posts table."

The MCP server will:

1. Call prepare_database_migration with your SQL migration
2. Create a temporary branch from your main branch
3. Apply the migration on the temporary branch
4. Return the schema diff so you can review what changed

At this point, the main branch is untouched. You can ask your AI client to run test queries against the temporary branch, verify the schema looks right, or check that existing queries still work. When you are satisfied, tell the client to commit.

5. The client calls complete_database_migration
6. The migration is applied to the main branch
7. The temporary branch is cleaned up

This workflow is possible because Neon branches are copy-on-write. Creating a branch takes milliseconds regardless of database size since it shares storage with the parent until data diverges. That makes "branch, test, merge" cheap enough to use for every migration, not just risky ones.

The compare_database_schema tool is useful here too. It shows the schema diff between a child branch and its parent, so you can verify exactly what a migration changed before committing. If something looks wrong, delete the branch and start over. No rollback scripts needed.

You can also use reset_from_parent to sync a development branch with the latest state of your main branch, which is helpful when multiple migrations are happening in sequence.

Beyond migrations, the Neon MCP server handles day-to-day database work through natural language.

SQL execution. The run_sql tool runs arbitrary SQL against any branch in any project. Ask "Show me all users who signed up in the last 7 days" and the MCP server translates that into a query, runs it, and returns the results. The run_sql_transaction tool wraps multiple statements in a transaction for atomic operations.

Schema exploration. Before writing queries, you can ask about your database structure. get_database_tables lists all tables in a database. describe_table_schema shows columns, types, constraints, and indexes for a specific table. This is useful when you are working with a database you did not design yourself.

Query tuning. The performance tools go beyond simple EXPLAIN. The workflow is:

1. list_slow_queries identifies queries that are consuming the most time
2. explain_sql_statement shows the execution plan for a specific query
3. prepare_query_tuning creates a temporary branch and applies your proposed optimization (new index, rewritten query, etc.)
4. You compare performance between the original and optimized versions
5. complete_query_tuning applies the optimization to the main branch

This follows the same branch-test-commit pattern as migrations. The temporary branch lets you measure the impact of an index or query rewrite without touching production data.

Connection strings. The get_connection_string tool returns a ready-to-use connection string for any branch. This is handy when you need to connect an external tool or script to a specific branch for testing.

One thing to keep in mind: Neon recommends using MCP for development and testing, not production workloads. Always review the SQL your AI client generates before approving execution, especially for write operations. LLMs can produce syntactically correct but semantically wrong queries.

The Neon MCP server handles database operations well, but AI agents working with databases usually produce more than just queries. They generate reports, export CSVs, create documentation, build migration scripts, and produce analysis summaries. Those artifacts need somewhere to live between sessions.

Local filesystems work for solo development but break down when you need to share agent output with a team, hand off analysis to a client, or run agents on ephemeral infrastructure.

Cloud storage platforms like S3 or Google Drive solve the persistence problem but lack agent-native interfaces. You end up writing custom upload scripts or manually managing file organization.

Fast.io is built for this use case. It provides workspaces where agents and humans collaborate on the same files, with an MCP server that exposes workspace, storage, AI, and workflow operations. An agent can query Neon for data, generate a report, upload it to a Fast.io workspace, and share the results with a human reviewer through a branded share link.

The free agent tier includes 50 GB of storage, 5,000 monthly credits, and 5 workspaces with no credit card or trial expiration. Workspaces support Intelligence Mode, which auto-indexes uploaded files for semantic search and RAG chat. Upload a database schema doc or migration log and it becomes searchable by meaning, not just filename.

A practical workflow combining Neon MCP and Fast.io:

1. Use the Neon MCP server to run a complex analytical query
2. Export the results to CSV or a formatted report
3. Upload the report to a Fast.io workspace via the Fast.io MCP server
4. Share the workspace with stakeholders using a send link
5. Stakeholders can ask questions about the report through Intelligence Mode

Both MCP servers can run side by side in the same client. Claude Desktop, Cursor, and VS Code all support multiple MCP server configurations. You define each server in your config file and the client routes tool calls to the appropriate server automatically.

Fast.io connects via Streamable HTTP at /mcp and legacy SSE at /sse, and works with any LLM: Claude, GPT-4, Gemini, or local models. Sign up at fast.io/storage-for-agents/ to get started.