> ## Documentation Index
> Fetch the complete documentation index at: https://polza.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP-сервер

> Подключение AI-агентов к аккаунту Polza.AI через Model Context Protocol

MCP (Model Context Protocol) — открытый стандарт, который позволяет AI-агентам взаимодействовать с внешними сервисами через структурированные инструменты. MCP-сервер Polza.AI даёт вашему агенту доступ к управлению аккаунтом: баланс, API-ключи, организации, история генераций и другое.

<Note>
  MCP-сервер работает в режиме бета-тестирования. Возможны изменения в API и ограничениях.
</Note>

## Требования

* Аккаунт [Polza.AI](https://polza.ai/dashboard) с пополненным балансом
* AI-агент с поддержкой MCP (Claude Code, Cursor, Cline, Windsurf и др.)

## Создание токена

<Steps>
  <Step title="Откройте раздел MCP">
    Перейдите в [polza.ai/dashboard/mcp](https://polza.ai/dashboard/mcp) и нажмите «Создать токен».
  </Step>

  <Step title="Настройте токен">
    Укажите название (например, «Claude Code» или «Cursor») и выберите нужные разрешения. Для быстрого старта используйте пресет «Только чтение» или «Разработчик».
  </Step>

  <Step title="Скопируйте токен">
    После создания скопируйте токен и сохраните его в надёжном месте. Он отображается **только один раз**.
  </Step>
</Steps>

<Warning>
  Токен даёт AI-агенту доступ к вашему аккаунту в рамках выбранных разрешений. Не передавайте его третьим лицам и не добавляйте в публичные репозитории.
</Warning>

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

<Steps>
  <Step title="Добавьте MCP-сервер">
    Выполните команду в терминале:

    ```bash theme={null}
    claude mcp add --transport http polza-ai https://polza.ai/api/mcp \
      --header "Authorization: Bearer <ваш-токен>"
    ```

    Замените `<ваш-токен>` на токен из предыдущего шага.
  </Step>

  <Step title="Проверьте подключение">
    Запустите Claude Code и попросите агента проверить ваш баланс или список организаций. Если MCP-сервер подключён корректно, агент получит данные из вашего аккаунта.
  </Step>
</Steps>

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

<Steps>
  <Step title="Создайте конфигурацию">
    В корне проекта создайте файл `.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "polza-ai": {
          "type": "http",
          "url": "https://polza.ai/api/mcp",
          "headers": {
            "Authorization": "Bearer <ваш-токен>"
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Перезапустите Cursor">
    После сохранения файла перезапустите Cursor. MCP-сервер появится в списке доступных инструментов.
  </Step>
</Steps>

<Warning>
  Добавьте `.cursor/mcp.json` в `.gitignore`, чтобы токен не попал в репозиторий.
</Warning>

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

Для любого MCP-клиента с поддержкой HTTP-транспорта используйте:

| Параметр    | Значение                            |
| ----------- | ----------------------------------- |
| URL         | `https://polza.ai/api/mcp`          |
| Транспорт   | HTTP (Streamable HTTP)              |
| Авторизация | `Authorization: Bearer <ваш-токен>` |

## Доступные инструменты

После подключения AI-агент получает доступ к инструментам в зависимости от выбранных разрешений.

| Группа          | Инструменты                                                                          | Описание                                                 |
| --------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| **Профиль**     | `get_profile`, `get_balance`, `list_organizations`, `switch_organization`            | Информация об аккаунте, баланс, переключение организации |
| **Организации** | `get_organization`, `list_org_members`, `create_organization`, `invite_member` и др. | Управление организациями и участниками                   |
| **API-ключи**   | `list_api_keys`, `create_api_key`, `update_api_key`, `delete_api_key`                | Создание и управление ключами                            |
| **Биллинг**     | `get_balance_details`, `get_transaction_history`, `create_topup_link`                | Баланс, транзакции, пополнение                           |
| **История**     | `list_generations`, `get_generation`                                                 | Метаданные генераций (без промптов)                      |
| **Подсказки**   | Системные промпты                                                                    | Контекстные подсказки для агента                         |

## Разрешения (Scopes)

Каждый токен имеет набор разрешений, определяющих какие инструменты доступны агенту. Разрешения следуют формату `ресурс.уровень`:

| Скоуп            | Уровень | Описание                                     |
| ---------------- | ------- | -------------------------------------------- |
| `profile.read`   | Чтение  | Email, ID, список организаций, баланс        |
| `profile.write`  | Запись  | Переключение активной организации            |
| `orgs.read`      | Чтение  | Просмотр организаций и участников            |
| `orgs.write`     | Запись  | Создание организаций, приглашение участников |
| `orgs.danger`    | Опасные | Удаление организаций и участников            |
| `keys.read`      | Чтение  | Список API-ключей                            |
| `keys.write`     | Запись  | Создание и обновление ключей                 |
| `keys.danger`    | Опасные | Безвозвратное удаление ключей                |
| `billing.read`   | Чтение  | Баланс и история транзакций                  |
| `billing.write`  | Запись  | Создание ссылки на пополнение                |
| `billing.danger` | Опасные | Списание с карты без подтверждения           |
| `history.read`   | Чтение  | Метаданные генераций                         |

### Пресеты

Для удобства при создании токена доступны готовые наборы:

| Пресет                   | Скоупы                                                                   |
| ------------------------ | ------------------------------------------------------------------------ |
| **Только чтение**        | `profile.read`, `orgs.read`, `keys.read`, `billing.read`, `history.read` |
| **Разработчик**          | Чтение + `keys.write`, `billing.write`                                   |
| **Полный (без опасных)** | Все скоупы кроме `*.danger`                                              |

<Note>
  Скоупы уровня «Опасные» (`*.danger`) дают агенту возможность выполнять необратимые действия: удаление ключей, организаций, списание средств. Включайте их только если вы уверены в необходимости.
</Note>

## Управление токенами

* **Просмотр** — все активные токены отображаются на странице [MCP](https://polza.ai/dashboard/mcp) с датой создания и последнего использования
* **Отзыв** — нажмите «Отозвать» рядом с токеном. Действие необратимо — агент немедленно потеряет доступ
* **Срок действия** — при создании можно указать дату истечения. После неё токен перестанет работать автоматически

## Решение проблем

<AccordionGroup>
  <Accordion title="Ошибка аутентификации (401)">
    * Убедитесь что токен скопирован полностью, без лишних пробелов
    * Проверьте что токен не был отозван на странице [MCP](https://polza.ai/dashboard/mcp)
    * Если указан срок действия — убедитесь что токен не истёк
  </Accordion>

  <Accordion title="Инструмент не найден (tool not available)">
    * Проверьте что у токена есть соответствующий скоуп. Например, для `list_api_keys` нужен скоуп `keys.read`
    * Создайте новый токен с нужными разрешениями
  </Accordion>

  <Accordion title="Превышен лимит запросов (rate limit)">
    * Операции записи ограничены 60 запросами в минуту
    * Опасные операции ограничены 5 запросами за 10 минут
    * Подождите и повторите запрос
  </Accordion>

  <Accordion title="MCP-сервер не подключается">
    * Убедитесь что используете URL `https://polza.ai/api/mcp`
    * Проверьте что заголовок авторизации передаётся в формате `Authorization: Bearer <токен>`
    * Убедитесь что ваш клиент поддерживает HTTP-транспорт (Streamable HTTP)
  </Accordion>
</AccordionGroup>

## Следующие шаги

<CardGroup cols={2}>
  <Card title="Claude Code" icon="terminal" href="/docs/integracii/claude-code">
    Настройте Claude Code для работы через Polza.AI
  </Card>

  <Card title="Начало работы" icon="rocket" href="/docs/gaidy/getting-started">
    Создайте API-ключ и пополните баланс
  </Card>
</CardGroup>