Перейти к основному содержанию
В этом руководстве описано, как включить удалённый MCP-сервер ClickHouse Cloud и настроить его для работы с распространёнными инструментами разработки. Необходимые условия
  • Запущенный сервис ClickHouse Cloud
  • IDE или выбранный вами инструмент для агентной разработки
  • Для неинтерактивной аутентификации — ключ API ClickHouse Cloud с доступом к нужной организации и сервисам

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

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

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

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

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

Если ваш MCP-клиент работает на удалённом хосте или хосте без графического интерфейса, где OAuth-поток через браузер использовать неудобно, выполните аутентификацию с помощью ключа API ClickHouse Cloud.
  1. В консоли ClickHouse Cloud откройте свою организацию и выберите API Keys.
  2. Создайте ключ с минимальным набором ролей и разрешений, необходимых MCP-клиенту для доступа к нужным организациям и сервисам, затем скачайте ID ключа и секрет. Чтобы вместо этого создать ключ с помощью clickhousectl, найдите ID роли, а затем создайте ключ со списком разрешённых IP-адресов для MCP-хоста. Для работы clickhousectl нужен уже существующий ключ API с разрешением на создание ключей:
    Команда выводит ID нового ключа и секрет только один раз — сохраните их в своём менеджере секретов. Без --ip-allow список разрешённых IP-адресов ключа остаётся пустым, и любой доступ запрещается.
  3. На удалённом хосте передайте учётные данные через используемую систему управления секретами и сформируйте значение для авторизации HTTP Basic:
  1. Выберите свой MCP-клиент и добавьте удалённый MCP-сервер:
При подключении Claude Code подставляет значение CH_AUTH из переменных окружения. Запустите Claude Code и выполните /mcp, чтобы убедиться, что clickhouse-cloud подключён.Подробнее об удалённых HTTP-серверах и настройке заголовков см. в документации Claude Code по MCP.
Переменная CH_AUTH должна быть доступна в каждом сеансе клиента. Не коммитьте ключ API, секрет или значение CH_AUTH в систему контроля версий. Кодирование Base64 не шифрует учётные данные. При аутентификации по ключу API не нужен ни браузер, ни отдельный вход через clickhousectl. Если вы также используете clickhousectl на том же хосте, он считывает те же переменные CLICKHOUSE_CLOUD_API_KEY и CLICKHOUSE_CLOUD_API_SECRET, и они имеют приоритет над входом через браузер.

Claude Code

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

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

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

Cursor

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

Visual Studio Code

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

Windsurf

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

Zed

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

Codex

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

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

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

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

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

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

Задавайте вопросы на естественном языке, и агент переведет их в SQL: Инструмент run_select_query позволяет выполнять только команды SELECT. Все запросы — только для чтения.

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

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

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