Skip to content

setup.md

Latest commit

 

History

History
104 lines (65 loc) · 6.23 KB

setup.md

File metadata and controls

104 lines (65 loc) · 6.23 KB

MCP — Настройка

Подключение

Включение MCP-эндпоинта на коллекторе.

Нужен коллектор GMONIT версии >= v4-6274.

Переменные окружения коллектора:

Переменная Описание Пример
MCP_ENABLED Включить MCP-модуль true
MCP_AUTH_TOKEN Bearer-токен для аутентификации MCP-клиентов. Любая непустая строка mcp-7Hq3...
CLICKHOUSE_READ_USER Пользователь ClickHouse, от имени которого MCP выполняет запросы gmonit_readonly
CLICKHOUSE_READ_KEY Пароль этого пользователя <секрет>

При MCP_ENABLED=true CLICKHOUSE_READ_USER и CLICKHOUSE_READ_KEY становятся обязательными — без них коллектор не стартует. Кого выбирать в качестве этого пользователя — см. Read-only пользователь ClickHouse.

После рестарта коллектора эндпоинт доступен по адресу https://<адрес-коллектора>/mcp (Streamable HTTP).

Быстрая проверка доступности:

curl -i -H "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  https://<адрес-коллектора>/mcp

Коды ответа: 200/405 — эндпоинт жив (MCP принимает POST), 401 — неверный токен.

Read-only пользователь ClickHouse

MCP выполняет все запросы от имени пользователя ClickHouse, указанного в подключении. Чтобы AI-агент не мог изменить или удалить данные, выделите ему отдельную учётку с правом только на чтение.

Особенно важно при включённом режиме произвольного SQL — read-only пользователь там единственная реальная защита от разрушительных запросов агента.

Режим произвольного SQL

По умолчанию агент работает только через структурированные инструменты (Apdex приложений, схема таблиц, состояние pipeline). Произвольный SQL включается отдельно — это компромисс между гибкостью и безопасностью.

Переменная Описание По умолчанию
MCP_RAW_SQL_ENABLED Разрешить инструмент execute_query с произвольным SQL false

Если флаг не выставлен, инструмент в наборе MCP остаётся, но любой его вызов агенту возвращает сообщение о том, что произвольный SQL отключён — у агента не получится обойти ограничение, переформулировав запрос.

При включении:

  • Результат любого запроса режется на 200 строках
  • Агент может выполнить всё, что позволят права пользователя ClickHouse — поэтому включайте только в связке с read-only пользователем
  • Полезно для ad-hoc исследования данных, для production-окружений лучше держать выключенным

Подключение клиента

Подключение AI-агента к развёрнутому MCP-эндпоинту.

Для Claude Code (CLI):

claude mcp add --transport http \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  gmonit https://<адрес-коллектора>/mcp

<MCP_AUTH_TOKEN> и адрес коллектора возьмите у администратора стенда.

Проверить подключение:

claude mcp list

Несколько стендов можно держать одновременно — каждому своё имя:

claude mcp add --transport http --header "Authorization: Bearer <TOKEN_DEV>" \
  gmonit-dev https://<dev-collector>/mcp
claude mcp add --transport http --header "Authorization: Bearer <TOKEN_PROD>" \
  gmonit-prod https://<prod-collector>/mcp

Удалить:

claude mcp remove gmonit

Другие MCP-клиенты (Codex, IDE-плагины) подключаются так же — указывается транспорт HTTP, URL вида https://<адрес-коллектора>/mcp и заголовок Authorization: Bearer <MCP_AUTH_TOKEN>.