Enable and connect ClickHouse Cloud remote MCP server

This guide explains how to enable and use the ClickHouse Cloud Remote MCP

This guide shows you how to enable the ClickHouse Cloud Remote MCP Server and set it up for use with common developer tools.

Prerequisites

• A running ClickHouse Cloud service
• Your IDE or agentic development tool of choice

Enable remote MCP server for Cloud

Connect to the ClickHouse Cloud service for which you want to enable the remote MCP server. In the left-hand menu, click Connect. A box with connection details will open.

Select Connect with MCP:

Toggle the button on to enable MCP for the service:

Copy the displayed URL, which is the same as the one below:

https://mcp.clickhouse.cloud/mcp

Setup remote MCP for development

Choose your IDE or tool below and follow the corresponding setup instructions.

Claude Code

From your working directory, run the following command to add the ClickHouse Cloud MCP Server configuration to Claude Code:

claude mcp add --transport http clickhouse-cloud https://mcp.clickhouse.cloud/mcp

Then launch Claude Code:

claude

Run the following command to list MCP servers:

/mcp

Select clickhouse-cloud and authenticate via OAuth using your credentials for ClickHouse Cloud.

Claude web UI

1. Navigate to Customize > Connectors
2. Click the ”+” icon and Add custom connector
3. Give the custom connector a name like clickhouse-cloud and add it
4. Click the newly added clickhouse-cloud connector and click Connect
5. Authenticate using your ClickHouse Cloud credentials via OAuth

Cursor

1. Browse and install MCP servers from the Cursor Marketplace.
2. Search for ClickHouse and click “Add to Cursor” on any server to install it
3. Authenticate with OAuth.

Visual Studio Code

Add the following configuration to your .vscode/mcp.json:

{
  "servers": {
    "clickhouse-cloud": {
      "type": "http",
      "url": "https://mcp.clickhouse.cloud/mcp"
    }
  }
}

For more details refer to the Visual Studio Code docs.

Windsurf

Edit your mcp_config.json file with the following config:

{
  "mcpServers": {
    "clickhouse-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"]
    }
  }
}

For more details refer to the Windsurf docs.

Zed

Add ClickHouse as a custom server. Add the following to your Zed settings under context_servers:

{
  "context_servers": {
    "clickhouse-cloud": {
      "url": "https://mcp.clickhouse.cloud/mcp"
    }
  }
}

Zed should then prompt you to authenticate via OAuth when it first connects to the server. For more details refer to the Zed docs.

Codex

Run the following command to add the ClickHouse Cloud MCP server via the CLI:

codex mcp add clickhouse-cloud --url https://mcp.clickhouse.cloud/mcp

Example usage

Once connected, you can interact with ClickHouse Cloud through natural-language prompts. Below are some common workflows and the tools your MCP client will invoke behind the scenes. For a full list of available tools, see the tool reference.

Exploring your data

Start by discovering what’s available:

Prompt	Tool invoked
”What organizations do I have access to?”	get_organizations
”What databases are available on my service?”	list_databases
”Show me the tables in the default database”	list_tables
”List all tables whose names start with events_”	list_tables (with the like filter)

Running analytical queries

Ask questions in plain language and the agent will translate them into SQL:

Prompt	Tool invoked
”Show me the top 10 rows from the hits table”	run_select_query
”What’s the average session duration by country for the last 7 days?”	run_select_query
”How many rows are in each table in the analytics database?”	run_select_query

The run_select_query tool only permits SELECT statements. All queries are read-only.

Managing services and infrastructure

Get visibility into your ClickHouse Cloud resources:

Prompt	Tool invoked
”List all my services”	get_services_list
”What’s the status of my production service?”	get_service_details
”Show me the backup schedule for this service”	get_service_backup_configuration
”List recent backups”	list_service_backups
”What ClickPipes are configured on this service?”	list_clickpipes

Monitoring costs

Prompt	Tool invoked
”What was my organization’s cost last week?”	get_organization_cost
”Show me daily costs from March 1 to March 15”	get_organization_cost (with from_date and to_date)

Related content

• ClickHouse agent skills