MCP-сервер ClickStack

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

Это позволяет использовать такие инструменты, как Claude Code, Cursor или любой MCP-совместимый клиент, чтобы расследовать инциденты, создавать панели мониторинга и управлять вашей конфигурацией обсервабилити, не выходя из среды разработки.

Доступность

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

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

Управляемый ClickStack

Поддержка MCP-сервера для Управляемого ClickStack находится в активной разработке и скоро станет доступна. Инструкции на этой странице относятся к развертываниям Open Source ClickStack и BYOC.

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

Перед подключением MCP-клиента вам потребуется:

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

Примечание

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

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

MCP-сервер доступен по пути /api/mcp на URL фронтенда ClickStack:

Например, для локального развертывания по умолчанию:

Замените localhost:8080 на хост и порт вашего экземпляра, если вы переопределили стандартные значения.

Примечание

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

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

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

В примерах ниже показано, как настроить популярные MCP-клиенты. Замените <YOUR_CLICKSTACK_URL> на URL вашего инстанса (например, http://localhost:8080), а <YOUR_API_KEY> — на ваш Personal API Access Key.

Claude code

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

Cursor

Добавьте следующее в файл .cursor/mcp.json вашего проекта или в глобальные настройки Cursor:

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

OpenCode

Добавьте следующее в файл конфигурации opencode.json:

{
  "mcp": {
    "hyperdx": {
      "type": "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?

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

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

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

Использование в нескольких командах

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

Используйте инструмент просмотра списка команд в вашем MCP-клиенте, чтобы узнать, к каким командам у вас есть доступ и какая из них активна.

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

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

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

Срабатывает ограничение по частоте запросов

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

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

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

Не удаётся подключиться к MCP-серверу

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