MCP-сервер для ClickHouse

MCP-сервер для ClickHouse — это приложение, которое предоставляет AI-ассистентам доступ к базам данных ClickHouse через стандартный протокол Model Context Protocol (MCP). Сервер разворачивается на виртуальной машине в Yandex Cloud и подключается к существующему кластеру ClickHouse.

Основные возможности и преимущества

• Интеграция с Yandex AI Studio. MCP-сервер интегрируется с AI Studio MCP-серверы — подключите его к вашим AI-агентам в несколько кликов.
• Интеграция с AI-ассистентами. Позволяет AI-моделям выполнять запросы к ClickHouse, анализировать данные и получать информацию о схеме базы данных.
• Авторизация Bearer-токеном. Все запросы к MCP-серверу защищены Bearer-токеном, который хранится в Yandex Lockbox.
• Безопасное подключение к ClickHouse. Пароль для подключения к ClickHouse хранится в Yandex Lockbox и извлекается при запуске. Поддержка SSL/TLS для шифрования соединения. Опциональный CA-сертификат из Certificate Manager для non-Managed ClickHouse^®.
• Стандартный протокол MCP. Использует открытый протокол Model Context Protocol для взаимодействия с AI-моделями, обеспечивая совместимость с широким спектром клиентов.
• HTTP транспорт. MCP-сервер доступен на порту 8000 (HTTP), что упрощает интеграцию с различными клиентами и инструментами.
• Минимальные ресурсы. Приложение работает на виртуальной машине с минимальной конфигурацией (2 vCPU, 2 ГБ RAM), что снижает затраты на инфраструктуру.

1. Убедитесь, что у вас есть работающий кластер ClickHouse (Managed Service for ClickHouse или self-hosted).
2. Создайте секрет в Yandex Lockbox для хранения пароля ClickHouse. Секрет должен содержать ключ clickhouse_password со значением пароля.
3. Создайте секрет в Yandex Lockbox для хранения Bearer-токена авторизации. Секрет должен содержать ключ bearer_token с произвольным токеном.
4. (Опционально) Если используется non-Managed ClickHouse^® и требуется дополнительный CA-сертификат, загрузите сертификат в Yandex Certificate Manager.
5. (Опционально) Для диагностики включите SSH-доступ, укажите имя пользователя и публичный SSH-ключ. При включённом SSH порт 22 доступен из интернета. После установки подключайтесь по адресу ssh <имя-пользователя>@<публичный-ip-адрес-виртуальной-машины>.
6. Создайте сервисный аккаунт для установки приложения и назначьте ему на каталог установки роли compute.editor, iam.serviceAccounts.admin, vpc.admin, resource-manager.admin.
7. Назначьте установочному сервисному аккаунту роль lockbox.admin отдельно на секрет с Bearer-токеном и на секрет с учётными данными внешнего сервиса. Роль нужна для чтения и изменения прав доступа к выбранным секретам; назначать её на каталог не требуется. Это правило действует и для секретов из другого каталога. При установке приложение создаст отдельный сервисный аккаунт ВМ и назначит ему lockbox.payloadViewer только на выбранные секреты.
8. Шаблон также назначает аккаунту ВМ certificate-manager.certificates.downloader на каталог установки. Для создания этой привязки IAM установочному аккаунту нужна роль resource-manager.admin, в том числе когда пользовательский сертификат не выбран. Если используете сертификат, выберите его из каталога установки; для сертификата из другого каталога отдельно предоставьте аккаунту ВМ доступ к нему.
9. В консоли управления выберите сервис Cloud Apps.
10. На панели слева выберите Магазин приложений.
11. Выберите MCP ClickHouse и нажмите кнопку Использовать.
12. Укажите:
    • Имя приложения.
    • (Опционально) Описание приложения.
    • Сервисный аккаунт, созданный ранее.
    • Облачную подсеть, в которой будет развернута виртуальная машина.
    • Идентификатор секрета Lockbox с Bearer-токеном для авторизации.
    • (Опционально) Сертификат из Certificate Manager для подключения к ClickHouse^®.
    • Хост ClickHouse (FQDN).
    • Порт ClickHouse (по умолчанию 8443; допустимый диапазон — от 1 до 65535).
    • Имя пользователя ClickHouse (по умолчанию default).
    • Идентификатор секрета Lockbox с паролем ClickHouse.
    • Внешний доступ к MCP-серверу (опционально; по умолчанию выключен, включите для подключения по публичному IP-адресу).
13. Нажмите кнопку Установить и дождитесь, пока приложение установится.
14. После установки скопируйте полный адрес из раздела Данные приложения, поле URL MCP-сервера (внутренний): http://<private-ip>:8000/mcp. Для подключения клиенту нужен сетевой доступ к внутреннему IP-адресу ВМ.
15. Настройте ваш AI-клиент для подключения к MCP-серверу, указав заголовок Authorization: Bearer <ваш-токен>.

Подключение MCP-сервера к Yandex AI Studio

1. В консоли управления откройте сервис AI Studio и перейдите в раздел Agent Core → MCP-серверы.
2. Нажмите Создать MCP-сервер и в разделе MCP-серверы из Yandex Cloud Marketplace выберите нужный MCP-сервер.
3. Укажите имя сервера и выберите уже развёрнутый экземпляр приложения или создайте новый, следуя инструкциям по развёртыванию. При развёртывании нового сервера кнопка Сохранить будет доступна только после полного развёртывания и запуска MCP-сервера.
4. После выбора приложения значения параметров Сеть и Сервисный аккаунт MCP-сервера заполнятся автоматически.
5. Нажмите Создать. После успешной проверки подключения выберите необходимые инструменты (tools) и нажмите Сохранить — MCP-сервер будет зарегистрирован в AI Studio и доступен для использования AI-агентами.

• Анализ данных в ClickHouse с помощью AI-ассистента.
• Автоматическая генерация SQL-запросов к ClickHouse через естественный язык.
• Исследование схемы базы данных ClickHouse с помощью AI.
• Мониторинг и анализ логов, хранящихся в ClickHouse.
• Построение отчётов и визуализаций на основе данных из ClickHouse.

Служба технической поддержки Yandex Cloud отвечает на запросы 24 часа в сутки, 7 дней в неделю. Доступные виды запросов и срок их обработки зависят от тарифного плана. Подключить платную поддержку можно в консоли управления. Подробнее о порядке оказания технической поддержки.