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 (neonctl init)

The fastest way to get started:

npx neonctl@latest init

neonctl init (see neonctl init reference) creates a Neon API key and configures the MCP server with API key auth so you can skip OAuth when using the connection. It installs the VS Code/Cursor extension where applicable, wires Claude Code and many other assistants the wizard supports, and installs Neon's agent skills. 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.

Supported agents (add-mcp)

add-mcp is the CLI Neon uses to patch each tool’s MCP config. Use npx add-mcp list-agents for the live list from your installed version. As of the current add-mcp release, --agent values include:

Aliases: cline-vscode → cline, gemini → gemini-cli, github-copilot → vscode. Config paths differ by agent and by project vs global (-g); see the add-mcp README.

Setup options

• Quick setup: npx neonctl@latest init (MCP with API key auth, extension where supported, agent skills, and many assistants via the wizard)
• 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.

Jules

1. Create a Neon API key from your Neon Console Settings.
2. Go to jules.google.com > Settings > MCP (or use this direct link).
3. Click Connect on the Neon server and paste your API key when prompted.
4. Run a task invoking the Neon MCP server to verify the connection.

Other MCP clients

Prefer npx neonctl@latest init for the full flow (see Quick setup above). If you only want MCP config lines, or you are re-running wiring for one tool, 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 (for example, -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