MCP-сервер ЮKassa — подключение к AI-агенту

Создавайте платежные ссылки и счета, проверяйте платежи и получайте данные о возвратах прямо в чате с агентом.

Это инструкция подключения к MCP-серверу ЮKassa. Сервер работает на стороне ЮKassa: разворачивать его у себя и устанавливать дополнительные пакеты не требуется.

Быстрый старт: получите токен → добавьте его в окружение → выберите Codex, Claude Code, Cursor или OpenCode → проверьте подключение.

1. Получите токен

В личном кабинете ЮKassa откройте Интеграция → Доступы к магазину → Токены для MCP-сервера и выпустите токен. Это доступно Владельцу и Управляющему. Сохраните значение сразу: повторно посмотреть его нельзя.

Для знакомства используйте тестовый магазин. Операции со счетами в тестовом магазине недоступны.

Нужен именно MCP-токен. shopId и секретный ключ API для этого подключения не подходят. Если блока токенов нет, проверьте условия его доступности и настройки отправки чеков в официальной инструкции.

2. Добавьте токен в окружение

Все примеры используют переменную YOOKASSA_MCP_TOKEN. Введите токен локально на своем компьютере. Для Bash и Zsh на macOS/Linux:

printf 'Токен MCP ЮKassa: '
read -r -s YOOKASSA_MCP_TOKEN
printf '\n'
export YOOKASSA_MCP_TOKEN

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

Для Windows задайте переменную через настройки среды или хранилище секретов используемого агента. Примеры конфигурации ниже одинаковы для разных ОС.

Переменная должна быть доступна процессу агента. export в терминале не передает ее автоматически уже открытому приложению. Сам по себе файл .env также не гарантирует загрузку токена.

3. Подключите своего агента

| Агент | Быстрый способ | Готовый файл | | --- | --- | --- | | Codex | Команда codex mcp add | TOML | | Claude Code | Команда claude mcp add-json | JSON | | Cursor | Добавить запись в mcp.json | JSON | | OpenCode | Добавить запись в opencode.json | JSON |

Сохраните остальные настройки и уже подключенные MCP-серверы. Если файл существует, добавьте в него только запись yookassa в соответствующем разделе.

Codex

Выполните команду:

codex mcp add yookassa --url https://mcp.yookassa.ru --bearer-token-env-var YOOKASSA_MCP_TOKEN

Альтернатива — добавьте в ~/.codex/config.toml содержимое готового файла:

[mcp_servers.yookassa]
url = "https://mcp.yookassa.ru"
bearer_token_env_var = "YOOK…[redacted]"

Используйте один из двух способов. bearer_token_env_var содержит имя переменной, а Codex сам добавляет Bearer к ее значению. Запустите новую сессию codex из терминала с токеном; в ней команда /mcp показывает активные серверы. codex mcp list показывает сохраненные настройки, но сам по себе не доказывает доступность инструментов.

При использовании приложения или IDE убедитесь, что токен доступен их процессу. Документация Codex.

Claude Code

Запустите в каталоге проекта:

claude mcp add-json yookassa '{"type":"http","url":"https://mcp.yookassa.ru","headers":{"Authorization":"Bearer ${YOOKASSA_MCP_TOKEN}"}}'

Одинарные кавычки сохраняют ссылку на переменную в настройках. Затем запустите claude из терминала с токеном и проверьте сервер через /mcp.

Альтернатива для общей конфигурации проекта — файл .mcp.json с содержимым этого примера. Включение проектных серверов может потребовать подтверждения в Claude Code. Документация Claude Code.

Cursor

Добавьте в ~/.cursor/mcp.json для всех проектов или в .cursor/mcp.json для текущего проекта:

{
  "mcpServers": {
    "yookassa": {
      "url": "https://mcp.yookassa.ru",
      "headers": {
        "Authorization": "Bearer ${env:YOOKASSA_MCP_TOKEN}"
      }
    }
  }
}

Готовый JSON. В Cursor используется синтаксис ${env:YOOKASSA_MCP_TOKEN}. Полностью завершите Cursor, затем запустите его из терминала с токеном командой cursor ., если команда Cursor установлена. Проверьте статус сервера в настройках MCP.

У удаленных серверов Cursor параметр envFile не поддерживается; используйте окружение процесса. Документация Cursor.

OpenCode

Добавьте в opencode.json проекта:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "yookassa": {
      "type": "remote",
      "url": "https://mcp.yookassa.ru",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:YOOKASSA_MCP_TOKEN}"
      }
    }
  }
}

Готовый JSON. Запустите opencode из терминала с токеном и проверьте подключение командой opencode mcp list. Здесь используется синтаксис {env:YOOKASSA_MCP_TOKEN}, а oauth: false отключает автоматическую OAuth-авторизацию: ЮKassa использует выпущенный MCP-токен. Документация OpenCode.

Другой агент

Если ваш клиент поддерживает Streamable HTTP и пользовательские HTTP-заголовки, используйте:

| Параметр | Значение | | --- | --- | | Адрес сервера | https://mcp.yookassa.ru | | Транспорт | Streamable HTTP | | Заголовок | Authorization: Bearer <значение MCP-токена> |

Настройте передачу токена через секреты клиента. Единого JSON для всех агентов нет: отличаются структура настроек и синтаксис переменных. Общие параметры ЮKassa.

4. Проверьте подключение

Напишите агенту:

Покажи инструменты подключенного MCP-сервера ЮKassa.
Ничего не создавай и не изменяй.

Агент получает набор операций через tools/list. Для настоящего магазина сейчас есть семь инструментов:

| Инструмент | Действие | | --- | --- | | create_payment | Создать платеж и получить ссылку на оплату | | get_payment | Проверить платеж по идентификатору | | get_payments_list | Получить платежи с фильтрами | | create_invoice | Выставить счет | | get_invoice | Проверить счет | | get_refund | Получить информацию о возврате | | get_refunds_list | Получить список возвратов |

Фактическую доступность определяет ответ сервера. В тестовом магазине инструменты счетов недоступны. Справочник инструментов.

Первый платеж в тестовом магазине

Убедитесь, что подключен токен тестового магазина, и отправьте запрос:

Создай тестовый платеж на 10.00 RUB.
Описание: «Тест оплаты через MCP».
Верни идентификатор, сумму, статус и ссылку на оплату.

Откройте ссылку, проверьте данные и используйте тестовые способы оплаты. Затем попросите:

Проверь через get_payment платеж с идентификатором <ID созданного платежа>.
Покажи текущие статус и сумму.

Ссылка на оплату не означает, что платеж выполнен. Успех подтверждает статус succeeded, полученный при проверке платежа. Порядок описан в быстром старте ЮKassa.

Что поддерживает сервер

MCP позволяет создавать одностадийные платежи и счета, читать данные о платежах, счетах и возвратах. Возврат денег через MCP создать нельзя: это делается в личном кабинете или через API.

Передача данных для чеков, автоплатежи, двухстадийные платежи, выплаты, сплитование и «Безопасная сделка» в этот набор возможностей не входят. Организацию чеков нужно учитывать отдельно при выборе способа интеграции. Возможности и ограничения.

Примеры запросов

Покажи успешные платежи за вчера по московскому времени.
Получи все страницы результатов и посчитай сумму отдельно по каждой валюте.

Проверь платеж <ID>: статус, сумма и описание.
Если данные недоступны, сообщи об этом.

Найди возвраты по платежу <ID> и покажи их статусы и суммы.

Для сценариев с созданием платежей или счетов можно добавить в инструкции агента:

Перед созданием покажи магазин, сумму, валюту и назначение и дождись подтверждения.
Для счета также проверь состав корзины и срок действия.
Используй только инструменты и параметры, которые доступны в подключении.
Если исход операции неизвестен из-за ошибки, сообщи об этом; не создавай дубликат автоматически.
Сообщай об успешной оплате только после проверки статуса платежа.
Не выводи токены в чат, файлы проекта или логи.

Это рекомендуемая инструкция для агента, а не техническое ограничение сервера.

Если подключение не работает

| Симптом | Что проверить | | --- | --- | | Ошибка авторизации | MCP-токен действует и не отозван; процесс агента видит переменную; используется синтаксис своего клиента | | Сервер отсутствует | Запись добавлена в нужный файл; начата новая сессия агента | | Подключение есть, инструмента нет | Получите текущий список инструментов; проверьте тип магазина и ограничения MCP | | Не получается работать со счетами | Используется настоящий магазин: в тестовом операции со счетами недоступны |

Не публикуйте токен в GitHub и не вставляйте его в запросы агенту. При утечке отзовите токен в кабинете ЮKassa. Правила хранения токена.