Как подключить ClickHouse к Microsoft Copilot через MCP

💡 Без установки? Используйте cloud.anythingmcp.com напрямую. Войдите, нажмите Connectors → ClickHouse, вставьте учётные данные, создайте MCP API key, и готово. Без Docker, без git clone, без локального сервера.

ClickHouse + Microsoft Copilot

Любой AI-агент может обращаться к серверу ClickHouse или сервису ClickHouse Cloud в режиме только для чтения через HTTP-интерфейс: список баз данных, таблиц и столбцов, операторы CREATE, размеры таблиц, выполняющиеся и недавние запросы и любой SELECT. Каждый запрос несёт readonly=1, поэтому запись отклоняет сам ClickHouse.

Предварительные требования

Полные инструкции по настройке встроены в коннектор (видны в магазине при выборе коннектора). Требуемые переменные окружения:

CLICKHOUSE_URL, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD

Шаг 1 — Получите учётные данные

Настройка занимает около 3 минут. Нужен HTTPS-адрес сервера ClickHouse или сервиса ClickHouse Cloud и пользователь с правом чтения.

1. Укажите адрес HTTP-интерфейса с портом в CLICKHOUSE_URL. В ClickHouse Cloud откройте сервис, нажмите Connect, выберите HTTPS и скопируйте хост, например https://abc123xyz.europe-west4.gcp.clickhouse.cloud:8443. Для собственного сервера: https://your-host:8443 или http://your-host:8123 в частной сети. Только схема, хост и порт, без пути.
2. Создайте отдельного пользователя, который может только читать, например CREATE USER mcp_reader IDENTIFIED BY '...'; GRANT SELECT ON analytics.* TO mcp_reader;. Для clickhouse_table_sizes, clickhouse_running_queries и clickhouse_recent_queries выдайте также GRANT SELECT ON system.parts, system.processes, system.query_log TO mcp_reader. Встроенный пользователь ClickHouse Cloud называется default.
3. Не назначайте этому пользователю профиль настроек с readonly = 2: коннектор ставит readonly=1 в каждом запросе, а при readonly = 2 ClickHouse такое изменение отклоняет. readonly = 0 и 1 работают оба.
4. Укажите имя пользователя в CLICKHOUSE_USER, а его пароль в CLICKHOUSE_PASSWORD. Они передаются как HTTP Basic auth.
5. Только ClickHouse Cloud: IP access list сервиса должен разрешать адрес, с которого обращается AnythingMCP.
6. Установите коннектор и вызовите clickhouse_server_info: он покажет версию, время работы, часовой пояс сервера, подключённого пользователя, его базу данных по умолчанию и действующий уровень readonly.

Что он читает: базы данных, видимые пользователю, с движком и комментарием; таблицы и представления одной базы (движок, общее число строк и байт, читаемый размер, комментарий); столбцы таблицы с типом, выражением по умолчанию и признаком вхождения в ключ партиционирования, сортировки или первичный ключ; оператор CREATE таблицы или представления (движок, ORDER BY, PARTITION BY, TTL, настройки или SELECT, стоящий за представлением); столбцы, которые clickhouse_search_columns находит по имени во всех базах. Для эксплуатации: объём хранения по таблицам по активным частям, выполняющиеся сейчас запросы и завершённые или упавшие запросы из журнала запросов. clickhouse_query выполняет один оператор типа SELECT, WITH, SHOW, DESCRIBE, EXPLAIN или EXISTS.

Что он пишет: ничего. Каждый запрос несёт настройку readonly=1, поэтому ClickHouse отклоняет INSERT, ALTER, CREATE, DROP и SET независимо от прав пользователя. Инструментов записи нет, поэтому при установке ни один инструмент не отключён.

Как ИИ строит запросы: он изучает структуру через clickhouse_list_databases, clickhouse_list_tables, clickhouse_describe_table и clickhouse_show_create_table, затем фильтрует по ключу сортировки и столбцам партиционирования, агрегирует в SQL (count(), sum(), uniq(), quantile(0.95)(x), toStartOfDay(ts)) и всегда заканчивает запрос LIMIT. Перед запросом, который может просканировать большую таблицу, он может выполнить EXPLAIN или EXPLAIN ESTIMATE. Запрос должен быть одним оператором без конструкции FORMAT и без точки с запятой в конце; database задаёт базу по умолчанию для имён таблиц без указания базы.

Форматы данных: формат JSON возвращает meta (имена и типы столбцов), data (строки), rows (число строк) и statistics (прошедшие секунды, прочитанные строки и байты). clickhouse_query может отвечать также в JSONCompact (строки как массивы, компактнее), CSVWithNames или TabSeparatedWithNames. 64-битные целые (UInt64, Int64) приходят строками, так что "12345678901" означает число. Значения DateTime имеют вид YYYY-MM-DD hh:mm:ss в часовом поясе сервера из clickhouse_server_info, если тип столбца не задаёт другой. Размеры из formatReadableSize указаны в двоичных единицах (KiB, MiB, GiB).

Постраничный вывод и ограничения: постраничного вывода нет, и ограничения на число строк тоже нет, кроме вашего LIMIT и предела размера ответа коннектора; весь результат приходит одним ответом, поэтому лучше агрегировать, чем выгружать сырые строки. clickhouse_search_columns возвращает до 500 совпадений. clickhouse_recent_queries возвращает последние 100 запросов за minutes (по умолчанию 60). clickhouse_running_queries показывает только ответивший узел, в ClickHouse Cloud это одна реплика сервиса. Простаивающий сервис Cloud просыпается при первом запросе, и это может занять до минуты.

Частые ошибки: тело ответа содержит Code: <n>. DB::Exception: .... Код 164 (READONLY) означает, что оператор пишет данные или меняет настройку. 497 (ACCESS_DENIED, HTTP 403) означает отсутствующий GRANT или, в ClickHouse Cloud, IP access list, который не пропускает этот сервер. 60 (UNKNOWN_TABLE) и 81 (UNKNOWN_DATABASE) означают неверное имя, 62 (SYNTAX_ERROR) ошибку в SQL, 159 или 241 тайм-аут или предел памяти: сузьте запрос. 401 или 516 (AUTHENTICATION_FAILED) означает неверного пользователя или пароль. Если по адресу ничего не отвечает, обычно неверен порт или в CLICKHOUSE_URL есть путь.

Коннектор не вставляет, не изменяет и не удаляет данные, не создаёт и не меняет таблицы и не управляет сервисами ClickHouse Cloud (запуск, остановка, масштабирование, резервные копии, расходы): для этого установите отдельный коннектор ClickHouse Cloud.

Шаг 2 — Установите адаптер

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Шаг 3 — Добавьте коннектор в Microsoft Copilot

URL вашего сервера: в AnythingMCP откройте MCP Servers → сервер, на котором находится этот коннектор, и скопируйте его URL (https://cloud.anythingmcp.com/mcp/…). Используйте его везде, где в этом руководстве указано YOUR_SERVER_ID.

Microsoft Copilot использует MCP-серверы через агентов, созданных в Copilot Studio: ты добавляешь AnythingMCP в агента как инструмент, а затем публикуешь агента в Microsoft 365 Copilot и Teams. Copilot Studio подключается из облака Microsoft по Streamable HTTP, который AnythingMCP поддерживает.

1. В Copilot Studio открой своего агента (или создай нового), перейди в Tools и выбери Add a tool → New tool → Model Context Protocol.
2. Укажи Server name (например, AnythingMCP), Server description, которое объясняет, что делает коннектор, и Server URL https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID. По описанию Copilot Studio решает, когда вызывать сервер.
3. В аутентификации выбери API key, установи Type в Header, укажи имя заголовка X-API-Key и нажми Create.
4. В окне Add tool выбери Create a new connection, вставь MCP API-ключ из AnythingMCP (MCP Servers → твой сервер → API keys) и нажми Add to agent.
5. Проверь в панели Test агента: попроси о том, для чего нужны инструменты ClickHouse.
6. Нажми Publish, затем Channels → Microsoft 365 and Microsoft Teams, оставь включённым Make agent available in Microsoft Copilot и нажми Add channel. See agent in Teams установит агента для тебя; в Microsoft 365 Copilot введи @ и выбери агента.

Хочешь, чтобы каждый входил под своей учётной записью? Вместо API-ключа выбери OAuth 2.0 → Dynamic discovery: каждый пользователь войдёт в AnythingMCP при первом вызове агентом.

Размещаешь сам? Используй публичный HTTPS-адрес своего экземпляра вместо https://cloud.anythingmcp.com. Copilot Studio подключается из облака Microsoft, поэтому localhost не подойдёт.

Доступные инструменты

Примеры запросов

• «Какие есть базы данных и таблицы, и какие таблицы занимают больше всего места на диске?»
• «Сколько событий в день было в analytics.events за последние 30 дней?»
• «Где лежит столбец вроде customer_id? Поищи во всех базах данных.»
• «Покажи запросы, которые упали за последний час, с кодом ошибки.»
• «Какие 10 стран дали больше всего выручки в этом месяце? Сначала проверь ключ сортировки, чтобы запрос был дешёвым.»

FAQ

Для какого Copilot это руководство? Для Microsoft 365 Copilot на работе — через агентов Copilot Studio. В приложении Microsoft Copilot для личных аккаунтов добавить свой MCP-сервер нельзя.

Что нужно? Рабочий аккаунт с доступом к Copilot Studio (лицензия или пробная версия), чтобы создать агента. Тем, кто будет пользоваться им в Microsoft 365 Copilot или Teams, нужен доступ к агенту: поделись им или попроси администратора опубликовать его для организации. Если в организации действуют политики данных для коннекторов Power Platform, они распространяются и на MCP-серверы.

Агент не вызывает инструменты. Проверь, что имя заголовка — ровно X-API-Key, а ключ относится к тому же MCP-серверу, что и URL, и сделай Server description конкретным: по нему Copilot Studio решает, когда вызывать сервер. После каждого изменения опубликуй агента заново; в открытом чате введи «start over», чтобы перейти на новую версию.

Следующие шаги

• Страница коннектора
• Подключить к Claude
• Подключить к ChatGPT
• Подключить к Cursor
• Подключить к Gemini
• Подключить к Meta Muse