.. meta:: :description: Подключение MCP-сервера Payneteasy к AI-агентам: пошаговое руководство по подключению stateless Streamable HTTP MCP-сервера Payneteasy к Claude Desktop, Claude Code и другим AI-агентам с авторизацией по ограниченному токену доступа. .. _mcp_guide: MCP-сервер Payneteasy ############################## .. role:: ex .. role:: code Введение -------------------------- A step-by-step guide to connecting the Payneteasy :ex:`stateless Streamable HTTP MCP server` to Claude Desktop, Claude Code and other AI agents, authenticated with a restricted access token. .. list-table:: :header-rows: 1 :widths: 28 72 * - Ключевые понятия - * - Эндпоинт production - ``https://gate.payneteasy.ru/mcp-ui`` * - Authorization - ``Authorization: Bearer `` * - Транспорт - ``Streamable HTTP (stateless)`` * - Права токена - ``MCP Read Only`` .. note:: The server is **read-only**. A ``MCP Read Only`` token cannot mutate platform state — every exposed tool is annotated ``readOnlyHint: true``. URL MCP-сервера -------------------------- Pick the endpoint that matches your environment. The configuration examples throughout this guide use the **production** URL — replace it with the sandbox URL when needed. .. list-table:: :header-rows: 1 :widths: 20 45 35 * - Среда - Эндпоинт MCP - Назначение * - **Production** - ``https://gate.payneteasy.ru/mcp-ui`` - Реальный платёжный трафик * - **Sandbox** - ``https://sandbox.payneteasy.ru/mcp-ui`` - Безопасное тестирование и интеграция .. warning:: The restricted access token is issued **per environment**. Create the token in the profile of the same environment you intend to connect to. A token from one environment will not work on another. Получение ограниченного токена доступа --------------------------------------- Access to the MCP server uses a Bearer token. Payneteasy uses a **restricted access token** — it grants rights only to a selected set of operations. The ``MCP Read Only`` profile is enough to connect MCP. Шаг 1 — Откройте профиль пользователя ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Перейдите в раздел *Ограниченные токены*: :code:`Профиль` → :code:`Ограниченные токены`. .. figure:: _static/images/screen-1.png :alt: Профиль пользователя с разделом «Ограниченные токены» :width: 100% Шаг 2 — Нажмите «Создать токен» ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Чтобы создать токен, нажмите кнопку :code:`Создать токен` в правом верхнем углу страницы «Ограниченные токены». .. figure:: _static/images/screen-2.png :alt: Страница «Ограниченные токены» с кнопкой «Создать токен» :width: 100% Шаг 3 — Заполните параметры токена ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 35 65 * - Поле - Значение * - Название - любое название токена, например ``mcp-1`` (1) * - Срок действия в днях - до ``180`` * - Права доступа - отметьте флажок ``MCP Read Only`` (2) .. figure:: _static/images/screen-3.png :alt: Форма создания токена с названием, сроком действия и флажком MCP Read Only :width: 100% Шаг 4 — Создайте и скопируйте токен ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Нажмите :code:`Создать токен` (справа вверху формы), затем скопируйте значение токена и сохраните его. .. figure:: _static/images/screen-4.png :alt: Окно с созданным токеном и кнопкой «Скопировать в буфер обмена» :width: 100% .. warning:: The token is shown **only once**. Click :code:`Copy to clipboard` and store it safely. The value cannot be viewed again. It is a long JWT string of the form ``eyJ…``. Claude Desktop --------------------------------------- Чтобы подключение к MCP прошло успешно, сначала установите **Node.js**. .. rubric:: Установка Node.js 1. Скачайте LTS-установщик для вашей операционной системы с `nodejs.org `_. 2. Запустите установщик, оставив параметры по умолчанию. 3. Перезапустите терминал (и Claude Desktop), чтобы подхватился новый ``PATH``. 4. Проверьте установку: .. code-block:: bash node -v npx -v Both commands should print a version number, e.g. ``v20.11.0``. If ``npx`` is not found, reopen the terminal or restart the computer. Настройка: через mcp-remote ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Расположение файла** Claude Desktop connects to remote MCP servers through a configuration file. Since Payneteasy server uses an HTTP transport, it is added to the ``mcpServers`` section. .. list-table:: :header-rows: 1 :widths: 20 80 * - OS - Путь * - macOS - ``~/Library/Application Support/Claude/claude_desktop_config.json`` * - Windows - ``%APPDATA%\Claude\claude_desktop_config.json`` | Его также можно открыть из приложения: :code:`Settings` → :code:`Developer` → :code:`Edit Config`. | Затем **закройте приложение Claude**. .. note:: In every configuration below, replace ```` with the value you copied. The token is sent to the server in the ``Authorization: Bearer `` header. .. rubric:: claude_desktop_config.json — mcp-remote .. code-block:: json { "mcpServers": { "Payneteasy": { "command": "npx", "args": [ "-y", "mcp-remote", "https://gate.payneteasy.ru/mcp-ui", "--header", "Authorization: Bearer " ] } } } Windows: устранение проблемы с запуском ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ On Windows, launching ``npx`` by an absolute path often breaks because of the space in ``C:\Program Files\nodejs``. The fix is to run it through ``cmd /c npx`` with a bare ``npx`` — it is picked up from ``PATH``, so the space no longer breaks argument parsing: .. rubric:: claude_desktop_config.json — Windows .. code-block:: json { "mcpServers": { "Payneteasy": { "command": "cmd", "args": [ "/c", "npx", "-y", "mcp-remote", "https://gate.payneteasy.ru/mcp-ui", "--header", "Authorization: Bearer " ] } } } That is, ``command`` = ``cmd``, and ``npx`` becomes the first argument after ``/c``. The resulting command line is ``cmd /c npx -y mcp-remote …``, and the space in "Program Files" no longer matters. .. note:: If it still misbehaves, as a fallback specify the 8.3 short path: ``"command": "C:\PROGRA~1\nodejs\npx.cmd"``. But the ``cmd /c npx`` variant is usually enough. Настройка: через HTTP ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Если версия Claude Desktop не поддерживает прямой HTTP-транспорт, используйте мост ``mcp-remote``: .. rubric:: claude_desktop_config.json .. code-block:: json { "mcpServers": { "Payneteasy": { "type": "http", "url": "https://gate.payneteasy.ru/mcp-ui", "headers": { "Authorization": "Bearer " } } } } .. note:: After saving the file, **fully restart Claude Desktop**. The connected server appears in the tools menu (the "🔌 / Search and tools" icon). Claude Code --------------------------------------- In Claude Code, MCP servers are added with a single ``claude mcp add`` command or via a ``.mcp.json`` file in the project root. Через CLI ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Быстрее всего добавить HTTP-сервер вместе с заголовком авторизации: .. rubric:: Терминал .. code-block:: bash # transport http, server name Payneteasy claude mcp add --transport http Payneteasy \ https://gate.payneteasy.ru/mcp-ui \ --header "Authorization: Bearer " Видимость задаётся флагом ``--scope``: .. list-table:: :header-rows: 1 :widths: 20 80 * - Scope - Описание * - ``local`` - только для вас в текущем проекте (по умолчанию) * - ``project`` - в ``.mcp.json``, доступен команде через git * - ``user`` - доступен во всех проектах Проверка подключения ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. rubric:: Терминал .. code-block:: bash claude mcp list # list servers and their status claude mcp get Payneteasy # server details Внутри сессии Claude Code статус проверяется командой ``/mcp``. Через файл проекта ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To make the server available to the whole team, add a ``.mcp.json`` to the repository root. It's best not to commit the token — move it to an environment variable: .. rubric:: .mcp.json .. code-block:: json { "mcpServers": { "Payneteasy": { "type": "http", "url": "https://gate.payneteasy.ru/mcp-ui", "headers": { "Authorization": "Bearer ${PAYNET_MCP_TOKEN}" } } } } .. rubric:: Терминал .. code-block:: bash export PAYNET_MCP_TOKEN="" .. note:: Claude Code expands ``${VAR}`` from the environment at startup. Commit ``.mcp.json`` to the repository, and keep the token itself in a local ``.env`` / secret manager. Другие AI-агенты --------------------------------------- The principle is the same for every client: point to the endpoint ``https://gate.payneteasy.ru/mcp-ui``, use the **Streamable HTTP** transport, and the ``Authorization: Bearer `` header. Below are concrete configurations for popular agents. Cursor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Файл: ``~/.cursor/mcp.json`` или ``.cursor/mcp.json`` в проекте. .. rubric:: .cursor/mcp.json .. code-block:: json { "mcpServers": { "Payneteasy": { "url": "https://gate.payneteasy.ru/mcp-ui", "headers": { "Authorization": "Bearer " } } } } Затем: **Settings → MCP → Enable** для сервера ``Payneteasy``. VS Code (GitHub Copilot / Agent Mode) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Файл: ``.vscode/mcp.json``. .. rubric:: .vscode/mcp.json .. code-block:: json { "servers": { "Payneteasy": { "type": "http", "url": "https://gate.payneteasy.ru/mcp-ui", "headers": { "Authorization": "Bearer " } } } } Start the server via the *Start* button above the block in ``mcp.json`` or with the ``MCP: List Servers`` command. Cline · Windsurf · другие MCP-клиенты ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Most clients use a single format. If a client only supports stdio, wrap the HTTP server with ``mcp-remote``: .. rubric:: настройки mcp (общий вид) .. code-block:: json { "mcpServers": { "Payneteasy": { "command": "npx", "args": [ "-y", "mcp-remote", "https://gate.payneteasy.ru/mcp-ui", "--header", "Authorization: Bearer " ] } } } Ручная проверка (curl) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Перед настройкой агента можно убедиться, что токен работает: .. rubric:: Терминал .. code-block:: bash curl https://gate.payneteasy.ru/mcp-ui \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' The response should contain the list of available tools — that means the server and token are configured correctly. .. admonition:: Сводка параметров для любого агента :class: tip * **URL** — ``https://gate.payneteasy.ru/mcp-ui`` * **Транспорт** — ``Streamable HTTP (stateless)`` * **Заголовок** — ``Authorization: Bearer `` * **Права токена** — ``MCP Read Only`` Доменная модель --------------------------------------- The server ships a domain model in its ``instructions`` field so an agent knows how the entities relate before it calls any tool. The model is reproduced here. Заказы и транзакции ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * An **order** is a customer purchase attempt. It contains one or more **transactions**: pre-authorization, capture, refund, chargeback. * Transaction statuses are **approved**, **declined** and **filtered** (*filtered* = blocked by fraud-prevention rules before processing). Инструменты статистики ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``stats_*`` tools return **aggregates** (counts and amounts) — never individual orders. Use ``orders_search`` to find specific orders. .. list-table:: :widths: 25, 75 :header-rows: 1 :class: longtable * - Scope - Описание * - :code:`stats_get_transaction_timeseries` - Возвращает количество и сумму по временным интервалам (день / неделя / месяц) с разбивкой по статусу транзакции. * - :code:`stats_get_transaction_summary` - Возвращает продажи / отмены / чарджбэки / фроды / диспуты (количества, суммы и доли) за период с разбивкой по типу карты и общим итогом. * - :code:`stats_get_breakdown` - Разбивает метрику за период (столбчатая диаграмма) по статусу транзакции, стране банка-эмитента или IP, а также по причине отказа / чарджбэка / фрода. Фильтры те же, что и у инструмента временных рядов. Инструменты заказов ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 25, 75 :header-rows: 1 :class: longtable * - Scope - Описание * - :code:`orders_get_details` - Возвращает один заказ по идентификатору: сводку по заказу и транзакциям, метаданные карты и маскированные контакты клиента. Разделы отображаются только для тех API заказа, которые доступны токену. * - :code:`orders_search` - Ищет заказы по периоду изменения с необязательными фильтрами по статусу и сущностям и с постраничной выдачей; возвращает безопасные сводки заказов. Для полной информации по одному заказу используйте ``orders_get_details``. Разрешение идентификаторов ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Идентификаторы валют и типов карт получайте через ``refs_list_*``.