> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/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", background}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} style={{
    backgroundColor
  }} />
      </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](/get-started/setup/cloud)
* Your IDE or agentic development tool of choice
* For headless authentication, a [ClickHouse Cloud API key](/cloud/manage/openapi) with access to the required organization and services

<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-parallel-read-in-order-multi-part/37W7US7wfagQNRCb/images/use-cases/AI_ML/MCP/1connectmcpmodal.webp?fit=max&auto=format&n=37W7US7wfagQNRCb&q=85&s=80474b9e139ce1199881753ab7223ac9" 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. Enabling or disabling MCP requires the `control-plane:service:manage-mcp` permission (see [Console roles and permissions](/products/cloud/reference/security/console-roles#console-permissions)):

<Image img="https://mintcdn.com/private-7c7dfe99-parallel-read-in-order-multi-part/37W7US7wfagQNRCb/images/use-cases/AI_ML/MCP/2enable_mcp.webp?fit=max&auto=format&n=37W7US7wfagQNRCb&q=85&s=36f93f16d90cc8301827a1e35f9a2cb5" 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="headless-mcp-client-authentication">
  Authenticate from a headless environment
</h3>

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](/cloud/manage/openapi) instead.

1. In the ClickHouse Cloud console, open your organization and select **API Keys**.
2. 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.
3. On the remote host, provide the credentials through your secret-management system and create an HTTP Basic authorization value:

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

4. Select your MCP client and add the remote MCP server:

<Tabs>
  <Tab title="Claude Code" id="headless-auth-claude-code">
    ```bash theme={null}
    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](https://code.claude.com/docs/en/mcp#option-1-add-a-remote-http-server) for details about remote HTTP servers and header configuration.
  </Tab>

  <Tab title="Codex" id="headless-auth-codex">
    Add the following entry to `~/.codex/config.toml`:

    ```toml theme={null}
    [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](https://developers.openai.com/codex/config-reference) for details about `mcp_servers.<id>.env_http_headers`.
  </Tab>

  <Tab title="OpenCode" id="headless-auth-opencode">
    Add the following entry to your `opencode.jsonc` configuration:

    ```jsonc theme={null}
    {
      "$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](https://opencode.ai/v2/docs/mcp-servers#remote) for details about remote servers, headers, and environment-variable substitution.
  </Tab>
</Tabs>

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.

<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](/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)