> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Enable and connect ClickHouse Cloud remote MCP server

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

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

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/get-started/setup/cloud)
* Your IDE or agentic development tool of choice

<h2 id="enable-remote-mcp-server">
  Enable remote MCP server for Cloud
</h2>

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**:

<Image img="https://mintcdn.com/private-7c7dfe99/F7iOqwDUBB9E2S65/images/use-cases/AI_ML/MCP/1connectmcpmodal.webp?fit=max&auto=format&n=F7iOqwDUBB9E2S65&q=85&s=744e5d063d27c1d69b4b09204c3627f8" alt="Select MCP in the Connect Modal" size="md" width="2190" height="2082" data-path="images/use-cases/AI_ML/MCP/1connectmcpmodal.webp" />

Toggle the button on to enable MCP for the service:

<Image img="https://mintcdn.com/private-7c7dfe99/F7iOqwDUBB9E2S65/images/use-cases/AI_ML/MCP/2enable_mcp.webp?fit=max&auto=format&n=F7iOqwDUBB9E2S65&q=85&s=b3dcbb434349ffabcc8402552d82eb1a" alt="Enable MCP Server" size="md" width="1340" height="884" data-path="images/use-cases/AI_ML/MCP/2enable_mcp.webp" />

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

```bash theme={null}
https://mcp.clickhouse.cloud/mcp
```

<h2 id="setup-clickhouse-cloud-remote-mcp-server">
  Setup remote MCP for development
</h2>

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

<h3 id="claude-code">
  Claude Code
</h3>

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

```bash theme={null}
claude mcp add --transport http clickhouse-cloud https://mcp.clickhouse.cloud/mcp
```

Then launch Claude Code:

```bash theme={null}
claude
```

Run the following command to list MCP servers:

```bash theme={null}
/mcp
```

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

<h3 id="claude-web">
  Claude web UI
</h3>

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

<h3 id="cursor">
  Cursor
</h3>

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.

<h3 id="visual-studio-code">
  Visual Studio Code
</h3>

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

```json theme={null}
{
  "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).

<h3 id="windsurf">
  Windsurf
</h3>

Edit your `mcp_config.json` file with the following config:

```json theme={null}
{
  "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).

<h3 id="zed">
  Zed
</h3>

Add ClickHouse as a custom server.
Add the following to your Zed settings under **context\_servers**:

```json theme={null}
{
  "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).

<h3 id="codex">
  Codex
</h3>

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

```bash theme={null}
codex mcp add clickhouse-cloud --url https://mcp.clickhouse.cloud/mcp
```

<h2 id="example-usage">
  Example usage
</h2>

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/products/cloud/features/ai-ml/remote-mcp#available-tools).

<h3 id="exploring-data">
  Exploring your data
</h3>

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) |

<h3 id="running-queries">
  Running analytical queries
</h3>

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.

<h3 id="managing-services">
  Managing services and infrastructure
</h3>

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`                  |

<h3 id="monitoring-costs">
  Monitoring costs
</h3>

| 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`) |

<h2 id="related-content">
  Related content
</h2>

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