Skip to content

setup.md

Latest commit

 

History

History
100 lines (61 loc) · 6.22 KB

setup.md

File metadata and controls

100 lines (61 loc) · 6.22 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 gmonit https://<адрес-коллектора>/mcp --header "Authorization: Bearer <MCP_AUTH_TOKEN> --transport http"

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

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

claude mcp list

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

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

Удалить:

claude mcp remove gmonit

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