Enable and connect ClickHouse Cloud remote MCP server

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
For headless authentication, a ClickHouse Cloud API key with access to the required organization and services

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. Enabling or disabling MCP requires the control-plane:service:manage-mcp permission (see Console roles and permissions): 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.

Authenticate from a headless environment

If your MCP client runs on a remote or headless host where a browser-based OAuth flow is not practical, authenticate with a ClickHouse Cloud API key instead.

In the ClickHouse Cloud console, open your organization and select API Keys.
Create a key with the minimum roles and permissions required for the organizations and services the MCP client needs to access, then download the key ID and secret.
On the remote host, provide the credentials through your secret-management system and create an HTTP Basic authorization value:

export CLICKHOUSE_CLOUD_API_KEY="<key_id>"
export CLICKHOUSE_CLOUD_API_SECRET="<key_secret>"

export CH_AUTH="Basic $(
  printf '%s:%s' \
    "$CLICKHOUSE_CLOUD_API_KEY" \
    "$CLICKHOUSE_CLOUD_API_SECRET" |
  base64 | tr -d '\n'
)"

Select your MCP client and add the remote MCP server:

Claude Code
Codex
OpenCode

claude mcp add \
  --scope user \
  --transport http \
  clickhouse-cloud \
  https://mcp.clickhouse.cloud/mcp \
  --header 'Authorization: ${CH_AUTH}'

Claude Code expands CH_AUTH from the environment when it connects. Launch Claude Code and run /mcp to confirm that clickhouse-cloud is connected.See the Claude Code MCP documentation for details about remote HTTP servers and header configuration.

Add the following entry to ~/.codex/config.toml:

[mcp_servers.clickhouse-cloud]
url = "https://mcp.clickhouse.cloud/mcp"
env_http_headers = { Authorization = "CH_AUTH" }

Run codex mcp list to confirm that clickhouse-cloud is configured.See the Codex configuration reference for details about mcp_servers.<id>.env_http_headers.

Add the following entry to your opencode.jsonc configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "clickhouse-cloud": {
        "type": "remote",
        "url": "https://mcp.clickhouse.cloud/mcp",
        "oauth": false,
        "headers": {
          "Authorization": "{env:CH_AUTH}"
        }
      }
    }
  }
}

Run opencode mcp list to confirm that clickhouse-cloud is connected.See the OpenCode MCP documentation for details about remote servers, headers, and environment-variable substitution.

Keep CH_AUTH available in each client session, and do not commit the API key, secret, or CH_AUTH value to source control. Base64 encoding does not encrypt the credentials. This API-key flow does not require a browser or a separate clickhousectl login.

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

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

Cursor

Browse and install MCP servers from the Cursor Marketplace.
Search for ClickHouse and click “Add to Cursor” on any server to install it
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`)

ClickHouse agent skills

Get started

Services and infrastructure

Bring Your Own Cloud

Data and integrations

Connect and query

Access management

Security and compliance

Monitoring and backups

AI tools and agents

Cloud API

Billing

Support

ClickHouse Private

Enable and connect ClickHouse Cloud remote MCP server

Enable remote MCP server for Cloud

Setup remote MCP for development

Authenticate from a headless environment

Claude Code

Claude web UI

Cursor

Visual Studio Code

Windsurf

Zed

Codex

Example usage

Exploring your data

Running analytical queries

Managing services and infrastructure

Monitoring costs

​Enable remote MCP server for Cloud

​Setup remote MCP for development

​Authenticate from a headless environment

​Claude Code

​Claude web UI

​Cursor

​Visual Studio Code

​Windsurf

​Zed

​Codex

​Example usage

​Exploring your data

​Running analytical queries

​Managing services and infrastructure

​Monitoring costs

​Related content

Enable remote MCP server for Cloud

Setup remote MCP for development

Authenticate from a headless environment

Claude Code

Claude web UI

Cursor

Visual Studio Code

Windsurf

Zed

Codex

Example usage

Exploring your data

Running analytical queries

Managing services and infrastructure

Monitoring costs

Related content