Enable and connect ClickHouse Cloud remote MCP server

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/guides/AI_ML/remote_mcp.md)

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](/docs/getting-started/quick-start/cloud)
- Your IDE or agentic development tool of choice

## Enable remote MCP server for Cloud[​](#enable-remote-mcp-server "Direct link to 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[​](#setup-clickhouse-cloud-remote-mcp-server "Direct link to Setup remote MCP for development")

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

### Claude Code[​](#claude-code "Direct link to 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[​](#claude-web "Direct link to 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[​](#cursor "Direct link to Cursor")

1. Browse and install MCP servers from the [Cursor Marketplace](https://cursor.com/marketplace).
2. Search for ClickHouse and click "Add to Cursor" on any server to install it
3. Authenticate with OAuth.

### Visual Studio Code[​](#visual-studio-code "Direct link to 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](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).

### Windsurf[​](#windsurf "Direct link to 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](https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp).

### Zed[​](#zed "Direct link to 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](https://zed.dev/docs/ai/mcp#as-custom-servers).

### Codex[​](#codex "Direct link to 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[​](#example-usage "Direct link to 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](/docs/cloud/features/ai-ml/remote-mcp#available-tools).

### Exploring your data[​](#exploring-data "Direct link to 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[​](#running-queries "Direct link to 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[​](#managing-services "Direct link to 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[​](#monitoring-costs "Direct link to 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[​](#related-content "Direct link to Related content")

- [ClickHouse agent skills](https://github.com/ClickHouse/agent-skills)

- [Enable remote MCP server for Cloud](#enable-remote-mcp-server)- [Setup remote MCP for development](#setup-clickhouse-cloud-remote-mcp-server)
    - [Claude Code](#claude-code)- [Claude web UI](#claude-web)- [Cursor](#cursor)- [Visual Studio Code](#visual-studio-code)- [Windsurf](#windsurf)- [Zed](#zed)- [Codex](#codex)- [Example usage](#example-usage)
      - [Exploring your data](#exploring-data)- [Running analytical queries](#running-queries)- [Managing services and infrastructure](#managing-services)- [Monitoring costs](#monitoring-costs)- [Related content](#related-content)

Was this page helpful?