# Подключить к Claude и ChatGPT

> Как подключить BILLZ к своему ассистенту — Claude, ChatGPT, Cursor и другим — и задавать вопросы о продажах, остатках и долгах.

BILLZ можно подключить к ИИ-ассистенту, которым вы уже пользуетесь: Claude, ChatGPT, Cursor и другим. После подключения ассистент отвечает на вопросы о вашей компании по данным из BILLZ:

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

Ассистент только читает данные: он ничего не меняет в BILLZ, не проводит продажи и не трогает остатки.

Эта страница — для владельцев и сотрудников компании. Если вы разработчик и хотите, чтобы агент писал код к API BILLZ, вам нужна [настройка ИИ-агента](/agent-setup/).

## Перед началом: ключ интеграции

Ассистент заходит в BILLZ по ключу интеграции. Создайте его в BILLZ: **Настройки → Настройки компании → Ключи интеграции**. Подробнее — в разделе [Ключ интеграции](/start/integration-key/).

Заведите под ассистента отдельный ключ, а не тот, которым пользуются ваши интеграции. Если ключ придётся перевыпустить, доступ закроется только ассистенту, а кассы, сайт и другие подключения продолжат работать.

Ассистент видит только то, что разрешено ключу: если у роли ключа нет доступа к отчётам или клиентам, ассистент их тоже не увидит.

## Подключение

Во всех приложениях подключение устроено одинаково:

1. В приложение добавляется адрес `https://mcp.billz.io/mcp` — без ключа.
2. Приложение открывает страницу BILLZ в браузере. Вставьте на ней ключ интеграции.
3. BILLZ показывает, какие данные просит приложение. Отметьте группы, которые разрешаете читать, и нажмите «Разрешить».
4. Браузер возвращает вас в приложение — можно задавать вопросы.

![Подключение по шагам: адрес https://mcp.billz.io/mcp в приложении, ключ интеграции на странице BILLZ, выбор данных и кнопка «Разрешить», вопрос ассистенту](/_astro/flow-ru.DXgD_aBU_wi1su.webp)

Ниже — где в каждом приложении добавить адрес.

### Claude Desktop и claude.ai

1. Откройте **Настроить → Коннекторы** (Customize → Connectors) и нажмите **Добавить свой коннектор** (Add custom connector).
2. Название — `BILLZ`, адрес — `https://mcp.billz.io/mcp`. Если Claude спрашивает способ входа, выберите **Sign in now**, а для OAuth-клиента — **Register automatically** (автоматическая регистрация). Нажмите **Добавить** (Add).
3. Нажмите **Подключить** (Connect) у нового коннектора и пройдите вход на странице BILLZ.

Коннектор, добавленный на claude.ai или в Claude Desktop, работает и в мобильном приложении Claude. На бесплатном тарифе можно добавить один свой коннектор. В тарифах Team и Enterprise свой коннектор добавляет владелец организации: **Настройки организации → Коннекторы** (Organization settings → Connectors) → **Add** → **Custom** → **Web**. После этого каждый сотрудник находит BILLZ в **Customize → Connectors** и нажимает **Connect**.

### ChatGPT

1. Откройте ChatGPT в браузере, раздел **Плагины** (Plugins) — адрес `chatgpt.com/plugins`. Нажмите **+** и выберите **Add custom MCP server**.
2. Название — `BILLZ`, адрес сервера (Server URL) — `https://mcp.billz.io/mcp`, вход (Authentication) — **OAuth**. Если ChatGPT предлагает выбрать способ регистрации клиента, выберите DCR (Dynamic Client Registration).
3. Подтвердите предупреждение (**I understand and want to continue**) и нажмите **Create as a plugin**.
4. Установите созданный плагин и пройдите вход на странице BILLZ, когда ChatGPT её откроет. В новом чате введите `@` и выберите BILLZ.

Свои MCP-серверы подключаются только в веб-версии ChatGPT, и эта возможность зависит от тарифа и настроек рабочего пространства: если пункта **Add custom MCP server** нет, спросите администратора рабочего пространства.

### Cursor

1. Откройте файл `~/.cursor/mcp.json` (серверы для всех проектов) или создайте `.cursor/mcp.json` в папке проекта.

2. Добавьте сервер:

   ```json
   {
     "mcpServers": {
       "billz": { "url": "https://mcp.billz.io/mcp" }
     }
   }
   ```

3. Сохраните файл и перезапустите Cursor. Откройте **Customize → MCPs**, найдите `billz` и пройдите вход: Cursor откроет страницу BILLZ.

### VS Code

1. Выполните команду **MCP: Open User Configuration** — сервер будет доступен во всех проектах. Или создайте в проекте файл `.vscode/mcp.json`.

2. Добавьте сервер:

   ```json
   {
     "servers": {
       "billz": { "type": "http", "url": "https://mcp.billz.io/mcp" }
     }
   }
   ```

3. Нажмите **Start** над сервером в файле (или выполните **MCP: List Servers** → `billz` → **Start**) и подтвердите вход: VS Code откроет страницу BILLZ. Вопросы задаются в чате Copilot.

### Claude Code

```bash
claude mcp add --transport http billz https://mcp.billz.io/mcp
```

Затем в Claude Code выполните `/mcp`, выберите `billz` и пройдите вход в браузере. То же можно сделать из терминала: `claude mcp login billz`.

### Codex

```bash
codex mcp add billz --url https://mcp.billz.io/mcp
codex mcp login billz
```

### Gemini CLI

Добавьте сервер в `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "billz": { "httpUrl": "https://mcp.billz.io/mcp" }
  }
}
```

Затем в Gemini CLI выполните `/mcp auth billz`.

## Какие данные видит ассистент

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

| Группа                                    | Что сможет читать ассистент                                                     |
| ----------------------------------------- | ------------------------------------------------------------------------------- |
| Продажи и финансы                         | выручка, чеки, прибыль, оплаты; лучшие товары, маржа и оборачиваемость          |
| Товары и остатки                          | товары, цены, остатки; поиск по названию, артикулу и штрихкоду, остатки на дату |
| Клиенты и долги — **персональные данные** | имена, телефоны, покупки и долги клиентов                                       |

Всегда доступны: список магазинов и способов оплаты, название компании ключа.

Ассистент ничего не меняет в BILLZ: только чтение. Компания определяется ключом — ассистент не может прочитать данные другой компании. Чтобы поменять набор групп, отключите BILLZ в приложении и подключите заново.

## Как отозвать доступ

* **Отключите BILLZ в приложении**: удалите коннектор или сервер в настройках. Закрывается только это подключение.
* **Перевыпустите ключ в BILLZ**: Настройки → Настройки компании → Ключи интеграции. Закрываются все подключения, сделанные с этим ключом, — во всех приложениях сразу. Чтобы вернуть доступ, подключитесь заново с новым ключом.

## Если не работает

| Что видите                                | Что сделать                                                                                           |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| «Ключ не подошёл»                         | Скопируйте ключ целиком, без пробелов. Если ключ перевыпускали, возьмите новый.                       |
| «Ссылка устарела»                         | Страница входа действует 10 минут. Начните подключение в приложении заново.                           |
| «Слишком много попыток»                   | Подождите несколько минут и попробуйте снова.                                                         |
| Приложение не открывает браузер           | Проверьте, что браузер по умолчанию задан. В Claude Code ссылку входа можно скопировать из терминала. |
| Ассистент пишет, что доступа к данным нет | Проверьте права роли ключа и группы, отмеченные при подключении.                                      |
| Приложение снова просит войти             | Ключ перевыпустили или подключение не использовалось 30 дней. Подключитесь заново.                    |

### Приложения без входа по OAuth

Если приложение не умеет входить по OAuth или подключение нужно для скрипта, ключ передаётся в заголовке `X-Billz-Token`. Например, в Claude Code:

```bash
claude mcp add --transport http billz \
  --header "X-Billz-Token: <КЛЮЧ ИНТЕГРАЦИИ>" \
  https://mcp.billz.io/mcp
```

Для приложений, которые подключают серверы только командой, подходит мост `mcp-remote`. Остальные способы — в [описании сервера](https://github.com/billz-2/billz_public_api/tree/main/mcp).

Ключ в заголовке даёт ассистенту все группы данных. Не публикуйте файлы настроек с ключом: если ключ попал к посторонним, перевыпустите его.

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

* Ключ интеграции вводится только на странице BILLZ и хранится на сервере BILLZ в зашифрованном виде. Приложению ассистента ключ не передаётся: оно получает собственный доступ, который можно отозвать.
* Доступ действует 30 дней и продлевается, пока ассистентом пользуются.
* Компания определяется ключом: ассистент видит только магазины и данные компании, которой выдан ключ.
* Только чтение: ассистент не может создать продажу, изменить цену или остаток.