New to Neon? Follow these best practices to get top performance in production
Neon DocsAsk Neon AI
Discord19.5k
Log InSign Up
/AI for agents/Connect MCP Clients

Connect MCP Clients to Neon

Learn how to connect MCP clients such as Cursor, Claude Desktop, Cline, Windsurf, Zed, and VS Code to your Neon Postgres database.

The Neon MCP Server allows you to connect various Model Context Protocol (MCP) compatible AI tools to your Neon Postgres databases. This guide provides instructions for connecting popular MCP clients to the Neon MCP Server, enabling natural language interaction with your Neon projects.

This guide covers the setup for the following MCP Clients:

By connecting these tools to the Neon MCP Server, you can manage your Neon projects, databases, and schemas using natural language commands within the MCP client interface.

Neon MCP Server Security Considerations

The Neon MCP Server grants powerful database management capabilities through natural language requests. Always review and authorize actions requested by the LLM before execution. Ensure that only authorized users and applications have access to the Neon MCP Server.

The Neon MCP Server is intended for local development and IDE integrations only. We do not recommend using the Neon MCP Server in production environments. It can execute powerful operations that may lead to accidental or unauthorized changes.

For more information, see MCP security guidance →.

Prerequisites

For Local MCP Server setup, you also need a Neon API key. See Neon API Keys documentation.

note

Ensure you are using the latest version of your chosen MCP client as MCP integration may not be available in older versions. If you are using an older version, update your MCP client to the latest version.

Connect to Neon MCP Server

You can connect to Neon MCP Server in two ways:

  1. Remote MCP Server (Preview): Connect to Neon's managed remote MCP server using OAuth or a Neon API key.
  2. Local MCP Server: Install and run the Neon MCP server locally, using a Neon API key.

Claude Desktop

  1. Open Claude desktop and navigate to Settings.

  2. Under the Developer tab, click Edit Config (On Windows, it's under File -> Settings -> Developer -> Edit Config) to open the configuration file (claude_desktop_config.json).

  3. Add the "Neon" server entry within the mcpServers object:

    {
  "mcpServers": {
    "Neon": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.neon.tech/mcp"]
    }
  }
}

    To use SSE instead of streamable HTTP responses, you can specify the https://mcp.neon.tech/sse endpoint instead of https://mcp.neon.tech/mcp.

  4. Save the configuration file and restart Claude Desktop.

  5. An OAuth window will open in your browser. Follow the prompts to authorize Claude Desktop to access your Neon account.

By default, the Remote MCP Server connects to your personal Neon account. To connect to an organization's account, you must authenticate with an API key. For more information, see API key-based authentication.

For more, see Get started with Neon MCP server with Claude Desktop.

Claude Code

  1. Ensure you have Claude Code installed. Visit docs.anthropic.com/en/docs/claude-code for installation instructions.
  2. Open terminal and add Neon MCP with 
    claude mcp add --transport http neon https://mcp.neon.tech/mcp
  3. Start a new session of claude to trigger OAuth authentication flow
  4. You can also trigger authentication with /mcp within Claude Code.

If you prefer to authenticate using a Neon API key, provide Authorization header to mcp add command:

claude mcp add --transport http neon https://mcp.neon.tech/mcp \
    --header "Authorization: Bearer <YOUR_NEON_API_KEY>"

Replace <YOUR_NEON_API_KEY> with your actual Neon API key which you obtained from the prerequisites section

Cursor

Click the button below to install the Neon MCP server in Cursor. When prompted, click Install within Cursor.

Add Neon MCP server to Cursor

Manual Setup

  1. Open Cursor. Create a .cursor directory in your project root if needed.

  2. Create or open the mcp.json file in the .cursor directory.

  3. Add the "Neon" server entry within the mcpServers object:

    {
  "mcpServers": {
    "Neon": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.neon.tech/mcp"]
    }
  }
}

    To use SSE instead of streamable HTTP responses, you can specify the https://mcp.neon.tech/sse endpoint instead of https://mcp.neon.tech/mcp.

  4. Save the configuration file. Cursor may detect the change or require a restart.

  5. An OAuth window will open in your browser. Follow the prompts to authorize Cursor to access your Neon account.

By default, the Remote MCP Server connects to your personal Neon account. To connect to an organization's account, you must authenticate with an API key. For more information, see API key-based authentication.

For more, see Get started with Cursor and Neon Postgres MCP Server.

Windsurf (Codeium)

  1. Open Windsurf and navigate to the Cascade assistant sidebar.

  2. Click the hammer (MCP) icon, then Configure which opens up the "Manage MCPs" configuration file.

  3. Click on "View raw config" to open the raw configuration file in Windsurf.

  4. Add the "Neon" server entry within the mcpServers object:

    {
  "mcpServers": {
    "Neon": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.neon.tech/mcp"]
    }
  }
}

    To use SSE instead of streamable HTTP responses, you can specify the https://mcp.neon.tech/sse endpoint instead of https://mcp.neon.tech/mcp.

  5. Save the file.

  6. Click the Refresh button in the Cascade sidebar next to "available MCP servers".

  7. An OAuth window will open in your browser. Follow the prompts to authorize Windsurf to access your Neon account.

By default, the Remote MCP Server connects to your personal Neon account. To connect to an organization's account, you must authenticate with an API key. For more information, see API key-based authentication.

For more, see Get started with Windsurf and Neon Postgres MCP Server.

Cline (VS Code Extension)

  1. Open Cline in VS Code (Sidebar -> Cline icon).
  2. Click MCP Servers Icon -> Installed -> Configure MCP Servers to open the configuration file.
  3. Add the "Neon" server entry within the mcpServers object: 
    {
  "mcpServers": {
    "Neon": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.neon.tech/sse"]
    }
  }
}

For streamable HTTP responses instead of SSE, you can specify the https://mcp.neon.tech/mcp endpoint instead of https://mcp.neon.tech/sse.

  1. Save the file. Cline should reload the configuration automatically.
  2. An OAuth window will open in your browser. Follow the prompts to authorize Cline to access your Neon account.

By default, the Remote MCP Server connects to your personal Neon account. To connect to an organization's account, you must authenticate with an API key. For more information, see API key-based authentication.

For more, see Get started with Cline and Neon Postgres MCP Server.

Zed

note

MCP support in Zed is currently in preview. Ensure you're using the Preview version of Zed to add MCP servers (called Context Servers in Zed). Download the preview version from zed.dev/releases/preview.

  1. Open the Zed Preview application.

  2. Click the Assistant (✨) icon in the bottom right corner.

  3. Click Settings in the top right panel of the Assistant.

  4. In the Context Servers section, click + Add Context Server.

  5. Configure the Neon Server:

    • Enter Neon in the Name field.

    • In the Command field, enter:

      npx -y mcp-remote https://mcp.neon.tech/sse

    • Click Add Server.

    For streamable HTTP responses instead of SSE, you can specify the https://mcp.neon.tech/mcp endpoint instead of https://mcp.neon.tech/sse.

  6. An OAuth window will open in your browser. Follow the prompts to authorize Zed to access your Neon account.

  7. Check the Context Servers section in Zed settings to ensure the connection is successful. "Neon" should be listed.

By default, the Remote MCP Server connects to your personal Neon account. To connect to an organization's account, you must authenticate with an API key. For more information, see API key-based authentication.

For more details, including workflow examples and troubleshooting, see Get started with Zed and Neon Postgres MCP Server.

VS Code (with GitHub Copilot)

note

To use MCP servers with VS Code, you need GitHub Copilot and GitHub Copilot Chat extensions installed

  1. Open VS Code.

  2. Create a .vscode folder in your project's root directory if it doesn't exist.

  3. Create or open the mcp.json file in the .vscode directory and add the following configuration into the file (if you have other MCP servers configured, add the "Neon" server entry within the servers object):

    {
  "servers": {
    "Neon": {
      "url": "https://mcp.neon.tech/mcp",
      "type": "http"
    }
  },
  "inputs": []
}

    For streamable HTTP responses instead of SSE, you can specify the https://mcp.neon.tech/mcp endpoint instead of https://mcp.neon.tech/sse.

  4. Save the mcp.json file.

  5. Click on Start on the MCP server.

  6. An OAuth window will open in your browser. Follow the prompts to authorize VS Code (GitHub Copilot) to access your Neon account.

  7. Once authorized, you can now open GitHub Copilot Chat in VS Code and switch to Agent mode. You will see the Neon MCP Server listed among the available tools.

By default, the Remote MCP Server connects to your personal Neon account. To connect to an organization's account, you must authenticate with an API key. For more information, see API key-based authentication.

For detailed instructions on utilizing the Neon MCP server with GitHub Copilot in VS Code, including a step-by-step example on generating an Azure Function REST API, refer to How to Use Neon MCP Server with GitHub Copilot in VS Code.

Other MCP clients

Adapt the instructions above for other clients:

  • Remote MCP server: Add the following JSON configuration within the mcpServers section of your client's MCP configuration file:

    By default, the Remote MCP Server connects to your personal Neon account. To connect to an organization's account, you must authenticate with an API key. If your client supports it, provide the key in the Authorization header. For more information, see API key-based authentication.

    "neon": {
  "command": "npx",
  "args": ["-y", "mcp-remote@latest", "https://mcp.neon.tech/mcp"]
}

    MCP supports two remote server transports: the deprecated Server-Sent Events (SSE) and the newer, recommended Streamable HTTP. If your LLM client doesn't support Streamable HTTP yet, you can switch the endpoint from https://mcp.neon.tech/mcp to https://mcp.neon.tech/sse to use SSE instead.

    Then follow the OAuth flow on first connection.

  • Local MCP server:

    Add the following JSON configuration within the mcpServers section of your client's MCP configuration file, replacing <YOUR_NEON_API_KEY> with your actual Neon API key obtained from the prerequisites section:

    For MacOS and Linux, add the following JSON configuration within the mcpServers section of your client's mcp_config file, replacing <YOUR_NEON_API_KEY> with your actual Neon API key:

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

    note

    After successful configuration, you should see the Neon MCP Server listed as active in your MCP client's settings or tool list. You can enter "List my Neon projects" in the MCP client to see your Neon projects and verify the connection.

Troubleshooting

Configuration Issues

If your client does not use JSON for configuration of MCP servers (such as older versions of Cursor), you can use the following command when prompted:

# For Remote MCP server
npx -y mcp-remote https://mcp.neon.tech/mcp

# For Local MCP server
npx -y @neondatabase/mcp-server-neon start <YOUR_NEON_API_KEY>

OAuth Authentication Errors

When using the remote MCP server with OAuth authentication, you might encounter the following error:

{"code":"invalid_request","error":"invalid redirect uri"}

This typically occurs when there are issues with cached OAuth credentials. To resolve this:

  1. Remove the MCP authentication cache directory: 
    rm -rf ~/.mcp-auth
  2. Restart your MCP client application
  3. The OAuth flow will start fresh, allowing you to properly authenticate

This error is most common when using the remote MCP server option and can occur after OAuth configuration changes or when cached credentials become invalid.

Next steps

Once connected, you can start interacting with your Neon Postgres databases using natural language commands within your chosen MCP client. Explore the Supported Actions (Tools) of the Neon MCP Server to understand the available functionalities.

Resources

Need help?

Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.

PreviousNeon MCP ServerNextAI rules

Last updated on

Was this page helpful?

On this page

Edit this page on GitHubOpen in ChatGPT