Перейти к содержимому
Интеграции
Открыть .md
На странице

MCP-сервер

Подключите Claude Code, Cursor или любой MCP-клиент к локальному серверу Paymos — агент соберёт интеграцию: инвойсы, симуляция оплаты, проверка вебхуков.

@paymos/mcp подключает вашего агента к песочнице Paymos. Локальный сервер работает по протоколу MCP: агент получает шесть инструментов и пять страниц документации, чтобы создавать тестовые инвойсы, проверять сценарии оплаты и подписи вебхуков при разработке интеграции.

Что понадобится

Подключение клиента

Выполните в терминале:

npx -y @paymos/mcp setup

Выберите свой клиент и введите тестовую пару ключей. При вводе секрет не виден на экране. Если нужна проверка подписи вебхуков, укажите и секрет вебхуков; этот шаг можно пропустить. Вместо ввода setup умеет брать значения из переменных окружения PAYMOS_API_KEY_ID, PAYMOS_API_SECRET и необязательной PAYMOS_WEBHOOK_SECRET.

Клиент можно сразу указать в команде:

npx -y @paymos/mcp setup --client codex
Клиент Значение --client Файл по умолчанию
Codex codex $CODEX_HOME/config.toml или ~/.codex/config.toml
Claude Code claude-code ~/.claude.json
Claude Desktop claude-desktop Конфигурация Claude в macOS или Windows
Kimi CLI kimi $KIMI_CODE_HOME/mcp.json или ~/.kimi-code/mcp.json
Cursor cursor ~/.cursor/mcp.json
Windsurf windsurf ~/.codeium/windsurf/mcp_config.json
OpenCode opencode OPENCODE_CONFIG или пользовательская конфигурация
VS Code vscode .vscode/mcp.json в текущей папке
Другой клиент generic Путь обязателен: --config PATH

Если клиент читает настройки из другого файла, передайте его путь через --config PATH. Для Claude Desktop в ОС, отличной от macOS и Windows, путь тоже нужно указать. В Cline, Roo Code или собственном клиенте сначала найдите файл настроек MCP, затем запустите setup с --client generic --config PATH.

Ключи сохраняются отдельно: в $XDG_CONFIG_HOME/paymos/mcp/credentials.json, а если XDG_CONFIG_HOME не задана — в ~/.config/paymos/mcp/credentials.json. Другую папку или имя файла можно выбрать через --credentials-file PATH. В настройках клиента будет только переменная PAYMOS_CREDENTIALS_FILE с путём к этому файлу. Сам файл с ключами храните вне проекта и не добавляйте в Git.

Чтобы посмотреть, какие изменения подготовит команда, добавьте --dry-run:

npx -y @paymos/mcp setup --client codex --dry-run
npx -y @paymos/mcp setup --help

В режиме предварительного просмотра файлы не меняются, секреты в вывод не попадают. Повторный запуск с теми же данными не дублирует запись. Если существующая запись Paymos или файл ключей отличаются, setup остановится, чтобы вы могли проверить конфликт. Остальные серверы, комментарии, выбранные модели и настройки клиента сохраняются. Старая запись Paymos с ключами в переменных окружения тоже вызовет конфликт: автоматически переносить такие ключи setup не будет.

После настройки перезапустите клиент или переподключите MCP-сервер. Проверьте, что Paymos появился в списке серверов, и дайте агенту задание создать тестовый инвойс и симулировать оплату. Сервер работает по stdio, не открывает сетевых портов и обращается к Merchant API через официальный SDK.

Клиент и модель настраиваются отдельно. Kimi CLI — самостоятельный клиент со своим файлом конфигурации. Модели GLM, Kimi и другие можно использовать через MCP-клиент, если и клиент, и выбранная модель поддерживают вызов инструментов. Одного названия модели для совместимости недостаточно. Например, инструкция Z.ai описывает GLM в Claude Code: после выбора модели подключите Paymos в самом Claude Code.

Ручная настройка

Если хотите добавить сервер вручную, создайте JSON-файл с ключами вне проекта:

{
  "apiKeyId": "pk_test_…",
  "apiSecret": "sk_test_…",
  "webhookSecret": "whsec_…"
}

Поле webhookSecret можно убрать, если проверка подписи не нужна. В Unix после сохранения выполните chmod 600 /absolute/path/credentials.json, подставив полный путь к файлу. В Windows храните файл в папке своей учётной записи и проверьте существующие права доступа. В примерах ниже замените /absolute/path/credentials.json полным путём к нему.

Claude Code, Claude Desktop, Cursor, Windsurf и другие клиенты

Добавьте запись в файл настроек MCP вашего клиента:

{
  "mcpServers": {
    "paymos": {
      "command": "npx",
      "args": ["-y", "@paymos/mcp"],
      "env": { "PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json" }
    }
  }
}

В Kimi CLI используется тот же формат в mcp.json. Для Claude Code можно вручную добавить запись и в проектный .mcp.json. Файл Claude Desktop в macOS — ~/Library/Application Support/Claude/claude_desktop_config.json, в Windows — %APPDATA%\Claude\claude_desktop_config.json. Существующие записи при добавлении Paymos сохраняйте.

Codex

Добавьте в config.toml:

[mcp_servers.paymos]
command = "npx"
args = ["-y", "@paymos/mcp"]

[mcp_servers.paymos.env]
PAYMOS_CREDENTIALS_FILE = "/absolute/path/credentials.json"

OpenCode

Добавьте в конфигурацию OpenCode:

{
  "mcp": {
    "paymos": {
      "type": "local",
      "command": ["npx", "-y", "@paymos/mcp"],
      "environment": { "PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json" },
      "enabled": true
    }
  }
}

VS Code

В .vscode/mcp.json запись выглядит так:

{
  "servers": {
    "paymos": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@paymos/mcp"],
      "env": { "PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json" }
    }
  }
}

Zed

Автоматического адаптера для Zed нет. В Unix добавьте сервер вручную в context_servers.paymos файла ~/.config/zed/settings.json; настройки проекта хранятся в .zed/settings.json. В Windows откройте настройки в Zed и выберите фактический файл settings.json. Используйте поля command, args и env из общего примера.

Запуск в Windows

При ручной настройке в Windows укажите команду и аргументы:

"command": "cmd",
"args": ["/d", "/c", "npx", "-y", "@paymos/mcp"]

В OpenCode вся команда записывается одним массивом: "command": ["cmd", "/d", "/c", "npx", "-y", "@paymos/mcp"]. Для Codex TOML укажите command = "cmd" и тот же массив аргументов. Команда setup выбирает этот способ запуска в Windows автоматически.

Сервер по-прежнему принимает PAYMOS_API_KEY_ID, PAYMOS_API_SECRET и PAYMOS_WEBHOOK_SECRET напрямую. Флаги --api-key-id и --api-secret тоже работают. Приоритет значений: переменные окружения → флаги → файл ключей. Не записывайте секреты в историю команд или настройки проекта.

Инструменты и документация

Инструмент Назначение
create_invoice Создать тестовый инвойс; повтор с тем же external_order_id идемпотентен; возвращает payment_url
get_invoice Прочитать текущее состояние инвойса
list_invoices Получить одну страницу инвойсов с фильтрами и курсорной пагинацией
cancel_invoice Отменить неоплаченный инвойс и сохранить причину
simulate_invoice_payment Симулировать paid, paid_late, overpaid, underpay или cancel в песочнице
verify_webhook_signature Проверить X-Webhook-Signature локально, без вызова API

Пять страниц доступны агенту как ресурсы: paymos://docs/quick-start, paymos://docs/hosted-checkout, paymos://docs/webhooks, paymos://docs/testing-sandbox, paymos://docs/server-sdks.

Сценарий paid_late проверяет оплату после срока, а не добавляет новый статус инвойса. Его поведение описано в документации песочницы.

Только песочница

Для MCP нужна тестовая пара ключей. Рабочие (pk_live_/sk_live_) и ключи выплат (rk_…) отклоняются при настройке, запуске сервера и вызове инструментов. Когда интеграция проверена, ваше приложение работает с рабочими ключами самостоятельно; локальный MCP-сервер в реальных платежах не участвует.

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

Что дальше

Назад Серверные SDK Далее Безопасность