Connect MCP clients to Neon

Connect MCP clients to the Neon MCP Server to interact with your Lakebase Postgres databases in natural language.

Quick setup (neon init)

The fastest way to get started:

npx neon@latest init

neon init (see neon init reference) sets up the current directory for Neon. Run it in a terminal: it installs agent tooling (either the Neon plugin, or agent skills and the MCP server), links a Neon project, and optionally writes a neon.ts config. Then restart your editor and ask your AI assistant "Get started with Neon".

If you only want the MCP server and nothing else, run neon mcp:

neon mcp

It prompts for config location, agents, and auth, then writes the config. Pass -y to run non-interactively, or --oauth to skip minting a key. See the neon mcp reference for all flags and supported agents.

To use the lower-level add-mcp tool directly instead:

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

This writes the MCP config to your editor. Add -g for global (user-level) instead of project-level, then restart your editor. On first use, an OAuth window opens to authorize; for API key auth, add --header "Authorization: Bearer $NEON_API_KEY". See the add-mcp repository for more.

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, kilo/kilocode → kilo-code, kimi → kimi-code, kiro → kiro-cli. Config paths differ by agent and by project vs global (-g); see the add-mcp README.

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 Code

npx neon@latest init

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

Claude Desktop

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

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 MCP Server.

Cursor

npx neon@latest init

One-click install for Cursor

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

fx

fx reads MCP servers only from ~/.fx/mcp.json. A project file cannot add a server. add-mcp always writes that global file; -g is not required.

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

{
  "mcp": {
    "neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "enabled": true
    }
  }
}

/mcp auth neon --open

See fx MCP for /mcp reload, /mcp auth, /mcp list, and bearer_token_env.

Gamut

1. In your Gamut agent, go to Connections and click Add Connection.
2. Search for Neon and click + to add it.
3. When the OAuth window opens, sign in to Neon and authorize the connection.
4. Ask your agent to query or manage your Neon database to verify the connection.

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.

Kimi Code

Wire up the Neon MCP Server with add-mcp:

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

Restart Kimi Code (or run /new to start a fresh session). When the OAuth window opens, click Authorize to complete the connection.

Alternatively, install Neon's agent skills repository as a plugin. Kimi reads its own manifest (kimi.plugin.json), which declares the Neon MCP Server, so this one command wires up the MCP connection along with the skills:

/plugins install https://github.com/neondatabase/agent-skills

Plugin changes apply to new sessions, so run /new afterward. See Agent Skills for more on what's included.

Kiro

Wire up the Neon MCP Server with add-mcp:

npx add-mcp https://mcp.neon.tech/mcp -a kiro-cli

Restart Kiro (or enable the MCP server in settings). When the OAuth window opens, click Authorize to complete the connection.

For manual configuration, Kiro reads ~/.kiro/settings/mcp.json (global) or .kiro/settings/mcp.json (project). See Kiro MCP documentation.

One-click install for Kiro

VS Code (with GitHub Copilot)

npx neon@latest init

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

Windsurf (Codeium)

For more, see Get started with Windsurf and Neon 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 MCP Server.

Other MCP clients

Prefer npx neon@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 this to your client's mcpServers section:

OAuth (remote server):

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

API key:

"neon": {
  "command": "npx",
  "args": [
    "-y",
    "mcp-remote@latest",
    "https://mcp.neon.tech/mcp",
    "--header",
    "Authorization:${NEON_AUTH_HEADER}"
  ],
  "env": {
    "NEON_AUTH_HEADER": "Bearer <YOUR_NEON_API_KEY>"
  }
}

The local stdio package (@neondatabase/mcp-server-neon) is deprecated. If your client only supports stdio, use one of the mcp-remote configs above. See Deprecated local stdio.

For Windows-specific configurations, see Other MCP clients.

Troubleshooting

Configuration Issues

If your client doesn't support JSON config (such as older Cursor versions), use the stdio bridge. See Deprecated local stdio.

npx -y mcp-remote@latest https://mcp.neon.tech/mcp \
  --header "Authorization: Bearer <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

Next steps

Once connected, explore the available 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