SerenDB MCP Server

The SerenDB MCP Server is an open-source tool that lets you interact with your SerenDB Postgres databases in natural language.

To get started connecting an MCP Client like Cursor, Claude Code, VS Code, Windsurf, ChatGPT, and others, see Connect MCP clients. If you're using Cursor, you can click the button below for a quick install. When prompted, click Install within Cursor.

Imagine you want to create a new database. Instead of using the SerenDB 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 SerenDB projects". The SerenDB MCP Server makes this possible.

It works by acting as a bridge between natural language requests and the SerenDB API. Built upon the Model Context Protocol (MCP), it translates your requests into the necessary SerenDB API calls, allowing you to manage everything from creating projects and branches to running queries and performing database migrations.

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

The SerenDB MCP Server is intended for local development and IDE integrations only. We do not recommend using the SerenDB MCP Server in production environments. It can execute powerful operations that may lead to accidental or unauthorized changes.

For more information, see MCP security guidance →.

Understanding MCP and SerenDB MCP Server

The Model Context Protocol (MCP) standardizes communication between LLMs and external tools. It defines a client-server architecture, enabling LLMs (Hosts) to connect to specialized servers that provide context and tools for interacting with external systems. The key components of the MCP architecture are:

Hosts: These are AI applications, such as Claude Desktop, Claude Code, or IDEs like Cursor, that initiate connections to MCP servers
Clients: These reside within the host application and maintain one-to-one connections with individual MCP servers
Server: These programs, such as SerenDB's MCP Server, provide context, tools, and prompts to clients, enabling access to external data and functionalities

Why use MCP?

Traditionally, connecting AI models to different data sources required developers to create custom code for each integration. This fragmented approach increased development time, maintenance burdens, and limited interoperability between AI models and tools. MCP addresses this challenge by providing a standardized protocol that simplifies integration, accelerates development, and enhances the capabilities of AI assistants.

What is SerenDB MCP server?

SerenDB MCP Server acts as the Server in the MCP architecture, specifically designed for SerenDB. It provides a set of tools that MCP clients (like Claude Desktop, Claude Code, Cursor) can utilize to manage SerenDB resources. This includes actions for project management, branch management, executing SQL queries, and handling database migrations, all driven by natural language requests.

Key Benefits of using SerenDB MCP Server:

Natural language interaction: Manage SerenDB databases using intuitive, conversational commands.
Simplified database management: Perform complex actions without writing SQL or directly using the SerenDB API.
Enhanced Productivity: Streamline workflows for database administration and development.
Accessibility for non-developers: Empower users with varying technical backgrounds to interact with SerenDB databases.
Database migration support: Leverage SerenDB's branching capabilities for database schema changes initiated via natural language.

The SerenDB 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 SerenDB MCP server and SerenDB API keys.

Setup options

You can set up the SerenDB MCP Server in two ways:

Remote hosted server (preview)

You can use SerenDB's managed MCP server, available at https://mcp.serendb.com. This is the easiest way to start using the SerenDB MCP Server. It streamlines the setup process by utilizing OAuth for authentication, eliminating the need to manage SerenDB API keys directly in your client configuration.

The remote hosted MCP server is currently in its preview phase. As the [OAuth specification for MCP](https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/authorization/) is still quite new, we are releasing it in this preview state. During the initial weeks, you may experience some adjustments to the setup. However, the instructions provided should be straightforward to follow at this time.

Prerequisites:

An MCP Client application (e.g., Cursor, Windsurf, Claude Desktop, Claude Code, Cline, Zed, ChatGPT).
A SerenDB account.

Click the button below to install the SerenDB MCP server in Cursor. When prompted, click **Install** within Cursor.

Setup steps:

Go to your MCP Client's settings where you configure MCP Servers (this varies by client)
Register a new MCP Server. Add a configuration block for "SerenDB" under 'mcpServers' key. The configuration should look like this:
```
{
  "mcpServers": {
    "SerenDB": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.serendb.com/mcp"]
    }
  }
}
```
This command uses npx to run a small helper (mcp-remote) that connects to SerenDB's hosted server endpoint (https://mcp.serendb.com/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.serendb.com/mcp to https://mcp.serendb.com/sse to use SSE instead.
Save the configuration and restart or refresh your MCP client application.
The first time the client initializes SerenDB's MCP server, it should trigger an OAuth flow:
- Your browser will open a SerenDB page asking you to authorize the "SerenDB MCP Server" to access your SerenDB account.
- Review the requested permissions and click Authorize.
- You should see a success message, and you can close the browser tab.
Your MCP client should now be connected to the SerenDB Remote MCP Server and ready to use.

Local MCP Server

You can install SerenDB MCP server locally using npm.

Prerequisites

Node.js (>= v18.0.0): Ensure Node.js version 18 or higher is installed on your system. You can download it from nodejs.org.
SerenDB API Key: You will need a SerenDB API key to authenticate the SerenDB MCP Server with your SerenDB account. You can create one from the SerenDB Console under your Profile settings. Refer to the SerenDB documentation on API Keys for detailed instructions.

Open your MCP client application and navigate to the settings where you can configure MCP servers. The location of these settings may vary depending on your client. Add a configuration block for "SerenDB" under the mcpServers key. Your configuration should look like this:

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

If you are using Windows and encounter issues while adding the MCP server, you might need to use the Command Prompt (cmd) or Windows Subsystem for Linux (wsl) to run the necessary commands. Your configuration setup may resemble the following:

  ```json
  {
    "mcpServers": {
      "neon": {
        "command": "cmd",
        "args": ["/c", "npx", "-y", "@serenorg/mcp-server-neon", "start", "<YOUR_NEON_API_KEY>"]
      }
    }
  }
  ```

  ```json
  {
    "mcpServers": {
      "neon": {
        "command": "wsl",
        "args": ["npx", "-y", "@serenorg/mcp-server-neon", "start", "<YOUR_NEON_API_KEY>"]
      }
    }
  }
  ```

Troubleshooting

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:

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

Usage examples

After setting up either the remote or local server and connecting your MCP client, you can start interacting with your SerenDB databases using natural language.

Example interactions

List projects: "List my SerenDB projects"
Create a new project: "Create a SerenDB project named 'my-test-project'"
List tables in a database: "What tables are in the database 'my-database' in project 'my-project'?"
Add a column to a table: "Add a column 'email' of type VARCHAR to the 'users' table in database 'main' of project 'my-project'"
Run a query: "Show me the first 10 rows from the 'users' table in database 'my-database'"

API key-based authentication

The SerenDB MCP Server supports API key-based authentication for remote access, in addition to OAuth. This allows for simpler authentication using your SerenDB API key (personal or organization) for programmatic access. API key configuration is shown below:

{
  "mcpServers": {
    "SerenDB": {
      "url": "https://mcp.serendb.com/mcp",
      "headers": {
        "Authorization": "Bearer <$NEON_API_KEY>"
      }
    }
  }
}

Currently, only streamable HTTP responses are supported with API-key based authentication. Server-Sent Events (SSE) responses are not yet supported for this authentication method.

Streamable HTTP support

The SerenDB MCP Server supports streamable HTTP as an alternative to Server-Sent Events (SSE) for streaming responses. This makes it easier to consume streamed data in environments where SSE is not ideal — such as CLI tools, backend services, or AI agents. To use streamable HTTP, make sure to use the latest remote MCP server, and specify the https://mcp.serendb.com/mcp endpoint, as shown in the following configuration example:

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

MCP security guidance

The SerenDB MCP server provides access to powerful tools for interacting with your SerenDB database—such as run_sql, create_table, update_row, and delete_table. MCP tools are useful in development and testing, but we do not recommend using MCP tools in production environments.

Recommended usage

Use MCP only for local development or IDE-based workflows.
Never connect MCP agents to production databases.
Avoid exposing production data or PII data to MCP — only use anonymized data.
Disable MCP tools capable of accessing or modifying data when they are not being used.
Only grant MCP access to trusted users.

Human oversight and access control

Always review and authorize actions requested by the LLM before execution. The MCP server grants powerful database management capabilities through natural language requests, so human oversight is essential.
Restrict access to ensure that only authorized users and applications have access to the SerenDB MCP Server and associated API keys.
Monitor usage and regularly audit who has access to your MCP server configurations and SerenDB API keys.

By following these guidelines, you reduce the risk of accidental or unauthorized actions when working with SerenDB's MCP Server.

Conclusion

The SerenDB MCP Server enables natural language interaction with SerenDB Postgres databases, offering a simplified way to perform database management tasks. You can perform actions such as creating new SerenDB projects and databases, managing branches, executing SQL queries, and making schema changes, all through conversational requests. Features like branch-based migrations contribute to safer schema modifications. By connecting your preferred MCP client to the SerenDB MCP Server, you can streamline database administration and development workflows, making it easier for users with varying technical backgrounds to interact with SerenDB databases.

Resources

PreviousSemantic Kernel NextData API

Last updated 1 month ago