MCP-сервер ЮKassa

MCP (Model Context Protocol) — открытый стандарт, по которому AI-приложения могут работать с инструментами внешних сервисов. С помощью MCP-сервера ЮKassa можно подключить возможности ЮKassa к AI-платформе или AI-агенту.

Через MCP-сервер можно создавать платежи и счета, получать информацию о платежах, счетах и возвратах, а также получать списки платежей и возвратов по заданным критериям. Например, вы можете попросить AI-агента создать платеж, а в ответ получить ссылку на страницу оплаты ЮKassa, затем отправить ее пользователю и принять оплату.

Работа с MCP-сервером строится вокруг взаимодействия AI-агента, AI-платформы и ЮKassa: агент выбирает подходящее действие, платформа отправляет запрос, а MCP-сервер выполняет операцию в ЮKassa и возвращает результат. Подробнее о работе с MCP-сервером:

Во взаимодействии с MCP-сервером ЮKassa есть несколько участников:

Для подключения AI-агентов к внешним системам используются MCP-серверы: они сообщают, какие действия доступны агенту во внешних сервисах. В MCP такие действия называются инструментами.

Инструмент — это отдельная операция, которую AI-агент может выполнить во внешнем сервисе: например, создать платеж, получить информацию о платеже или возврате, выставить счет. У каждого инструмента есть описание по правилам протокола MCP: для чего он нужен, какие данные требуются для выполнения операции и какой результат вернется.

Когда вы просите AI-агента выполнить действие, он выбирает подходящий инструмент и проверяет, достаточно ли данных для его использования. Если для инструмента не хватает обязательных данных, агент должен уточнить их у вас. Например, если вы попросили создать платеж, но не указали сумму, агент должен запросить ее у вас. После этого AI-платформа или AI-приложение вызывает выбранный инструмент, а MCP-сервер ЮKassa выполняет операцию и возвращает результат.

Результат выполнения вашего запроса зависит от модели, используемой в AI-агенте, настроек модели и переданного контекста. Если модель слабая (например, устаревшая), контекст слишком большой или инструкции сформулированы неоднозначно, агент может ошибиться, поэтому перед платежом рекомендуется проверять сумму и другие данные.

Для простых операций достаточно подключить MCP-сервер и сформулировать задачу в чате. При необходимости вы можете добавить инструкции, навык (скилл) или логику на своей стороне: например, чтобы агент получал данные из CRM, проверял товары по каталогу или возвращал результат в определенном формате.

MCP-сервер и API ЮKassa — разные инструменты для работы с платежами, счетами и возвратами в ЮKassa. Их можно использовать одновременно в одном магазине, но они отличаются способом подключения, форматом взаимодействия, данными для аутентификации и набором доступных операций.

Через MCP-сервер ЮKassa можно:

MCP-сервер принимает и возвращает только те данные, которые указаны в описании инструмента. Этот набор меньше, чем у соответствующего метода в API. Например, при создании платежа по сценарию Умный платеж через API нужно передать параметр return_url — адрес страницы, на которую вернется пользователь после оплаты. Инструмент создания платежа через MCP-сервер не принимает этот параметр. Подробнее об инструментах и данных

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

Чтобы снизить риск ошибочных или нежелательных операций, MCP-сервер поддерживает ограниченный набор возможностей. Часть опций API ЮKassa нельзя использовать через MCP-сервер. Например:

Через MCP-сервер можно передавать только те параметры, которые поддерживает выбранный инструмент. Если вам нужна другая возможность (например, автоплатежи), используйте API ЮKassa или другие платежные решения ЮKassa.

Через MCP-сервер можно создать платеж или счет. При создании платежа MCP-сервер возвращает ссылку на страницу оплаты, а при создании счета — ссылку на страницу счета. Все платежи, в том числе для оплаты выставленного счета, проходят по сценарию интеграции Умный платеж. Счет может действовать максимум 30 дней.

MCP-сервер создает платеж или счет и возвращает ссылку, которую можно отправить пользователю. Перед отправкой пользователю откройте ссылку и проверьте данные платежа:

Обычно процесс приема платежа выглядит так:

Если при создании платежа что-то пошло не так (например, в запросе на создание платежа нет обязательного параметра — суммы), ЮKassa вернет ошибку, и агент сможет вам о ней сообщить. Результат обработки ошибки зависит от модели, используемой в AI-агенте, и ее настроек.

При создании платежа или счета через MCP-сервер нельзя передавать данные для отправки чеков.

Вы можете формировать чеки самостоятельно, без участия ЮKassa. Для этого отключите отправку чеков в разделе Настройки — Онлайн-касса.

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

Вы можете получать информацию о них тремя способами:

Сделать возврат можно только в личном кабинете ЮKassa или по API. Через MCP-сервер нельзя создать возврат, но можно получить информацию о возврате или список возвратов.

По платежам, созданным через MCP-сервер, приходят стандартные реестры платежей.

Чтобы принимать платежи с помощью MCP-сервера ЮKassa, нужно:

MCP-сервер ЮKassa можно подключать к любым AI-агентам, AI-платформам и приложениям, которые поддерживают работу с MCP-серверами. Например, Cursor, Claude Code, Codex или OpenCode. Настройки подключения зависят от платформы. Общий принцип одинаковый: в настройках AI-платформы нужно указать URL MCP-сервера ЮKassa и настроить передачу данных для аутентификации. Подробнее о подключении и настройке MCP-сервера

При подключении MCP-сервера вы даете AI-платформе возможность выполнять операции от имени магазина. Через MCP-сервер можно создать платеж или счет, но деньги списываются только после того, как пользователь перейдет на страницу ЮKassa, проверит данные и подтвердит оплату. Операции, связанные со списанием денег без подтверждения (например, автоплатежи и создание возвратов), недоступны при работе с MCP-сервером.

Результат работы с MCP-сервером может отличаться в зависимости от модели, ее настроек и переданного контекста. Контролируйте операции через MCP-сервер: включайте подтверждение действий, если это поддерживает AI-платформа, и проверяйте историю или логи вызовов, если они доступны.

Перед отправкой пользователю ссылки на страницу оплаты или страницу счета проверяйте: