Перейти к содержимому

Интеграция через ИИ (MCP)

MCP-сервер документации АТОЛ Pay - одна команда, и Claude, Cursor или VS Code пишут интеграцию по актуальной документации.

MCP (Model Context Protocol) - открытый протокол, позволяющий ИИ-ассистентам подключаться к внешним источникам данных и инструментам. Мы упаковали всю документацию этого портала в MCP-сервер: подключите его к своему ИИ-ассистенту, и он сможет искать по документации, читать описания методов, коды ошибок и примеры - а значит, писать интеграцию с АТОЛ Pay и АТОЛ Онлайн за вас и без галлюцинаций.

Это шаг 1, если идете с ассистентом

Подключение занимает одну команду и не требует ни токенов, ни доступов в личный кабинет. Пишете код сами? Этот шаг пропускается - сразу к шагу 2: нужна ли вам своя фискализация или к ручному маршруту в быстром старте.

Что это дает

  • Интеграция в диалоге. «Подключи оплату АТОЛ Pay к моему Express-приложению» - ассистент сам найдет нужные методы, параметры и напишет код по актуальной документации.
  • Точные ответы. Ассистент отвечает не по памяти, а по документации: форматы полей, коды ошибок, ограничения (например, лимит длины orderId для разных банков).
  • Отладка. Вставьте ошибку PARTIAL_REFUND_IS_NOT_POSSIBLE - ассистент найдет ее в справочнике и объяснит, что частичный возврат невозможен на первой стадии двухстадийного платежа.

Быстрое подключение

Сервер работает на нашей стороне по Streamable HTTP: скачивать, собирать и запускать ничего не нужно - ассистент подключается по адресу https://pay.atol.ru/mcp. Версия документации всегда актуальная, обновлять нечего.

bash
claude mcp add --transport http atol-docs https://pay.atol.ru/mcp

Что нужно от вашей среды

Только доступ в интернет к https://pay.atol.ru/mcp по HTTPS. Node.js, Docker и локальные процессы не требуются - если ассистент запущен в контейнере или на удаленной машине, разрешите исходящие запросы к этому адресу.

Учетные данные

Инструменты документации работают без настройки. Живые вызовы API включаются заголовками подключения: в Claude Code - флаг --header, в конфигах остальных клиентов - блок headers.

ЗаголовокНазначение
X-Atol-Pay-TokenТокен АТОЛ Pay (ЛК > Настройки > API Токены) - включает create_payment, check_payment_status, get_receipt_dictionaries. Префикс Bearer сервер подставляет сам
X-Atol-Pay-Base-UrlБаза API АТОЛ Pay. По умолчанию - sandbox https://croc-sandbox-api-mobile.atolpay.ru
X-Atol-Allow-Live1 - разрешить боевую среду и денежные инструменты (cancel_payment, deposit_payment). По умолчанию отключено
X-Atol-Online-Login / X-Atol-Online-Pass / X-Atol-Online-GroupДоступ к АТОЛ Онлайн v5 - включает get_fiscal_report
X-Atol-Kkt-Login / X-Atol-Kkt-PassДоступ к сервису ККТ и ФН - включает get_kkt_info (по умолчанию берутся из X-Atol-Online-*)

Подключение с sandbox-токеном в Claude Code:

bash
claude mcp add --transport http atol-docs https://pay.atol.ru/mcp \
  --header "X-Atol-Pay-Token: <sandbox-токен>"

То же самое в конфиге Claude Desktop, Cursor или VS Code:

json
{
  "mcpServers": {
    "atol-docs": {
      "type": "http",
      "url": "https://pay.atol.ru/mcp",
      "headers": {
        "X-Atol-Pay-Token": "<sandbox-токен>"
      }
    }
  }
}

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

Не давайте ассистенту боевые токены без необходимости. Защита двухуровневая:

  • инструменты cancel_payment и deposit_payment всегда требуют X-Atol-Allow-Live: 1 - даже на sandbox;
  • любой вызов к не-тестовому адресу (X-Atol-Pay-Base-Url с боевым API) тоже требует X-Atol-Allow-Live: 1, иначе сервер откажет до отправки запроса.

Без X-Atol-Allow-Live сервер работает только на тестовых контурах и только на неденежных операциях. Заголовки хранятся в конфиге ассистента на вашей машине - не коммитьте .cursor/mcp.json и .vscode/mcp.json с токенами в репозиторий.

Дальше