> This page location: AI > AI for Agents > MCP integration > Overview > Full Neon documentation index: https://neon.com/docs/llms.txt # Neon MCP Server overview Learn about managing your Neon projects using natural language with Neon MCP Server The **Neon MCP Server** is an open-source tool that lets you interact with your Neon Postgres databases in **natural language**: - Manage projects, branches, and databases with conversational commands - Run SQL queries and make schema changes without writing code - Use branch-based migrations for safer schema modifications ## Quick setup The fastest way to set up Neon's MCP Server is with one command: ```bash npx neonctl@latest init ``` This configures the Neon MCP Server for compatible MCP clients in your workspace (Cursor, VS Code, Claude Code, and others) using API key authentication. See the [neonctl init documentation](https://neon.com/docs/reference/cli-init). **If you only want the MCP server and nothing else**, use: ```bash npx add-mcp https://mcp.neon.tech/mcp ``` This command adds the required configuration to your editor's MCP config files; it does not open a browser by itself. 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 MCP connection, an OAuth window will open in your browser to authorize access to your Neon account. For more options (e.g., global vs project-level), see the [add-mcp repository](https://github.com/neondatabase/add-mcp). **Other setup options:** - **API key authentication (remote agents):** For remote agents or when OAuth isn't available: ```bash npx add-mcp https://mcp.neon.tech/mcp --header "Authorization: Bearer $NEON_API_KEY" ``` - **Manual configuration:** See [Connect MCP clients](https://neon.com/docs/ai/connect-mcp-clients-to-neon) for step-by-step instructions for any editor, including Windsurf, ChatGPT, Zed, and others. After setup, restart your editor and ask your AI assistant to **"Get started with Neon"** to launch the interactive onboarding guide. --- Imagine you want to create a new database. Instead of using the Neon Console or API, you could just type a request like, "Create a database named 'my-new-database'". Or, to see your projects, you might ask, "List all my Neon projects". The Neon MCP Server makes this possible. It works by acting as a bridge between natural language requests and the [Neon API](https://api-docs.neon.tech/reference/getting-started-with-neon-api). Built upon the [Model Context Protocol (MCP)](https://modelcontextprotocol.org), it translates your requests into the necessary Neon API calls, allowing you to manage everything from creating projects and branches to running queries and performing database migrations. **Important: 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. ## Other setup options Tab: Remote (OAuth) Connect to Neon's managed MCP server using OAuth. No API key configuration needed. ```bash npx add-mcp https://mcp.neon.tech/mcp ``` Or add this to your MCP config file: ```json { "mcpServers": { "neon": { "type": "http", "url": "https://mcp.neon.tech/mcp" } } } ``` **Tip: One-click install for Cursor** Add Neon MCP server to Cursor After saving, restart your MCP client. When the OAuth window opens in your browser, review the requested permissions and click **Authorize** to complete the connection. Tab: Remote (API Key) Connect using API key authentication. Useful for remote agents where OAuth isn't available. **Requires:** [Neon API key](https://neon.com/docs/manage/api-keys) ```bash npx add-mcp https://mcp.neon.tech/mcp --header "Authorization: Bearer " ``` #### MCP-only setup (OAuth): If you only want the MCP server and prefer OAuth, run: ```bash npx add-mcp https://mcp.neon.tech/mcp ``` The command adds the config to your editor; restart your editor (or enable the MCP server) for it to take effect. When you use the MCP connection, an OAuth window will open in your browser—follow the prompts to authorize. For the recommended quick setup (API key + agent skills), use `npx neonctl@latest init` instead. **Tip: Install in a single click for Cursor users** Click the button below to install the Neon MCP server in Cursor. When prompted, click **Install** within Cursor. ```json { "mcpServers": { "neon": { "type": "http", "url": "https://mcp.neon.tech/mcp", "headers": { "Authorization": "Bearer <$NEON_API_KEY>" } } } } ``` **Note:** Use an organization API key to limit access to organization projects only. #### Manual setup: 1. Go to your MCP Client's settings where you configure MCP Servers (this varies by client) 2. Register a new MCP Server. When prompted for the configuration, name the server "Neon" and add the following configuration: ```json { "mcpServers": { "Neon": { "type": "http", "url": "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. Tab: Local Run the MCP server locally on your machine. **Requires:** Node.js >= v18, [Neon API key](https://neon.com/docs/manage/api-keys) ```bash npx add-mcp "npx -y @neondatabase/mcp-server-neon start " --name neon ``` Or add this to your MCP config file: ```json { "mcpServers": { "neon": { "command": "npx", "args": ["-y", "@neondatabase/mcp-server-neon", "start", ""] } } } ``` **Note: Windows users** Use `cmd` or `wsl` if you encounter issues: ```json { "mcpServers": { "neon": { "command": "cmd", "args": ["/c", "npx", "-y", "@neondatabase/mcp-server-neon", "start", ""] } } } ``` ```json { "mcpServers": { "neon": { "command": "wsl", "args": ["npx", "-y", "@neondatabase/mcp-server-neon", "start", ""] } } } ``` ### Read-only mode The Neon MCP Server supports read-only mode for safe operation. Enable it by adding the `x-read-only: true` header: ```json { "mcpServers": { "neon": { "type": "http", "url": "https://mcp.neon.tech/mcp", "headers": { "x-read-only": "true" } } } } ``` When enabled, the server restricts all operations to read-only tools and SQL queries automatically run in read-only transactions. This provides a safe method for querying and analyzing databases without risk of accidental modifications. ### Troubleshooting If your client does not use JSON for configuration of MCP servers (such as older versions of Cursor), use this command when prompted: ```bash npx -y @neondatabase/mcp-server-neon start ``` **Note:** For clients that don't support Streamable HTTP, you can use the deprecated SSE endpoint: `https://mcp.neon.tech/sse`. SSE is not supported with API key authentication. **Important: 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.** The Neon MCP Server is intended for local development and IDE integrations only. For more information, see [MCP security guidance](https://neon.com/docs/ai/neon-mcp-server#mcp-security-guidance). ## Supported actions (tools) The Neon MCP Server provides the following actions, which are exposed as "tools" to MCP clients. You can use these tools to interact with your Neon projects and databases using natural language commands. **Project management:** - `list_projects`: Lists the first 10 Neon projects in your account, providing a summary of each project. If you can't find a specific project, increase the limit by passing a higher value to the limit parameter. - `list_shared_projects`: Lists Neon projects shared with the current user. Supports a search parameter and limiting the number of projects returned (default: 10). - `describe_project`: Fetches detailed information about a specific Neon project, including its ID, name, and associated branches and databases. - `create_project`: Creates a new Neon project in your Neon account. A project acts as a container for branches, databases, roles, and computes. - `delete_project`: Deletes an existing Neon project and all its associated resources. - `list_organizations`: Lists all organizations that the current user has access to. Optionally filter by organization name or ID using the search parameter. **Branch management:** - `create_branch`: Creates a new branch within a specified Neon project. Leverages [Neon's branching](https://neon.com/docs/introduction/branching) feature for development, testing, or migrations. - `delete_branch`: Deletes an existing branch from a Neon project. - `describe_branch`: Retrieves details about a specific branch, such as its name, ID, and parent branch. - `list_branch_computes`: Lists compute endpoints for a project or specific branch, including compute ID, type, size, last active time, and autoscaling information. - `compare_database_schema`: Shows the schema diff between the child branch and its parent. - `reset_from_parent`: Resets the current branch to its parent's state, discarding local changes. Automatically preserves to backup if branch has children, or optionally preserve on request with a custom name. **SQL query execution:** - `get_connection_string`: Returns your database connection string. - `run_sql`: Executes a single SQL query against a specified Neon database. Supports both read and write operations. - `run_sql_transaction`: Executes a series of SQL queries within a single transaction against a Neon database. - `get_database_tables`: Lists all tables within a specified Neon database. - `describe_table_schema`: Retrieves the schema definition of a specific table, detailing columns, data types, and constraints. **Database migrations (schema changes):** - `prepare_database_migration`: Initiates a database migration process. Critically, it creates a temporary branch to apply and test the migration safely before affecting the main branch. - `complete_database_migration`: Finalizes and applies a prepared database migration to the main branch. This action merges changes from the temporary migration branch and cleans up temporary resources. **Query performance optimization:** - `list_slow_queries`: Identifies performance bottlenecks by finding the slowest queries in a database. Requires the [pg_stat_statements](https://neon.com/docs/extensions/pg_stat_statements) extension; statistics accumulate as queries run, so you may need to allow time for data collection before listing. - `explain_sql_statement`: Provides detailed execution plans for SQL queries to help identify performance bottlenecks. - `prepare_query_tuning`: Analyzes query performance and suggests optimizations, like index creation. Creates a temporary branch for safely testing these optimizations. - `complete_query_tuning`: Finalizes query tuning by either applying optimizations to the main branch or discarding them. Cleans up the temporary tuning branch. **Neon Auth:** - `provision_neon_auth`: Provisions Neon Auth for a Neon project. It allows developers to easily set up authentication infrastructure by creating an integration with an Auth provider. **Neon Data API:** - `provision_neon_data_api`: Provisions the Neon Data API for a branch, enabling HTTP-based Data API access with optional JWT authentication. **Search and discovery:** - `search`: Searches across organizations, projects, and branches matching a query. Returns IDs, titles, and direct links to the Neon Console. - `fetch`: Fetches detailed information about a specific organization, project, or branch using an ID (typically from the search tool). **Documentation and resources:** - `load_resource`: Loads comprehensive Neon documentation and usage guidelines, including the "neon-get-started" guide for setup, configuration, and best practices. ## Usage examples After setup, interact with your Neon databases using natural language: - `"Get started with Neon"` — Launch the interactive onboarding guide - `"List my Neon projects"` - `"Create a project named 'my-app'"` - `"Show tables in database 'main'"` - `"Search for 'production' across my Neon resources"` - `"SELECT * FROM users LIMIT 10"` ## MCP security guidance The Neon MCP server provides powerful database tools. We recommend MCP for **development and testing only**, not production environments. - Use MCP only for local development or IDE-based workflows - Never connect MCP agents to production databases - Avoid exposing production or PII data—use anonymized data only - Always review and authorize LLM-requested actions before execution - Restrict MCP access to trusted users and regularly audit access ## Resources - [MCP Protocol](https://modelcontextprotocol.org) - [Neon API Reference](https://api-docs.neon.tech/reference/getting-started-with-neon-api) - [Neon API Keys](https://neon.com/docs/manage/api-keys#creating-api-keys) - [Neon MCP server GitHub](https://github.com/neondatabase/mcp-server-neon) --- ## Related docs (MCP integration) - [Connect MCP clients](https://neon.com/docs/ai/connect-mcp-clients-to-neon)