1. Home
  2. Neon MCP Server
  3. Neon MCP Server for Windsurf: Setup & Config

Data as of

Neon MCP Server for Windsurf: Setup & Config

Windsurf: Manage Neon Postgres projects, branches, queries, and migrations through an AI assistant.

What you can do with Neon in Windsurf

Choose Neon-native branching and migrations with hosted authentication and project-scoped access.

  • Run SQL or multi-statement database transactions.
  • Limit an assistant to read-only queries in a selected project.

Before you start: Neon in Windsurf

  • A Neon account
  • An MCP-compatible client
  • Node.js 18+ for the documented command-based setup

This command registers the hosted service with detected clients; it does not launch a local server. Complete OAuth authorization, or use the documented bearer API-key configuration. Production use is not recommended.

Neon Windsurf configuration

  1. Choose Windsurf configuration scope

    For Neon MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

  2. Add Neon MCP Server to Windsurf

    Use the mcp-server-neon-neondatabase-labs entry below in mcpServers. Keep Neon MCP Server's documented http connection fields and your other Windsurf entries.

  3. Check Neon MCP Server in Windsurf

    Neon MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

JSON
{
  "mcpServers": {
    "mcp-server-neon-neondatabase-labs": {
      "serverUrl": "https://mcp.neon.tech/mcp"
    }
  }
}

Neon tools available to Windsurf

Neon's stored tool list documents 30 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

__node_version

After refreshing Neon in Windsurf settings, check Cascade's tool list for __node_version.

list_projects

After refreshing Neon in Windsurf settings, check Cascade's tool list for list_projects.

create_project

After refreshing Neon in Windsurf settings, check Cascade's tool list for create_project.

delete_project

After refreshing Neon in Windsurf settings, check Cascade's tool list for delete_project.

describe_project

After refreshing Neon in Windsurf settings, check Cascade's tool list for describe_project.

run_sql

After refreshing Neon in Windsurf settings, check Cascade's tool list for run_sql.

run_sql_transaction

After refreshing Neon in Windsurf settings, check Cascade's tool list for run_sql_transaction.

describe_table_schema

After refreshing Neon in Windsurf settings, check Cascade's tool list for describe_table_schema.

get_database_tables

After refreshing Neon in Windsurf settings, check Cascade's tool list for get_database_tables.

List tables in a Neon database.

create_branch

After refreshing Neon in Windsurf settings, check Cascade's tool list for create_branch.

Create a branch within a Neon project.

prepare_database_migration

After refreshing Neon in Windsurf settings, check Cascade's tool list for prepare_database_migration.

Prepare database schema changes using the documented migration workflow.

complete_database_migration

After refreshing Neon in Windsurf settings, check Cascade's tool list for complete_database_migration.

Finish a confirmed migration and remove its temporary branch.

describe_branch

After refreshing Neon in Windsurf settings, check Cascade's tool list for describe_branch.

Inspect a branch's databases, schemas, tables, views, and functions.

delete_branch

After refreshing Neon in Windsurf settings, check Cascade's tool list for delete_branch.

Remove a branch from a Neon project.

get_connection_string

After refreshing Neon in Windsurf settings, check Cascade's tool list for get_connection_string.

Retrieve a PostgreSQL connection string for a Neon database.

provision_neon_auth

After refreshing Neon in Windsurf settings, check Cascade's tool list for provision_neon_auth.

list_shared_projects

After refreshing Neon in Windsurf settings, check Cascade's tool list for list_shared_projects.

list_organizations

After refreshing Neon in Windsurf settings, check Cascade's tool list for list_organizations.

list_branch_computes

After refreshing Neon in Windsurf settings, check Cascade's tool list for list_branch_computes.

compare_database_schema

After refreshing Neon in Windsurf settings, check Cascade's tool list for compare_database_schema.

list_slow_queries

After refreshing Neon in Windsurf settings, check Cascade's tool list for list_slow_queries.

explain_sql_statement

After refreshing Neon in Windsurf settings, check Cascade's tool list for explain_sql_statement.

search

After refreshing Neon in Windsurf settings, check Cascade's tool list for search.

Search through the server's retrieval interface; unavailable with project scoping.

fetch

After refreshing Neon in Windsurf settings, check Cascade's tool list for fetch.

Retrieve content through the server's retrieval interface; unavailable with project scoping.

list_docs_resources

After refreshing Neon in Windsurf settings, check Cascade's tool list for list_docs_resources.

Discover available documentation resources.

get_doc_resource

After refreshing Neon in Windsurf settings, check Cascade's tool list for get_doc_resource.

Retrieve a selected documentation resource.

reset_from_parent

After refreshing Neon in Windsurf settings, check Cascade's tool list for reset_from_parent.

Reset a branch from its parent; requires write access.

provision_neon_data_api

After refreshing Neon in Windsurf settings, check Cascade's tool list for provision_neon_data_api.

Provision the Neon Data API with write-enabled access.

prepare_query_tuning

After refreshing Neon in Windsurf settings, check Cascade's tool list for prepare_query_tuning.

Prepare query tuning through a write-enabled workflow.

complete_query_tuning

After refreshing Neon in Windsurf settings, check Cascade's tool list for complete_query_tuning.

Complete the documented query-tuning workflow with write access.

Neon: full stored tool descriptions

Troubleshooting Neon in Windsurf

  • For Neon MCP Server, Windsurf reads serverUrl (mcp.neon.tech), not url. Refresh the connection and check the tools exposed to Cascade.
  • Neon MCP Server: check http connectivity to mcp.neon.tech from Windsurf; a stdio command is not a replacement for this endpoint.
  • Transport mismatch: Neon's catalog lists stdio; the displayed Windsurf configuration uses http.
  • Known limitation: The README advises against production use.
  • Known limitation: Write-enabled access includes destructive project and branch operations.
  • Known limitation: Organization projects require explicit context when using OAuth.
  • General Windsurf troubleshooting lives in the /clients/windsurf guide.

Neon MCP Server — details. Windsurf guide

Frequently asked questions

Windsurf reads Neon MCP Server under mcpServers in ~/.codeium/windsurf/mcp_config.json on macOS/Linux; Windows uses %USERPROFILE%\.codeium\windsurf\mcp_config.json.

Windsurf's mcp-server-neon-neondatabase-labs example uses http. The Neon MCP Server catalog lists stdio; these instructions follow the stored configuration instead.

Windsurf connects Neon MCP Server to mcp.neon.tech using serverUrl.

Neon MCP Server's stored list contains 30 tools, including __node_version, list_projects, create_project. Compare those names with Windsurf's connected tool list; the stored list is not a live check.

Yes. run_sql remains available but is restricted to read-only queries; write operations are disabled.

No. The README recommends development and IDE integrations and explicitly advises against production use.