8. MCP-сервер Payneteasy

8.1. Введение

Пошаговое руководство по подключению stateless Streamable HTTP MCP-сервера Payneteasy к Claude Desktop, Claude Code и другим AI-агентам с авторизацией по ограниченному токену доступа.

Ключевые понятия

Эндпоинт production

https://gate.payneteasy.ru/mcp-ui

Authorization

Authorization: Bearer <token>

Транспорт

Streamable HTTP (stateless)

Права токена

MCP Read Only

Примечание

Сервер работает только на чтение. Токен MCP Read Only не может изменять состояние платформы — каждый доступный инструмент помечен readOnlyHint: true.

8.2. URL MCP-сервера

Выберите эндпоинт, соответствующий вашей среде. Во всех примерах конфигурации в этом руководстве используется production-URL — при необходимости замените его на URL песочницы.

Среда

Эндпоинт MCP

Назначение

Production

https://gate.payneteasy.ru/mcp-ui

Реальный платёжный трафик

Sandbox

https://sandbox.payneteasy.ru/mcp-ui

Безопасное тестирование и интеграция

Предупреждение

Ограниченный токен доступа выпускается отдельно для каждой среды. Создавайте токен в профиле той среды, к которой собираетесь подключаться. Токен одной среды не будет работать в другой.

8.3. Получение ограниченного токена доступа

Доступ к MCP-серверу выполняется по Bearer-токену. В Payneteasy используется ограниченный токен доступа — он даёт права только на выбранный набор операций. Для подключения MCP достаточно профиля MCP Read Only.

Шаг 1 — Откройте профиль пользователя

Перейдите в раздел Ограниченные токены: Профиль → Ограниченные токены.

Профиль пользователя с разделом «Ограниченные токены»

Шаг 2 — Нажмите «Создать токен»

Чтобы создать токен, нажмите кнопку Создать токен в правом верхнем углу страницы «Ограниченные токены».

Страница «Ограниченные токены» с кнопкой «Создать токен»

Шаг 3 — Заполните параметры токена

Поле

Значение

Название

любое название токена, например mcp-1 (1)

Срок действия в днях

до 180

Права доступа

отметьте флажок MCP Read Only (2)
Форма создания токена с названием, сроком действия и флажком MCP Read Only

Шаг 4 — Создайте и скопируйте токен

Нажмите Создать токен (справа вверху формы), затем скопируйте значение токена и сохраните его.

Окно с созданным токеном и кнопкой «Скопировать в буфер обмена»

Предупреждение

Токен показывается только один раз. Нажмите Скопировать в буфер обмена и сохраните его в надёжном месте. Посмотреть значение повторно нельзя. Это длинная JWT-строка вида eyJ….

8.4. Claude Desktop

Чтобы подключение к MCP прошло успешно, сначала установите Node.js.

Установка Node.js

  1. Скачайте LTS-установщик для вашей операционной системы с nodejs.org.

  2. Запустите установщик, оставив параметры по умолчанию.

  3. Перезапустите терминал (и Claude Desktop), чтобы подхватился новый PATH.

  4. Проверьте установку:

    node -v
npx -v

    Обе команды должны вывести номер версии, например v20.11.0. Если npx не найден, откройте терминал заново или перезагрузите компьютер.

Настройка: через mcp-remote

Расположение файла

Claude Desktop подключается к удалённым MCP-серверам через файл конфигурации. Поскольку сервер Payneteasy использует HTTP-транспорт, он добавляется в секцию mcpServers.

OS

Путь

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json
Его также можно открыть из приложения: Settings → Developer → Edit Config.
Затем закройте приложение Claude.

Примечание

Во всех конфигурациях ниже замените <ACCESS_TOKEN> на скопированное значение. Токен передаётся на сервер в заголовке Authorization: Bearer <ACCESS_TOKEN>.

claude_desktop_config.json — mcp-remote

{
  "mcpServers": {
    "Payneteasy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://gate.payneteasy.ru/mcp-ui",
        "--header",
        "Authorization: Bearer <ACCESS_TOKEN>"
      ]
    }
  }
}

Windows: устранение проблемы с запуском

В Windows запуск npx по абсолютному пути часто ломается из-за пробела в C:\Program Files\nodejs. Решение — запускать его через cmd /c npx, указав просто npx: он берётся из PATH, и пробел больше не ломает разбор аргументов:

claude_desktop_config.json — Windows

{
  "mcpServers": {
    "Payneteasy": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "https://gate.payneteasy.ru/mcp-ui",
        "--header",
        "Authorization: Bearer <ACCESS_TOKEN>"
      ]
    }
  }
}

То есть command = cmd, а npx становится первым аргументом после /c. Итоговая командная строка — cmd /c npx -y mcp-remote …, и пробел в «Program Files» больше не имеет значения.

Примечание

Если проблема сохраняется, в качестве запасного варианта укажите короткий путь 8.3: "command": "C:\PROGRA~1\nodejs\npx.cmd". Но обычно достаточно варианта cmd /c npx.

Настройка: через HTTP

Если версия Claude Desktop не поддерживает прямой HTTP-транспорт, используйте мост mcp-remote:

claude_desktop_config.json

{
  "mcpServers": {
    "Payneteasy": {
      "type": "http",
      "url": "https://gate.payneteasy.ru/mcp-ui",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>"
      }
    }
  }
}

Примечание

После сохранения файла полностью перезапустите Claude Desktop. Подключённый сервер появится в меню инструментов (иконка «🔌 / Search and tools»).

8.5. Claude Code

В Claude Code MCP-серверы добавляются одной командой claude mcp add или через файл .mcp.json в корне проекта.

Через CLI

Быстрее всего добавить HTTP-сервер вместе с заголовком авторизации:

Терминал

# transport http, server name Payneteasy
claude mcp add --transport http Payneteasy \
  https://gate.payneteasy.ru/mcp-ui \
  --header "Authorization: Bearer <ACCESS_TOKEN>"

Видимость задаётся флагом --scope:

Scope

Описание

local

только для вас в текущем проекте (по умолчанию)

project

в .mcp.json, доступен команде через git

user

доступен во всех проектах

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

Терминал

claude mcp list           # list servers and their status
claude mcp get Payneteasy # server details

Внутри сессии Claude Code статус проверяется командой /mcp.

Через файл проекта

Чтобы сервер был доступен всей команде, добавьте .mcp.json в корень репозитория. Токен лучше не коммитить — вынесите его в переменную окружения:

.mcp.json

{
  "mcpServers": {
    "Payneteasy": {
      "type": "http",
      "url": "https://gate.payneteasy.ru/mcp-ui",
      "headers": {
        "Authorization": "Bearer ${PAYNET_MCP_TOKEN}"
      }
    }
  }
}

Терминал

export PAYNET_MCP_TOKEN="<ACCESS_TOKEN>"

Примечание

Claude Code подставляет ${VAR} из окружения при запуске. .mcp.json коммитьте в репозиторий, а сам токен держите в локальном .env или менеджере секретов.

8.6. Другие AI-агенты

Принцип одинаков для всех клиентов: укажите эндпоинт https://gate.payneteasy.ru/mcp-ui, используйте транспорт Streamable HTTP и заголовок Authorization: Bearer <ACCESS_TOKEN>. Ниже приведены готовые конфигурации для популярных агентов.

Cursor

Файл: ~/.cursor/mcp.json или .cursor/mcp.json в проекте.

.cursor/mcp.json

{
  "mcpServers": {
    "Payneteasy": {
      "url": "https://gate.payneteasy.ru/mcp-ui",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>"
      }
    }
  }
}

Затем: Settings → MCP → Enable для сервера Payneteasy.

VS Code (GitHub Copilot / Agent Mode)

Файл: .vscode/mcp.json.

.vscode/mcp.json

{
  "servers": {
    "Payneteasy": {
      "type": "http",
      "url": "https://gate.payneteasy.ru/mcp-ui",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>"
      }
    }
  }
}

Запустите сервер кнопкой Start над блоком в mcp.json или командой MCP: List Servers.

Cline · Windsurf · другие MCP-клиенты

Большинство клиентов используют единый формат. Если клиент поддерживает только stdio, оберните HTTP-сервер в mcp-remote:

настройки mcp (общий вид)

{
  "mcpServers": {
    "Payneteasy": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://gate.payneteasy.ru/mcp-ui",
        "--header",
        "Authorization: Bearer <ACCESS_TOKEN>"
      ]
    }
  }
}

Ручная проверка (curl)

Перед настройкой агента можно убедиться, что токен работает:

Терминал

curl https://gate.payneteasy.ru/mcp-ui \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

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

Сводка параметров для любого агента

  • URL — https://gate.payneteasy.ru/mcp-ui

  • Транспорт — Streamable HTTP (stateless)

  • Заголовок — Authorization: Bearer <ACCESS_TOKEN>

  • Права токена — MCP Read Only

8.7. Доменная модель

Сервер отдаёт доменную модель в поле instructions, чтобы агент понимал связи между сущностями ещё до вызова инструментов. Ниже она приведена целиком.

Заказы и транзакции

  • Заказ — это попытка покупки со стороны клиента. Он содержит одну или несколько транзакций: преавторизацию, списание, возврат, чарджбэк.

  • Статусы транзакций: approved, declined и filtered (filtered — заблокирована правилами фрод-мониторинга до обработки).

Инструменты статистики

Инструменты stats_* возвращают агрегаты (количества и суммы), но никогда не отдельные заказы. Для поиска конкретных заказов используйте orders_search.

Scope

Описание

stats_get_transaction_timeseries

Возвращает количество и сумму по временным интервалам (день / неделя / месяц) с разбивкой по статусу транзакции.

stats_get_transaction_summary

Возвращает продажи / отмены / чарджбэки / фроды / диспуты (количества, суммы и доли) за период с разбивкой по типу карты и общим итогом.

stats_get_breakdown

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

Инструменты заказов

Scope

Описание

orders_get_details

Возвращает один заказ по идентификатору: сводку по заказу и транзакциям, метаданные карты и маскированные контакты клиента. Разделы отображаются только для тех API заказа, которые доступны токену.

orders_search

Ищет заказы по периоду изменения с необязательными фильтрами по статусу и сущностям и с постраничной выдачей; возвращает безопасные сводки заказов. Для полной информации по одному заказу используйте orders_get_details.

Разрешение идентификаторов

Идентификаторы валют и типов карт получайте через refs_list_*.