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

Аутентификация из среды без графического интерфейса
Если ваш MCP-клиент работает на удалённом хосте или хосте без графического интерфейса, где OAuth-поток через браузер использовать неудобно, выполните аутентификацию с помощью ключа API ClickHouse Cloud.- В консоли ClickHouse Cloud откройте свою организацию и выберите API Keys.
-
Создайте ключ с минимальным набором ролей и разрешений, необходимых MCP-клиенту для доступа к нужным организациям и сервисам, затем скачайте ID ключа и секрет.
Чтобы вместо этого создать ключ с помощью
clickhousectl, найдите ID роли, а затем создайте ключ со списком разрешённых IP-адресов для MCP-хоста. Для работыclickhousectlнужен уже существующий ключ API с разрешением на создание ключей:Команда выводит ID нового ключа и секрет только один раз — сохраните их в своём менеджере секретов. Без--ip-allowсписок разрешённых IP-адресов ключа остаётся пустым, и любой доступ запрещается. - На удалённом хосте передайте учётные данные через используемую систему управления секретами и сформируйте значение для авторизации HTTP Basic:
- Выберите свой MCP-клиент и добавьте удалённый MCP-сервер:
- Claude Code
- Codex
- OpenCode
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 конфигурацию MCP Server для ClickHouse Cloud:
clickhouse-cloud и авторизуйтесь через OAuth, используя свои учетные данные ClickHouse Cloud.
- Перейдите в Customize > Connectors
- Нажмите значок «+» и выберите Add custom connector
- Задайте пользовательскому коннектору имя, например
clickhouse-cloud, и добавьте его - Нажмите на только что добавленный коннектор
clickhouse-cloud, затем нажмите Connect - Пройдите аутентификацию через OAuth, используя свои учетные данные ClickHouse Cloud
- Откройте маркетплейс Cursor, найдите и установите MCP-серверы.
- Найдите ClickHouse и на странице любого сервера нажмите “Add to Cursor”, чтобы установить его
- Пройдите аутентификацию через OAuth.
.vscode/mcp.json следующую конфигурацию:
mcp_config.json, указав следующую конфигурацию:
Задавайте вопросы на естественном языке, и агент переведет их в SQL:
Инструмент
run_select_query позволяет выполнять только команды SELECT. Все запросы — только для чтения.
Получите обзор ресурсов ClickHouse Cloud: