Connect MCP clients to Neon

This guide covers connecting MCP clients to the Neon MCP Server for natural language interaction with your Neon Postgres databases.

Quick setup (Cursor, VS Code, Claude Code)

The fastest way to get started:

npx neonctl@latest init

This installs the MCP server for all your projects with API key-based authentication so you can skip OAuth windows. It also adds the VS Code extension for editors that support it and adds Neon's agent skills to help agents use Neon the right way. Then restart and ask your AI assistant "Get started with Neon".

If you only want the MCP server and nothing else, use:

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

This adds the MCP config to your editor's configuration files. Add -g for global (user-level) setup instead of project-level. Restart your editor (or enable the MCP server in your editor's settings); when you use the connection, an OAuth window will open to authorize. For API key authentication, add --header "Authorization: Bearer $NEON_API_KEY". For more options, see the add-mcp repository.

Setup options

• Quick Setup: Cursor, Claude Code, and VS Code support automatic setup with npx neonctl@latest init (MCP server with API key auth, VS Code extension where supported, and agent skills)
• OAuth: Connect to Neon's remote MCP server (no local installation needed)
• Local: Run the MCP server locally with your API key (requires Node.js >= v18)

For Local setup, you'll need a Neon API key.

Cursor

npx neonctl@latest init

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

Claude Code

npx neonctl@latest init

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

VS Code (with GitHub Copilot)

npx neonctl@latest init

For a detailed guide including an Azure Function REST API example, see Using Neon MCP Server with GitHub Copilot in VS Code.

ChatGPT

Connect ChatGPT to Neon using custom MCP connectors. Enable Developer mode, add the Neon connector, then enable it per chat.

1. Add MCP server to ChatGPT

   In your ChatGPT account settings, go to Settings → Connectors → Advanced Settings and enable Developer mode.

   Still on the Connectors tab, you can then create a Neon connection from the Browse connectors section. Use the following URL:

   https://mcp.neon.tech/mcp

   Make sure you choose OAuth for authentication and check "I trust this application", then complete the authorization flow when prompted.

   

   

2. Enable Neon per chat

   In each chat where you want to use Neon, click the + button and enable Developer Mode for that chat. Under Add sources, you can then enable the Neon connector you just created.

   Once connected, you can use natural language to manage your Neon databases directly in ChatGPT.

Claude Desktop

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

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

Cline (VS Code Extension)

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

Windsurf (Codeium)

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

Zed

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

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

Other MCP clients

For Cursor, VS Code, and Claude Code, use npx neonctl@latest init as the preferred setup (see Quick setup above). For other clients, or if you only want the MCP server, use add-mcp:

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

This tool auto-detects supported clients and configures them. Use -a <agent> to target a specific agent (e.g., -a cursor). Add -g for global (user-level) setup instead of project-level. For more options (including global vs project-level), see the add-mcp repository. For manual configuration, add one of these to your client's mcpServers section:

OAuth (remote server):

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

Local setup:

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

For Windows-specific configurations, see Local MCP Server.

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 OAuth (remote server)
npx -y mcp-remote https://mcp.neon.tech/mcp

# For Local setup
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 OAuth authentication and can occur after OAuth configuration changes or when cached credentials become invalid.

Next steps

Once connected, explore the available MCP tools to see what you can do with natural language.

Resources

• MCP Protocol
• Neon API Reference
• Neon API Keys
• Neon MCP server GitHub
• VS Code MCP Server Documentation