# MCP-сервер

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

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

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

- Node.js 20 или новее
- Тестовая пара ключей из [Дашборд → Разработчик → API-ключи](/ru/docs/api-keys.md): `pk_test_…` и `sk_test_…`
- MCP-клиент, который умеет запускать локальные stdio-серверы

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

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

```bash
npx -y @paymos/mcp setup
```

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

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

```bash
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`:

```bash
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](https://docs.z.ai/devpack/tool/claude) описывает GLM в Claude Code: после выбора модели подключите Paymos в самом Claude Code.

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

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

```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 вашего клиента:

```json
{
  "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`:

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

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

### OpenCode

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

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

### VS Code

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

```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 укажите команду и аргументы:

```json
"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` проверяет оплату после срока, а не добавляет новый статус инвойса. Его поведение описано в [документации песочницы](/ru/docs/testing.md).

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

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

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

## Что дальше

- [Быстрый старт](/ru/docs/quick-start.md) — пройти сценарий с инвойсом вручную
- [Тестирование в песочнице](/ru/docs/testing.md) — выбрать сценарии оплаты
- [Серверные SDK](/ru/docs/server-sdks.md) — собрать приложение с SDK
- [Вебхуки](/ru/docs/webhooks.md) — обрабатывать события и проверять подписи