Подключение и настройка MCP-сервера ЮKassa

В этой статье описано, как выпустить токен, подключить MCP-сервер ЮKassa к AI-платформе и проверить доступные инструменты.

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

Совместимость

MCP-сервер ЮKassa работает по Streamable HTTP. Обмен сообщениями проходит по JSON-RPC 2.0.

Платформа должна поддерживать подключение внешнего MCP-сервера по Streamable HTTP и передачу заголовка Authorization. Протокольные запросы, в том числе tools/list и tools/call, AI-платформа или приложение отправляет самостоятельно: вручную формировать JSON-RPC не нужно.

Общий порядок подключения

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

Общий порядок подключения:

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

Магазин ЮKassa

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

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

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

Токен для доступа к MCP-серверу

Выпуск токена

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

Если в разделе Интеграция — Доступы к магазину отсутствует блок Токены для MCP-сервера, проверьте, отключена ли отправка чеков в разделе Настройки — Онлайн-касса. При создании платежа или счета через MCP-сервер нельзя передавать данные для отправки чеков.

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

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

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

Для MCP-сервера и API ЮKassa используются разные данные для аутентификации. Токен MCP-сервера нельзя использовать для запросов к API. Для обычных запросов к API используются shopId и секретный ключ, которые не подходят для подключения к MCP-серверу. Подробнее об аутентификации запросов к API ЮKassa

Хранение токена

Храните токен в хранилище секретов, защищенных настройках приложения или переменной окружения.

Не добавляйте токен:

в инструкции и запросы для AI-агента;
в открытые файлы и репозитории;
в публичные конфигурации;
в cookie браузера.

В конфигурации указывайте не фактическое значение токена, а обращение к переменной окружения или защищенному хранилищу.

Конфигурация

Общая конфигурация

Независимо от AI-платформы, для подключения понадобятся:

URL MCP-сервера

https://mcp.yookassa.ru

Значение заголовка Authorization

Bearer <ваш токен для MCP-сервера>

В примерах используется переменная окружения YOOKASSA_MCP_TOKEN. Синтаксис обращения к переменной и возможность подстановки секретов зависят от AI-платформы.

Пример общей структуры настроек

JSON

{
  "name": "yookassa",
  "transport": "http",
  "url": "https://mcp.yookassa.ru",
  "headers": {
    "Authorization": "Bearer ${YOOKASSA_MCP_TOKEN}"
  }
}

Не вставляйте фактическое значение токена в конфигурацию, которую можно опубликовать или передать другим пользователям.

Разделение потоков платежей

Если вы разделяете поток платежей в рамках одного аккаунта (shopId), передавайте идентификатор нужного субаккаунта в заголовке Mcp-Param-Gateway-Id или в параметре gateway_id при создании платежа или счета. Это значение соответствует параметру recipient.gateway_id в API ЮKassa. Подробнее об идентификаторе субаккаунта

Mcp-Param-Gateway-Id — это HTTP-заголовок в конфигурации подключения MCP-сервера. Значение заголовка — идентификатор субаккаунта, который вы получили от менеджера ЮKassa. MCP-сервер использует его при создании платежей и счетов.

Пример конфигурации с идентификатором субаккаунта

JSON

{
  "name": "yookassa",
  "transport": "http",
  "url": "https://mcp.yookassa.ru",
  "headers": {
    "Authorization": "Bearer ${YOOKASSA_MCP_TOKEN}",
    "Mcp-Param-Gateway-Id": "123456"
  }
}

Рекомендуется использовать заголовок Mcp-Param-Gateway-Id: так идентификатор субаккаунта не потребуется передавать для каждого платежа или счета.

Если вы не разделяете поток платежей, вам не нужно передавать идентификатор субаккаунта в запросах на создание платежа или в заголовке Mcp-Param-Gateway-Id.

Примеры для AI-платформ

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

Пример команды для подключения в Claude Code

cURL

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

Если вы настраиваете подключение через JSON-конфигурацию, добавьте MCP-сервер.

Пример JSON-конфигурации для Claude Code

JSON

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

Проверьте подключение командой claude mcp list или командой /mcp в Claude Code.

Проверка подключения

После настройки откройте список MCP-серверов или инструментов в AI-платформе. Убедитесь, что MCP-сервер ЮKassa подключен и AI-платформа получила доступные инструменты.

Чтобы проверить создание и получение информации о платеже, используйте Быстрый старт.

Подробнее о доступных инструментах и параметрах — в разделе Инструменты MCP-сервера.

Что почитать еще

Основы работы с MCP-сервером

Быстрый старт с MCP-сервером

Инструменты MCP-сервера

Формат взаимодействия с API ЮKassa

Тестирование платежей