.. meta:: :description: Подключение MCP-сервера SBC к AI-агентам: пошаговое руководство по подключению stateless Streamable HTTP MCP-сервера SBC к Claude Desktop, Claude Code и другим AI-агентам с авторизацией по ограниченному токену доступа. .. _mcp_guide: MCP-сервер SBC ############################## .. role:: ex .. role:: code Введение -------------------------- Пошаговое руководство по подключению :ex:`stateless Streamable HTTP MCP-сервера` SBC к Claude Desktop, Claude Code и другим AI-агентам с авторизацией по ограниченному токену доступа. .. list-table:: :header-rows: 1 :widths: 28 72 * - Ключевые понятия - * - Эндпоинт production - ``https://gate.sbctech.ru/mcp-ui`` * - Authorization - ``Authorization: Bearer `` * - Транспорт - ``Streamable HTTP (stateless)`` * - Права токена - ``MCP Read Only`` .. note:: Сервер работает **только на чтение**. Токен ``MCP Read Only`` не может изменять состояние платформы — каждый доступный инструмент помечен ``readOnlyHint: true``. URL MCP-сервера -------------------------- Выберите эндпоинт, соответствующий вашей среде. Во всех примерах конфигурации в этом руководстве используется **production**-URL — при необходимости замените его на URL песочницы. .. list-table:: :header-rows: 1 :widths: 20 45 35 * - Среда - Эндпоинт MCP - Назначение * - **Production** - ``https://gate.sbctech.ru/mcp-ui`` - Реальный платёжный трафик * - **Sandbox** - ``https://sandbox.sbctech.ru/mcp-ui`` - Безопасное тестирование и интеграция .. warning:: Ограниченный токен доступа выпускается **отдельно для каждой среды**. Создавайте токен в профиле той среды, к которой собираетесь подключаться. Токен одной среды не будет работать в другой. Получение ограниченного токена доступа --------------------------------------- Доступ к MCP-серверу выполняется по Bearer-токену. В SBC используется **ограниченный токен доступа** — он даёт права только на выбранный набор операций. Для подключения MCP достаточно профиля ``MCP Read Only``. Шаг 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:: Токен показывается **только один раз**. Нажмите :code:`Скопировать в буфер обмена` и сохраните его в надёжном месте. Посмотреть значение повторно нельзя. Это длинная JWT-строка вида ``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 Обе команды должны вывести номер версии, например ``v20.11.0``. Если ``npx`` не найден, откройте терминал заново или перезагрузите компьютер. Настройка: через mcp-remote ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Расположение файла** Claude Desktop подключается к удалённым MCP-серверам через файл конфигурации. Поскольку сервер SBC использует HTTP-транспорт, он добавляется в секцию ``mcpServers``. .. 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:: Во всех конфигурациях ниже замените ```` на скопированное значение. Токен передаётся на сервер в заголовке ``Authorization: Bearer ``. .. rubric:: claude_desktop_config.json — mcp-remote .. code-block:: json { "mcpServers": { "SBC": { "command": "npx", "args": [ "-y", "mcp-remote", "https://gate.sbctech.ru/mcp-ui", "--header", "Authorization: Bearer " ] } } } Windows: устранение проблемы с запуском ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ В Windows запуск ``npx`` по абсолютному пути часто ломается из-за пробела в ``C:\Program Files\nodejs``. Решение — запускать его через ``cmd /c npx``, указав просто ``npx``: он берётся из ``PATH``, и пробел больше не ломает разбор аргументов: .. rubric:: claude_desktop_config.json — Windows .. code-block:: json { "mcpServers": { "SBC": { "command": "cmd", "args": [ "/c", "npx", "-y", "mcp-remote", "https://gate.sbctech.ru/mcp-ui", "--header", "Authorization: Bearer " ] } } } То есть ``command`` = ``cmd``, а ``npx`` становится первым аргументом после ``/c``. Итоговая командная строка — ``cmd /c npx -y mcp-remote …``, и пробел в «Program Files» больше не имеет значения. .. note:: Если проблема сохраняется, в качестве запасного варианта укажите короткий путь 8.3: ``"command": "C:\PROGRA~1\nodejs\npx.cmd"``. Но обычно достаточно варианта ``cmd /c npx``. Настройка: через HTTP ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Если версия Claude Desktop не поддерживает прямой HTTP-транспорт, используйте мост ``mcp-remote``: .. rubric:: claude_desktop_config.json .. code-block:: json { "mcpServers": { "SBC": { "type": "http", "url": "https://gate.sbctech.ru/mcp-ui", "headers": { "Authorization": "Bearer " } } } } .. note:: После сохранения файла **полностью перезапустите Claude Desktop**. Подключённый сервер появится в меню инструментов (иконка "🔌 / Search and tools"). Claude Code --------------------------------------- В Claude Code MCP-серверы добавляются одной командой ``claude mcp add`` или через файл ``.mcp.json`` в корне проекта. Через CLI ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Быстрее всего добавить HTTP-сервер вместе с заголовком авторизации: .. rubric:: Терминал .. code-block:: bash # transport http, server name SBC claude mcp add --transport http SBC \ https://gate.sbctech.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 SBC # server details Внутри сессии Claude Code статус проверяется командой ``/mcp``. Через файл проекта ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Чтобы сервер был доступен всей команде, добавьте ``.mcp.json`` в корень репозитория. Токен лучше не коммитить — вынесите его в переменную окружения: .. rubric:: .mcp.json .. code-block:: json { "mcpServers": { "SBC": { "type": "http", "url": "https://gate.sbctech.ru/mcp-ui", "headers": { "Authorization": "Bearer ${PAYNET_MCP_TOKEN}" } } } } .. rubric:: Терминал .. code-block:: bash export PAYNET_MCP_TOKEN="" .. note:: Claude Code подставляет ``${VAR}`` из окружения при запуске. ``.mcp.json`` коммитьте в репозиторий, а сам токен держите в локальном ``.env`` или менеджере секретов. Другие AI-агенты --------------------------------------- Принцип одинаков для всех клиентов: укажите эндпоинт ``https://gate.sbctech.ru/mcp-ui``, используйте транспорт **Streamable HTTP** и заголовок ``Authorization: Bearer ``. Ниже приведены готовые конфигурации для популярных агентов. Cursor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Файл: ``~/.cursor/mcp.json`` или ``.cursor/mcp.json`` в проекте. .. rubric:: .cursor/mcp.json .. code-block:: json { "mcpServers": { "SBC": { "url": "https://gate.sbctech.ru/mcp-ui", "headers": { "Authorization": "Bearer " } } } } Затем: **Settings → MCP → Enable** для сервера ``SBC``. VS Code (GitHub Copilot / Agent Mode) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Файл: ``.vscode/mcp.json``. .. rubric:: .vscode/mcp.json .. code-block:: json { "servers": { "SBC": { "type": "http", "url": "https://gate.sbctech.ru/mcp-ui", "headers": { "Authorization": "Bearer " } } } } Запустите сервер кнопкой *Start* над блоком в ``mcp.json`` или командой ``MCP: List Servers``. Cline · Windsurf · другие MCP-клиенты ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Большинство клиентов используют единый формат. Если клиент поддерживает только stdio, оберните HTTP-сервер в ``mcp-remote``: .. rubric:: настройки mcp (общий вид) .. code-block:: json { "mcpServers": { "SBC": { "command": "npx", "args": [ "-y", "mcp-remote", "https://gate.sbctech.ru/mcp-ui", "--header", "Authorization: Bearer " ] } } } Ручная проверка (curl) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Перед настройкой агента можно убедиться, что токен работает: .. rubric:: Терминал .. code-block:: bash curl https://gate.sbctech.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"}' В ответе должен прийти список доступных инструментов — значит, сервер и токен настроены верно. .. admonition:: Сводка параметров для любого агента :class: tip * **URL** — ``https://gate.sbctech.ru/mcp-ui`` * **Транспорт** — ``Streamable HTTP (stateless)`` * **Заголовок** — ``Authorization: Bearer `` * **Права токена** — ``MCP Read Only`` Доменная модель --------------------------------------- Сервер отдаёт доменную модель в поле ``instructions``, чтобы агент понимал связи между сущностями ещё до вызова инструментов. Ниже она приведена целиком. Заказы и транзакции ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * **Заказ** — это попытка покупки со стороны клиента. Он содержит одну или несколько **транзакций**: преавторизацию, списание, возврат, чарджбэк. * Статусы транзакций: **approved**, **declined** и **filtered** (*filtered* — заблокирована правилами фрод-мониторинга до обработки). Инструменты статистики ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Инструменты ``stats_*`` возвращают **агрегаты** (количества и суммы), но никогда не отдельные заказы. Для поиска конкретных заказов используйте ``orders_search``. .. list-table:: :widths: 25, 75 :header-rows: 1 :class: longtable * - Scope - Описание * - :code:`stats_get_transaction_timeseries` - Возвращает количество и сумму по временным интервалам (день / неделя / месяц) с разбивкой по статусу транзакции. * - :code:`stats_get_transaction_summary` - Возвращает продажи / отмены / чарджбэки / фроды / диспуты (количества, суммы и доли) за период с разбивкой по типу карты и общим итогом. * - :code:`stats_list_top_entities` - Ранжирует мерчантов / компании / процессоры по метрике за период (по убыванию); полученные идентификаторы можно передавать в инструменты ``*_get_details`` или использовать как фильтры статистики. * - :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``. * - :code:`orders_get_logs` - Возвращает стадии сессии обработки заказа (журнал) — каждую со своим сообщением; ``mode=UNLIMITED`` отдаёт полный набор. Разрешение идентификаторов ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Идентификаторы валют и типов карт получайте через ``refs_list_*``, а идентификаторы мерчантов, процессоров, менеджеров и т.д. — через инструменты ``*_search``, прежде чем использовать их как фильтры статистики.