> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-3a82795f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP-сервер ClickStack

> Подключайте ИИ-ассистентов к ClickStack с помощью сервера Model Context Protocol (MCP)

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

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

Благодаря этому вы можете использовать такие инструменты, как [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://www.cursor.com/), или любой клиент, совместимый с MCP, чтобы расследовать инциденты, создавать панели мониторинга и управлять вашей системой обсервабилити, не покидая среду разработки.

<div id="availability">
  ## Доступность
</div>

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

| Развертывание                                     | Статус               |
| ------------------------------------------------- | -------------------- |
| **Open Source ClickStack**                        | Доступно             |
| **BYOC (Собственное облако)**                     | Доступно             |
| **Управляемый ClickStack**                        | Скоро будет доступно |
| **HyperDX v1** ([hyperdx.io](https://hyperdx.io)) | Не поддерживается    |

<Info>
  **Управляемый ClickStack**

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

<div id="prerequisites">
  ## Предварительные требования
</div>

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

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

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-3a82795f/aRvsybqUpVR5ZXyi/images/clickstack/api-key-personal.png?fit=max&auto=format&n=aRvsybqUpVR5ZXyi&q=85&s=72cc1e86a82b0078bfafd1fb338ebfb4" alt="Personal API Access Key в разделе Team Settings" size="md" border width="3798" height="1938" data-path="images/clickstack/api-key-personal.png" />

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

<div id="endpoint">
  ## Конечная точка
</div>

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

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

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

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

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

<div id="connecting-a-client">
  ## Подключение MCP-клиента
</div>

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

<div id="claude-code">
  ### Claude code
</div>

```shell theme={null}
claude mcp add --transport http hyperdx <YOUR_CLICKSTACK_URL>/api/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"
```

<div id="cursor">
  ### Cursor
</div>

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

```json theme={null}
{
  "mcpServers": {
    "hyperdx": {
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}
```

<div id="opencode">
  ### OpenCode
</div>

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

```json theme={null}
{
  "mcp": {
    "hyperdx": {
      "type": "http",
      "url": "<YOUR_CLICKSTACK_URL>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}
```

<div id="other-clients">
  ### Другие клиенты
</div>

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

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

<div id="capabilities">
  ## Что можно делать с MCP?
</div>

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

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

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

<div id="multi-team">
  ## Использование в нескольких командах
</div>

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

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

<div id="troubleshooting">
  ## Устранение неполадок
</div>

<Accordion title="Я получаю ошибку аутентификации 403">
  * Убедитесь, что вы используете **Personal API Access Key** (а не ключ API для приёма данных).
  * Убедитесь, что ключ передаётся как токен `Bearer` в заголовке `Authorization`.
  * Проверьте, что ваш экземпляр ClickStack запущен и доступен по указанному URL.
</Accordion>

<Accordion title="Я сталкиваюсь с ограничением частоты запросов">
  MCP-сервер ограничивает частоту запросов до **600 запросов в минуту** на пользователя. Если вы превысите этот лимит, запросы будут временно отклоняться. Уменьшите частоту запросов или подождите перед повторной попыткой.
</Accordion>

<Accordion title="Я получаю ошибку 401 с заголовком x-hdx-team">
  Убедитесь, что идентификатор команды указан верно и что ваша учётная запись входит в эту команду.
</Accordion>

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