Get started with Zed and Neon Postgres MCP Server

Imagine you could interact with your database using plain English, whether you're asking for specific data or changing its schema. That's what the Neon MCP Server allows you to do. It lets you manage your Neon Postgres databases using everyday language, simplifying tasks like running queries and performing database migrations.

In this guide, we'll explore how to set up the Neon MCP Server within Zed, a next-generation AI-powered code editor, to handle various database operations. These include creating projects, managing database branches, running SQL queries, and performing safe database migrations.

Setting up Neon MCP Server in Zed

You have two options for connecting Zed to the Neon MCP Server:

1. Remote MCP Server (Preview): Connect to Neon's managed MCP server using OAuth for authentication. This method is more convenient as it eliminates the need to manage API keys in Zed. Additionally, you will automatically receive the latest features and improvements as soon as they are released.

2. Local MCP Server: Run the Neon MCP server locally on your machine, authenticating with a Neon API key.

Prerequisites

Before you begin, ensure you have the following:

1. Zed editor: Download and install preview version of Zed from zed.dev/releases/preview.

2. A Neon account and project: You'll need a Neon account and a project. You can quickly create a new Neon project here pg.new

3. Neon API Key (for Local MCP server): After signing up, get your Neon API Key from the Neon console. This API key is needed to authenticate your application with Neon. For instructions, see Manage API keys.

   Neon API Key Security

   Keep your Neon API key secure, and never share it publicly. It provides access to your Neon projects.

4. Node.js (>= v18) and npm: Ensure Node.js (version 18 or later) and npm are installed. Download them from nodejs.org.

Option 1: Setting up the Remote Hosted Neon MCP Server

This method uses Neon's managed server and OAuth authentication.

1. Open Zed.

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

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

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

5. Configure 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.

6. An OAuth window will open. 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 as a context server.

8. Zed is now connected to Neon's remote MCP server.

Option 2: Setting up the Local Neon MCP Server

This method runs the Neon MCP server locally on your machine, using a Neon API key for authentication.

1. Open Zed.

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

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

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

5. Configure Neon Server:

   • Enter Neon in the Name field.
   • In the Command field, enter:

     npx -y @neondatabase/mcp-server-neon start <YOUR_NEON_API_KEY>

     
   • Click Add Server.

6. Check the Context Servers section in Zed Settings to ensure the connection is successful. Neon should be listed as a context server.

7. Zed is now connected to Neon's local MCP server.

Verification

With the Neon MCP server set up either remotely or locally, you can now verify the connection and test the available tools.

1. Open Zed Assistant.

2. Type List my Neon projects in the Assistant text field.

3. When prompted, click Allow to authorize the tool to access your Neon project.

4. Zed will use the list_projects MCP tool to retrieve and display your Neon projects, including project ID, name, and other details.

5. Try other commands such as listing all tables, creating a new branch, creating a new project, or running SQL queries.

Troubleshooting

If you experience issues adding an MCP server from the Assistant panel, you can also do so through the Settings. Follow these steps:

1. Open the ~/.config/zed/settings.json file. You can access this file by clicking on Settings in the Zed menu bar.
2. Add the following context_servers section to the file.

"context_servers": {
   "neon": {
      "command": {
         "path": "npx",
         "args": ["-y", "mcp-remote", "https://mcp.neon.tech/sse"],
         "env": null
      },
      "settings": {}
   }
}

Troubleshooting on Windows

If you are using Windows, and you encounter issues with the command line, you may need to adjust the command to use cmd or wsl to run the MCP server. For example, here's how you can set it up:

"context_servers": {
   "neon": {
      "command": {
         "path": "cmd",
         "args": ["/c", "npx", "-y", "@neondatabase/mcp-server-neon", "start", "<YOUR_NEON_API_KEY>"],
         "env": null
      },
      "settings": {}
   }
}

Neon MCP Server Tools

Neon MCP server exposes the following actions, which primarily map to Neon API endpoints:

• list_projects: Lists all your Neon projects. This uses the Neon API to retrieve a summary of all projects associated with your Neon account.
• describe_project: Retrieves detailed information about a specific Neon project. Provides comprehensive details about a chosen project, such as its ID, name, and associated branches.
• create_project: Creates a new Neon project — a container in Neon for branches, databases, roles, and computes.
• delete_project: Deletes an existing Neon project.
• create_branch: Creates a new branch within a Neon project. Leverages Neon's branching feature, allowing you to create new branches for development or migrations.
• delete_branch: Deletes an existing branch in a Neon project.
• describe_branch: Retrieves details about a specific branch. Retrieves information about a particular branch, such as its name and ID.
• get_connection_string: Retrieves a connection string for a specific database in a Neon project. Returns a formatted connection string that can be used to connect to the database.
• run_sql: Runs a single SQL query against a Neon database. Allows you to run read or write SQL queries.
• run_sql_transaction: Runs a series of SQL queries within a transaction against a Neon database. Enables running multiple SQL statements as a single atomic transaction, ensuring data consistency.
• get_database_tables: Lists all tables in a specified Neon database. Provides a list of tables.
• describe_table_schema: Retrieves the schema definition of a specific table. Details the structure of a table, including columns and data types.
• prepare_database_migration: Initiates a database migration process, utilizing a temporary branch for safety. Begins the process of altering your database schema, safely using Neon's branching feature.
• complete_database_migration: Completes a migration process, applying changes to your main database and cleaning up temporary resources.

These actions enable any MCP client like Zed to interact with various functionalities of the Neon platform via the Neon API. Certain tools, especially database migration ones, are tailored for AI agent and LLM usage, leveraging Neon’s branching for safe preview and commit.

Development Workflow: Adding a Column with Zed and Neon MCP

Let's walk through a typical development scenario: Quickly adding a column for prototyping using natural language within Zed. The following chat log demonstrates a real interaction with Zed and the Neon MCP server.

Scenario: During development, you decide to track timestamps for entries in your playing_with_neon table. You want to quickly add a created_at column.

Here's the conversation log between the user and Zed:

User: List my neon projects
Zed: I'll use the list_projects tool to show your Neon projects.
> Run MCP tool `list_projects`
> You have one Neon project:
> Name: mcp
> Project ID: red-math-82356803
> Region: aws-ap-southeast-1
> ...other details...

User: what tables are present in it?
Zed: I'll use the `get_database_tables` tool to list the tables in your project. I'll use the project ID we just found.
> Run MCP tool `get_database_tables`
> There is one table in your project's database:
> Schema: public
> Table Name: `playing_with_neon`
> Type: Base Table
> Let me fetch the details of this table's schema so you can see its structure:
> Run MCP tool `describe_table_schema`
> The "playing_with_neon" table has three columns:
> 1. id: An auto-incrementing integer (primary key)
> 2. value: A real (floating-point) number that can be null
> 3. name: A text field that cannot be null

Would you like to see the data in this table or perform any operations on it?

User: Can you show me first 5 rows in it?
Zed: I'll query the first 5 rows from the playing_with_neon table:
> Run MCP tool `run_sql`
> xxx (table rows are returned by Zed)

User: can you add a created_at column to the table?
Zed: I'll use the prepare_database_migration tool to add a created_at column to the playing_with_neon table:
> Run MCP tool `prepare_database_migration`
> I've added the `created_at` column in a temporary branch. Let me verify the change by checking the table structure:
> Run MCP tool `run_sql`
> I've verified that the created_at column has been successfully added in the temporary branch.
> Migration Details:
> - Migration ID: a78e2a3b-8498-48a0-9c7a-2dec30da84bc
> - Temporary Branch Name: br-royal-mode-a1nfvzag
> - Temporary Branch ID: br-royal-mode-a1nfvzag
> - Migration Result: Success
> Would you like to commit this migration to the main branch?

User: yes do it
Zed: I'll complete the migration using the provided migration ID:
> Run MCP tool `complete_database_migration`
> The migration has been successfully completed. The `created_at` column has been added to the `playing_with_neon` table in the main branch, and the temporary branch has been deleted.

Key takeaways:

• Natural language interaction: You can use simple, conversational English to interact with your database.
• Step-by-step guidance: Zed (Claude) confirms each step and provides details like branch names and migration IDs.
• MCP Tools in action: The underlying MCP tools (get_database_tables, run_sql, prepare_database_migration, complete_database_migration) illustrate the automated process.
• Branching for safety: The agent automatically creates a temporary branch for schema changes. The user will be prompted to confirm the migration before applying it to the main branch.

You can verify the changes in your Neon Console or by querying the database directly.

Bonus: Creating a project and branch

Beyond schema changes, you can also manage your Neon projects and branches directly within Zed using natural language commands. This can be useful for quickly setting up a new development or test environment.

Creating a new project

Let's say you want to create a new Neon project named "my-new-project". You can simply tell Zed:

User: Create a Neon project named "my-new-project"
Zed: I'll create a new Neon project with the specified name.
> Run MCP tool `create_project`
> I've successfully created a new Neon project named "my-new-project". Here are the key details:
> - Project ID: red-frog-93550744
> - Default Branch: main (ID: br-shiny-water-a5us05x3)
> - Default Database: neondb
> The project is ready to use. You can now create tables, add data, or perform other database operations. Would you like to perform any specific operations with your new project?

Zed will then use the create_project MCP tool to initiate the project creation. It will provide you with a project ID, default branch, and database details. You can then proceed to create tables or perform other operations within this project.

Creating a New Branch

Once you have a project, you can easily create new branches for development or experimentation. For example, to create a branch named "feature-x" in your "my-new-project" project:

User: Create a branch named "feature-x"
Zed: I'll create a new branch named "feature-x" in your project.
> Run MCP tool `create_branch`
> I've successfully created a new branch named "feature-x" in your project. Here are the details:
> - Branch Name: feature-x
> - Branch ID: br-gentle-dream-a5u9fmm4
> - Parent Branch: br-shiny-water-a5us05x3
> The branch is ready for use. Would you like to perform any specific operations in this branch?

Zed will use the create_branch MCP tool to create the branch and provide you with the branch name and ID. Notice how we don't need to specify the project ID, as Zed remembers the active project context.

Conclusion

Zed combined with the Neon MCP Server, whether using the Remote Hosted (Preview) option or the Local Server setup, lets you use natural language to interact with your database and take advantage of Neon's branching capabilities for fast iteration. This approach is ideal for quickly testing database ideas and making schema changes during development.

Resources

• MCP Protocol
• Context Servers in Zed
• Neon Docs
• Neon API Keys
• Neon MCP server GitHub