# Подключить ИИ-агента

> Как дать ИИ-агенту (Claude, Cursor или своему) доступ к стоп-листам Stoplist.Tech через MCP: токен агента, уровни «Чтение» и «Стоп-лист», подключение, инструменты, безопасность.

ИИ-агент, например Claude или Cursor, может работать со Stoplist.Tech от вашего имени: отвечать, что сейчас в стопе, разбирать историю и упущенную выручку, ставить блюда на стоп и снимать их. Агент подключается к серверу Stoplist.Tech по протоколу [MCP](https://modelcontextprotocol.io) с токеном, который вы выпускаете в профиле.

> **В разработке**
>
> Подключение агентов появится в следующей версии. Шаги ниже описывают, как это будет работать.
## Что умеет агент

Агент понимает обычные просьбы и сам выбирает, что посмотреть или сделать. Например:

* «Что сейчас в стопе на Невском?»
* «Какие блюда чаще всего вставали в стоп за октябрь и сколько выручки мы на этом потеряли?»
* «Сколько стоял в стопе борщ на прошлой неделе и почему?»
* «Закончилась свёкла на Садовой — что встанет в стоп? Поставь».
* «Верни в продажу хачапури во всех ресторанах, где он в стопе».

Аналитики, закупок, отчётов в Excel, настроек и управления сотрудниками у агента нет.

## Уровни доступа

Агент действует от имени сотрудника, выпустившего токен, и **никогда не получает больше, чем сам сотрудник**: те же рестораны и те же действия, что разрешает его [роль](https://docs.stoplist.tech/access/roles). Токен может только сузить это.

| Уровень | Что может агент |
|---------|-----------------|
| Чтение | Смотреть рестораны, стоп-лист, историю, блюда, причины, стопы по ингредиенту, упущенную выручку и топ блюд в стопе. Ничего не меняет |
| Стоп-лист | Всё, что «Чтение», и ещё: ставить блюда на стоп, менять остаток, снимать стоп, ставить и снимать [стоп по ингредиенту](https://docs.stoplist.tech/plugin/ingredient-stops) |

При выпуске можно выбрать рестораны: агент будет видеть только их. Если ничего не выбрать, агент видит все ваши рестораны.

Если роль сотрудника потом изменится или его отключат, агент сразу потеряет те же права.

## Выпустить токен

1. Откройте **Профиль → ИИ-агенты**.
2. Нажмите **Выпустить токен**.
3. Назовите токен так, чтобы потом понять, где он стоит: «Claude у управляющего», «Cursor на ноутбуке бара».
4. Выберите уровень, при необходимости рестораны и срок действия: 30, 90, 180 или 365 дней.
5. Скопируйте токен и адрес сервера. Токен начинается с `slt_` и **показывается один раз**: Stoplist.Tech хранит только его отпечаток и показать токен снова не сможет. Потеряли — отзовите и выпустите новый.

У одного сотрудника может быть до 10 действующих токенов. В списке видно, когда токен последний раз использовался.

## Отозвать токен

В **Профиль → ИИ-агенты** нажмите **Отозвать** у токена или **Отозвать все**. Агент перестанет работать со следующего запроса. Свой токен можно отозвать всегда, даже если роль больше не разрешает выпускать новые.

Администратор сети видит токены всех сотрудников на странице **ИИ-агенты** в настройках: кто выпустил, уровень, рестораны, когда использовался, — и может отозвать любой.

Токен перестаёт работать и сам: когда истёк срок, сотрудника отключили или тариф перестал включать подключение агентов.

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

Адрес сервера: `https://api.stoplist.tech/mcp`. Токен передаётся в заголовке `Authorization: Bearer slt_…`. Ниже вместо `slt_…` подставьте свой токен.

### Claude Code

```bash
claude mcp add --transport http stoplist https://api.stoplist.tech/mcp --header "Authorization: Bearer slt_…"
```

Проверьте командой `claude mcp list`: у `stoplist` должно быть «connected».

### Claude Desktop

Claude Desktop подключается к удалённому серверу с токеном через мост `mcp-remote` (нужен Node.js). Откройте **Settings → Developer → Edit Config** и добавьте в `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "stoplist": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.stoplist.tech/mcp", "--header", "Authorization:${STOPLIST_AUTH}"],
      "env": { "STOPLIST_AUTH": "Bearer slt_…" }
    }
  }
}
```

Перезапустите Claude Desktop.

### Cursor

В `~/.cursor/mcp.json` (или `.cursor/mcp.json` проекта):

```json
{
  "mcpServers": {
    "stoplist": {
      "url": "https://api.stoplist.tech/mcp",
      "headers": { "Authorization": "Bearer slt_…" }
    }
  }
}
```

### Свой агент

Сервер работает по транспорту MCP Streamable HTTP без сессий: каждый запрос — `POST /mcp` с JSON-RPC, ответ — JSON (без SSE). Подойдёт любой клиент MCP, который умеет передавать заголовок `Authorization`. Без токена или с недействительным токеном сервер отвечает `401`.

## Инструменты

| Инструмент | Уровень | Что делает | Пример просьбы |
|------------|---------|------------|----------------|
| `list_restaurants` | Чтение | Рестораны, сколько в стопе, на связи ли плагин; для одного ресторана — его кассы (группы терминалов) | «Какие рестораны сейчас без связи с плагином?» |
| `get_stoplist` | Чтение | Текущий стоп-лист ресторана: остатки, кассы, с какого времени, причина, кто поставил | «Что в стопе на Невском?» |
| `search_products` | Чтение | Поиск блюд ресторана по названию | «Найди все борщи на Невском» |
| `stoplist_history` | Чтение | История стоп-листа за период | «Что вставало в стоп вчера вечером?» |
| `list_reasons` | Чтение | [Причины](https://docs.stoplist.tech/stoplists/reasons) стопа сети | «Какие у нас есть причины стопа?» |
| `search_ingredients` | Чтение | Поиск ингредиентов из техкарт | «Найди ингредиент свёкла» |
| `preview_ingredient_stop` | Чтение | Что встанет в стоп, если закончился ингредиент | «Что встанет, если кончится сливочный соус?» |
| `list_ingredient_stops` | Чтение | Действующие стопы по ингредиенту | «Какие стопы по ингредиенту сейчас стоят?» |
| `lost_revenue` | Чтение | Оценка [упущенной выручки](https://docs.stoplist.tech/analytics/lost-revenue) за период | «Сколько мы потеряли из-за стопов в октябре?» |
| `top_products` | Чтение | Блюда, чаще всего бывшие в стопе | «Топ-10 блюд в стопе за месяц» |
| `stop_product` | Стоп-лист | Поставить блюда на стоп, можно с причиной | «Поставь борщ на стоп на Невском, причина — нет свёклы» |
| `set_remaining` | Стоп-лист | Изменить остаток позиции в стоп-листе | «Хачапури осталось 5 штук» |
| `unstop_product` | Стоп-лист | Вернуть позиции в продажу | «Верни борщ в продажу» |
| `stop_ingredient` | Стоп-лист | Стоп по ингредиенту | «Кончилась свёкла на Садовой, поставь всё со свёклой» |
| `release_ingredient_stop` | Стоп-лист | Снять стоп по ингредиенту | «Свёклу привезли, снимай стоп» |

Команды на стоп и снятие уходят в [плагин](https://docs.stoplist.tech/plugin/quick-start) на кассе, как из веб-приложения: стоп-лист обновится через несколько секунд. Если плагин кассы не на связи, агент скажет об этом.

Ограничения:

* за один раз агент меняет не больше 50 позиций;
* не больше 20 изменений стоп-листа в минуту и 60 запросов к серверу в минуту на токен;
* очистить весь стоп-лист ресторана разом агент не может — только перечисленные позиции.

## Безопасность

* **Храните токен как пароль.** Не вставляйте его в переписку и общие документы. Токен работает только для подключения агентов: войти с ним на сайт или в приложение нельзя.
* **Давайте минимум.** Агенту, который только отвечает на вопросы, хватит уровня «Чтение». Ограничьте рестораны, если агент нужен для одного.
* **Проверяйте изменения.** Агент может ошибиться или выполнить чужую инструкцию из текста, который ему показали. Перед тем как разрешать агенту ставить и снимать стопы, включите в клиенте подтверждение действий — так вы увидите каждое изменение до того, как оно уйдёт на кассу.
* **Всё в журнале.** Каждое изменение агента записывается в [журнал](https://docs.stoplist.tech/audit) с вашим именем и отметкой «через агента «название токена»», а в стоп-листе у позиции видно, кто поставил стоп: «Иван Петров · через агента «Claude у управляющего»». В журнале можно отобрать действия конкретного агента.

## Тариф

Подключение ИИ-агентов входит в тариф [«Аналитика и Управление»](https://docs.stoplist.tech/pricing#тариф-аналитика-и-управление). Выпускать токены может сотрудник, которому роль разрешает управлять токенами агентов: у администратора сети это право есть.

---
Раздел: Настройки. Источник: https://docs.stoplist.tech/settings/ai-agents