MCP-сервер ClickStack - ClickHouse Documentation

ClickStack включает встроенный сервер Model Context Protocol (MCP), который позволяет AI-ассистентам взаимодействовать с вашими данными обсервабилити. После подключения AI-ассистент может выполнять запросы к журналам, трассировкам и метрикам; управлять панелями мониторинга и оповещениями; просматривать источники данных; и работать с сохранёнными поисками — всё это на естественном языке. Благодаря этому вы можете использовать такие инструменты, как Claude Code, Cursor, или любой клиент, совместимый с MCP, чтобы расследовать инциденты, создавать панели мониторинга и управлять вашей системой обсервабилити, не покидая среду разработки.

Доступность

MCP-сервер доступен в следующих типах развертывания ClickStack:

Развертывание	Статус
Open Source ClickStack	Доступно
BYOC (Собственное облако)	Доступно
ClickStack в ClickHouse Cloud	Доступно
HyperDX v1 (hyperdx.io)	Не поддерживается

Разная настройка для ClickHouse Cloud и OSS/BYOCClickStack в ClickHouse Cloud использует другую конечную точку и другой метод аутентификации, чем развертывания Open Source и BYOC. См. раздел ClickStack в ClickHouse Cloud ниже с инструкциями по настройке для Cloud.

ClickStack в ClickHouse Cloud

ClickStack в ClickHouse Cloud подключается через конечную точку Cloud MCP по адресу https://mcp.clickhouse.cloud/clickstack и использует аутентификацию OAuth 2.0. Аутентификация с помощью API-ключа для этой конечной точки не поддерживается.

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

Запущенный сервис ClickHouse Cloud с включенным ClickStack
Включенный MCP на сервисе — откройте консоль Cloud, нажмите Connect, выберите Connect with MCP и включите его

Конечная точка

https://mcp.clickhouse.cloud/clickstack

Для аутентификации используется OAuth 2.0. Когда ваш MCP-клиент подключается впервые, откроется окно браузера, в котором нужно войти с учетными данными ClickHouse Cloud. Ключ API не требуется.

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

При первом подключении каждый клиент автоматически выполняет OAuth-поток.

claude mcp add --transport http clickstack https://mcp.clickhouse.cloud/clickstack

Запустите Claude Code и выполните /mcp, затем выберите clickstack, чтобы завершить OAuth-поток.

Добавьте следующее в .cursor/mcp.json:

{
  "mcpServers": {
    "clickstack": {
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

Добавьте следующее в .vscode/mcp.json:

{
  "servers": {
    "clickstack": {
      "type": "http",
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

Добавьте следующее в opencode.json:

{
  "mcp": {
    "clickstack": {
      "type": "remote",
      "url": "https://mcp.clickhouse.cloud/clickstack"
    }
  }
}

Добавьте следующее в librechat.yaml:

mcpServers:
  clickstack:
    type: streamable-http
    url: https://mcp.clickhouse.cloud/clickstack

Подключиться может любой MCP-клиент с поддержкой Streamable HTTP и OAuth. Настройте его следующим образом:

URL: https://mcp.clickhouse.cloud/clickstack

Указание конкретного сервиса

Без заголовка x-service-id запросы по умолчанию направляются в первый сервис ClickStack, созданный в вашем аккаунте. Чтобы обратиться к другому сервису, передайте x-service-id: <YOUR_SERVICE_ID> в качестве заголовка в конфигурации вашего MCP-клиента.

Open Source и BYOC

Развертывания Open Source и BYOC используют встроенную конечную точку MCP экземпляра ClickStack с аутентификацией по Bearer-токену.

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

запущенный экземпляр ClickStack (варианты развертывания см. в разделе Развертывание)
Personal API Access Key — его можно найти в HyperDX: Team Settings → API Keys → Personal API Access Key

Personal API Access Key отличается от ключ API для приёма данных API key в Team Settings, который используется для аутентификации телеметрических данных, отправляемых в OpenTelemetry Collector.

Конечная точка

MCP-сервер доступен по пути /api/mcp в URL фронтенда ClickStack. Например, для локального развертывания с настройками по умолчанию URL: http://localhost:8080/api/mcp. Замените localhost:8080 на хост и порт вашего экземпляра, если вы изменили стандартные значения.

В примерах на этой странице используется URL фронтенд-приложения (по умолчанию порт 8080). Вы также можете обращаться к MCP-серверу напрямую через бэкенд по адресу <BACKEND_URL>/mcp, но не во всех развертываниях бэкенд доступен извне, поэтому в этой документации используется путь через фронтенд.

MCP-сервер использует транспорт Streamable HTTP с аутентификацией по Bearer token.

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

Замените <YOUR_CLICKSTACK_URL> на URL вашего экземпляра (например, http://localhost:8080), а <YOUR_API_KEY> — на ваш Personal API Access Key.

claude mcp add --transport http hyperdx <YOUR_CLICKSTACK_URL>/api/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"

Добавьте следующее в файл .cursor/mcp.json:

{
  "mcpServers": {
    "hyperdx": {
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

Добавьте следующее в файл .vscode/mcp.json:

{
  "servers": {
    "hyperdx": {
      "type": "http",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

Добавьте следующее в файл opencode.json:

{
  "mcp": {
    "hyperdx": {
      "type": "remote",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

Добавьте следующее в файл librechat.yaml:

mcpServers:
  clickstack:
    type: streamable-http
    url: <YOUR_CLICKSTACK_URL>/api/mcp
    headers:
      Authorization: "Bearer <YOUR_API_KEY>"

Подключиться может любой MCP-клиент с поддержкой Streamable HTTP. Укажите:

URL: <YOUR_CLICKSTACK_URL>/api/mcp
Заголовок: Authorization: Bearer <YOUR_API_KEY>

Что можно делать с MCP?

После подключения ваш ИИ-помощник получает доступ к набору инструментов, охватывающих основные области ClickStack. В их числе:

Запросы к данным — Ищите и агрегируйте журналы, трассировки и метрики с помощью конструктора запросов ClickStack, поискового синтаксиса или raw SQL.
Источники данных — Просматривайте доступные источники данных, подключения к базам данных, схемы столбцов и ключи атрибутов.
Панели мониторинга — Создавайте, обновляйте, удаляйте и просматривайте панели мониторинга вместе с их плитками.
Оповещения — Создавайте, обновляйте и просматривайте оповещения вместе с историей их выполнения.
Сохранённые поиски — Создавайте, обновляйте и просматривайте повторно используемые определения сохранённых поисков.
Вебхуки — Просматривайте доступные пункты назначения вебхуков для уведомлений об оповещениях.
Команды — Просматривайте команды, в которые входит текущий пользователь, и определяйте активную команду.

Со временем набор инструментов может расширяться. Ваш MCP-клиент автоматически обнаружит доступные инструменты при подключении.

Использование в нескольких командах (OSS/BYOC)

Это относится только к развертываниям с открытым исходным кодом и BYOC. Для ClickStack в ClickHouse Cloud см. указание конкретного сервиса. По умолчанию запросы MCP выполняются в контексте вашей основной команды. Если вы состоите в нескольких командах, можно обратиться к конкретной команде, передав заголовок x-hdx-team с ID команды вместе с заголовком Authorization. Если этот заголовок не указан, используется ваша основная команда. Если указать команду, в которую вы не входите, запрос будет отклонён с ошибкой 401. Используйте в своём MCP-клиенте инструмент вывода списка команд, чтобы узнать, к каким командам у вас есть доступ и какая из них активна.

Устранение неполадок

ClickStack в ClickHouse Cloud

Не удается завершить OAuth-поток

Убедитесь, что ваш MCP-клиент поддерживает OAuth 2.0. Клиенты, поддерживающие только Bearer-токен или транспорт stdio, не могут пройти аутентификацию через конечную точку Cloud.
Проверьте, не блокирует ли браузер всплывающее окно OAuth или перенаправление.
Убедитесь, что у вашего аккаунта ClickHouse Cloud есть доступ к организации и сервису.

MCP включен, но клиент не может подключиться

Убедитесь, что вы используете конечную точку ClickStack (https://mcp.clickhouse.cloud/clickstack), а не общую конечную точку Cloud MCP (https://mcp.clickhouse.cloud/mcp).
Убедитесь, что MCP включен для сервиса в консоли Cloud.

Запросы идут не в тот сервис

Без заголовка x-service-id запросы по умолчанию направляются в первый подготовленный сервис ClickStack, к которому обращался ваш аккаунт. Передайте этот заголовок, чтобы указать конкретный сервис. См. указание конкретного сервиса.

Open Source и BYOC

Я получаю ошибку аутентификации 403

Убедитесь, что вы используете Personal API Access Key (а не ключ API для приёма данных API key).
Убедитесь, что ключ передаётся как токен Bearer в заголовке Authorization.
Проверьте, что ваш экземпляр ClickStack запущен и доступен по указанному URL.

Я сталкиваюсь с ограничением частоты запросов

MCP-сервер ограничивает частоту запросов до 600 запросов в минуту на пользователя. Если вы превысите этот лимит, запросы будут временно отклоняться. Уменьшите частоту запросов или подождите перед повторной попыткой.

Я получаю ошибку 401 с заголовком x-hdx-team

Убедитесь, что идентификатор команды указан верно и что ваша учётная запись входит в эту команду.

Я не могу подключиться к MCP-серверу

Убедитесь, что ваш MCP-клиент поддерживает транспорт Streamable HTTP. Более старые клиенты, поддерживающие только transport stdio, работать не будут.
Если вы запускаете ClickStack локально, убедитесь, что приложение доступно по указанному URL (по умолчанию — http://localhost:8080).
Для BYOC-развертываний за балансировщиком нагрузки или обратным прокси убедитесь, что путь /api/mcp не блокируется и не переписывается.

​Доступность

​ClickStack в ClickHouse Cloud

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

​Конечная точка

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

​Указание конкретного сервиса

​Open Source и BYOC

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

​Конечная точка

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

​Что можно делать с MCP?

​Использование в нескольких командах (OSS/BYOC)

​Устранение неполадок

​ClickStack в ClickHouse Cloud

​Open Source и BYOC

Доступность

ClickStack в ClickHouse Cloud

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

Конечная точка

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

Указание конкретного сервиса

Open Source и BYOC

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

Конечная точка

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

Что можно делать с MCP?

Использование в нескольких командах (OSS/BYOC)

Устранение неполадок

ClickStack в ClickHouse Cloud

Open Source и BYOC