Включение и подключение удалённого MCP-сервера ClickHouse Cloud

В этом руководстве описано, как включить удалённый MCP-сервер ClickHouse Cloud и настроить его для работы с распространёнными инструментами разработки. Необходимые условия

Запущенный сервис ClickHouse Cloud
IDE или выбранный вами инструмент для агентной разработки
Для неинтерактивной аутентификации — ключ API ClickHouse Cloud с доступом к нужной организации и сервисам

Включение удалённого MCP-сервера для Cloud

Подключитесь к сервису ClickHouse Cloud, для которого нужно включить удалённый MCP-сервер. В меню слева нажмите Connect. Откроется окно со сведениями о подключении. Выберите Connect with MCP: Включите переключатель, чтобы активировать MCP для сервиса. Чтобы включить или отключить MCP, требуется разрешение control-plane:service:manage-mcp (см. Роли и разрешения в консоли): Скопируйте отображаемый URL — он совпадает с приведённым ниже:

https://mcp.clickhouse.cloud/mcp

Настройка удалённого MCP для разработки

Выберите ниже IDE или инструмент и следуйте соответствующим инструкциям по настройке.

Аутентификация из среды без графического интерфейса

Если ваш MCP-клиент работает на удалённом хосте или хосте без графического интерфейса, где OAuth-поток через браузер использовать неудобно, выполните аутентификацию с помощью ключа API ClickHouse Cloud.

В консоли ClickHouse Cloud откройте свою организацию и выберите API Keys.
Создайте ключ с минимальным набором ролей и разрешений, необходимых MCP-клиенту для доступа к нужным организациям и сервисам, затем скачайте ID ключа и секрет.
На удалённом хосте передайте учётные данные через используемую систему управления секретами и сформируйте значение для авторизации HTTP Basic:

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

Выберите свой MCP-клиент и добавьте удалённый MCP-сервер:

Claude Code
Codex
OpenCode

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

При подключении Claude Code подставляет значение CH_AUTH из переменных окружения. Запустите Claude Code и выполните /mcp, чтобы убедиться, что clickhouse-cloud подключён.Подробнее об удалённых HTTP-серверах и настройке заголовков см. в документации Claude Code по MCP.

Добавьте следующую запись в ~/.codex/config.toml:

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

Выполните codex mcp list, чтобы убедиться, что clickhouse-cloud настроен.Подробнее о mcp_servers.<id>.env_http_headers см. в справочнике по конфигурации Codex.

Добавьте следующую запись в конфигурацию opencode.jsonc:

{
  "$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}"
        }
      }
    }
  }
}

Выполните opencode mcp list, чтобы убедиться, что clickhouse-cloud подключён.Подробнее об удалённых серверах, заголовках и подстановке переменных окружения см. в документации OpenCode по MCP.

Переменная CH_AUTH должна быть доступна в каждом сеансе клиента. Не коммитьте ключ API, секрет или значение CH_AUTH в систему контроля версий. Кодирование Base64 не шифрует учётные данные. При аутентификации по ключу API не нужен ни браузер, ни отдельный вход через clickhousectl.

Claude Code

В рабочем каталоге выполните следующую команду, чтобы добавить в Claude Code конфигурацию MCP Server для ClickHouse Cloud:

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

Затем запустите Claude Code:

claude

Выполните следующую команду, чтобы получить список MCP-серверов:

/mcp

Выберите clickhouse-cloud и авторизуйтесь через OAuth, используя свои учетные данные ClickHouse Cloud.

Веб-интерфейс Claude

Перейдите в Customize > Connectors
Нажмите значок «+» и выберите Add custom connector
Задайте пользовательскому коннектору имя, например clickhouse-cloud, и добавьте его
Нажмите на только что добавленный коннектор clickhouse-cloud, затем нажмите Connect
Пройдите аутентификацию через OAuth, используя свои учетные данные ClickHouse Cloud

Cursor

Откройте маркетплейс Cursor, найдите и установите MCP-серверы.
Найдите ClickHouse и на странице любого сервера нажмите “Add to Cursor”, чтобы установить его
Пройдите аутентификацию через OAuth.

Visual Studio Code

Добавьте в .vscode/mcp.json следующую конфигурацию:

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

Подробнее см. в документации по Visual Studio Code.

Windsurf

Отредактируйте файл mcp_config.json, указав следующую конфигурацию:

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

Подробнее см. в документации Windsurf.

Zed

Добавьте ClickHouse как пользовательский сервер. Добавьте следующее в настройки Zed в разделе context_servers:

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

При первом подключении к серверу Zed должен предложить вам пройти аутентификацию через OAuth. Подробнее см. в документации Zed.

Codex

Выполните следующую команду, чтобы добавить MCP-сервер ClickHouse Cloud через CLI:

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

Пример использования

После подключения вы сможете взаимодействовать с ClickHouse Cloud с помощью промптов на естественном языке. Ниже приведены некоторые типовые сценарии работы и инструменты, которые ваш MCP-клиент будет вызывать за кулисами. Полный список доступных инструментов см. в справочнике по инструментам.

Изучение ваших данных

Для начала посмотрите, что доступно:

Промпт	Используемый инструмент
”К каким организациям у меня есть доступ?”	`get_organizations`
”Какие базы данных доступны в моём сервисе?”	`list_databases`
”Покажи таблицы в базе данных `default`”	`list_tables`
”Выведи все таблицы, имена которых начинаются с `events_`”	`list_tables` (с фильтром `like`)

Выполнение аналитических запросов

Задавайте вопросы на естественном языке, и агент переведет их в SQL:

Промпт	Вызываемый инструмент
”Покажи 10 первых строк из таблицы `hits`”	`run_select_query`
”Какова средняя длительность сеанса по странам за последние 7 дней?”	`run_select_query`
”Сколько строк в каждой таблице базы данных `analytics`?”	`run_select_query`

Инструмент run_select_query позволяет выполнять только команды SELECT. Все запросы — только для чтения.

Управление сервисами и инфраструктурой

Получите обзор ресурсов ClickHouse Cloud:

Промпт	Вызываемый инструмент
”Покажи все мои сервисы”	`get_services_list`
”Какой статус у моего сервиса в продакшне?”	`get_service_details`
”Покажи расписание резервного копирования для этого сервиса”	`get_service_backup_configuration`
”Покажи последние резервные копии”	`list_service_backups`
”Какие ClickPipes настроены для этого сервиса?”	`list_clickpipes`

Отслеживание затрат

Промпт	Вызываемый инструмент
”Каковы были расходы моей организации на прошлой неделе?”	`get_organization_cost`
”Покажи ежедневные расходы с 1 по 15 марта”	`get_organization_cost` (с `from_date` и `to_date`)

Навыки для агентов ClickHouse

Начало работы

Сервисы и инфраструктура

Собственное облако

Данные и интеграции

Подключение и выполнение запросов

Управление доступом

Безопасность и соблюдение требований

Мониторинг и резервные копии

Инструменты и агенты ИИ

Cloud API

Оплата

Поддержка

ClickHouse Private

Включение и подключение удалённого MCP-сервера ClickHouse Cloud

Включение удалённого MCP-сервера для Cloud

Настройка удалённого MCP для разработки

Аутентификация из среды без графического интерфейса

Claude Code

Веб-интерфейс Claude

Cursor

Visual Studio Code

Windsurf

Zed

Codex

Пример использования

Изучение ваших данных

Выполнение аналитических запросов

Управление сервисами и инфраструктурой

Отслеживание затрат

​Включение удалённого MCP-сервера для Cloud

​Настройка удалённого MCP для разработки

​Аутентификация из среды без графического интерфейса

​Claude Code

​Веб-интерфейс Claude

​Cursor

​Visual Studio Code

​Windsurf

​Zed

​Codex

​Пример использования

​Изучение ваших данных

​Выполнение аналитических запросов

​Управление сервисами и инфраструктурой

​Отслеживание затрат

​См. также

Включение удалённого MCP-сервера для Cloud

Настройка удалённого MCP для разработки

Аутентификация из среды без графического интерфейса

Claude Code

Веб-интерфейс Claude

Cursor

Visual Studio Code

Windsurf

Zed

Codex

Пример использования

Изучение ваших данных

Выполнение аналитических запросов

Управление сервисами и инфраструктурой

Отслеживание затрат

См. также