# Как подключить MCP-сервер PapaProxy.net в Claude Code

> Страница: https://papaproxy.net/ru/developers/mcp/claude-code.php. MCP-сервер PapaProxy.net даёт Claude Code 56 инструментов для прокси-аккаунта: наличие IP, расчёт цены, заказы, привязка по IP, выгрузка списка прокси и анализ ошибок. Это удалённый сервер на Streamable HTTP (`--transport http`), локально ничего ставить не нужно.

- Адрес MCP: `https://papaproxy.net/account_new/api/v1/mcp`
- Авторизация: заголовок `Authorization: Bearer <api_key>`
- Создать ключ: личный кабинет → Настройки → API-ключи (https://papaproxy.net/account_new/settings#api-keys). Полный ключ показывается один раз.
- Стоимость: входит в каждый аккаунт, оплачиваются только заказанные прокси.

## Шаг 1. Ключ API с нужными правами

Права проверяются на сервере, поэтому ограничивают Claude независимо от правил разрешений и режима работы.

| Что должен делать Claude | Права |
|---|---|
| Только анализ: наличие IP, цены, услуги, статистика, ошибки | `catalog:read`, `services:read`, `usage:read` |
| Ещё и настройка: привязка по IP, логины и пароли, автопродление | то же плюс `services:write` |
| Ещё и оплата с баланса: заказы, продления, дополнения, докупка IP | то же плюс `wallet:read`, `wallet:spend` |

Начните без `wallet:spend`: Claude всё равно сможет рассчитать любой заказ.

## Шаг 2. Добавьте сервер в Claude Code

| Область | Где работает | Где хранится |
|---|---|---|
| `local` (по умолчанию) | Только текущий проект, только у вас | `~/.claude.json`, в разделе проекта |
| `user` | Все ваши проекты на этом компьютере | `~/.claude.json` |
| `project` | Все, кто работает с репозиторием | `.mcp.json` в корне проекта |

Способ 1, одна команда (область `user`; замените заглушку, `Bearer ` оставьте):

```bash
claude mcp add --transport http --scope user papaproxy-net \
  https://papaproxy.net/account_new/api/v1/mcp \
  --header "Authorization: Bearer fb_YOUR_API_KEY"
```

В Windows запишите команду в одну строку (переносы через `\` работают только в терминалах macOS и Linux). Ключ хранится открытым текстом в `~/.claude.json`.

Способ 2, `.mcp.json` в корне проекта с ключом в переменной окружения (Claude Code подставляет `${VAR}` в `url` и `headers`):

```json
{
  "mcpServers": {
    "papaproxy-net": {
      "type": "http",
      "url": "https://papaproxy.net/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${PAPAPROXY_API_KEY}"
      }
    }
  }
}
```

Задайте `export PAPAPROXY_API_KEY="fb_..."` в `~/.zshrc` или `~/.bashrc` и откройте новый терминал перед запуском `claude`. При первом запуске в проекте Claude Code попросит одобрить серверы из `.mcp.json`; до этого статус — `Pending approval`.

## Шаг 3. Проверьте подключение

Выполните `claude mcp get papaproxy-net`: статус должен быть `✔ Connected`. При `✘ Failed to connect` в строке будут HTTP-статус и текст ошибки сервера. Внутри сессии `/mcp` показывает сервер и число инструментов. Затем отправьте запрос, который ничего не стоит:

> Через MCP-сервер papaproxy-net покажи страны, где есть серверные прокси, и рассчитай цену 100 IP в США на месяц. Ничего не покупай.

Claude должен вызвать `list_countries` и `quote_composite`. Расчёт цены бесплатный и ничего не резервирует.

## Разрешения

В правилах инструменты называются `mcp__papaproxy-net__<инструмент>`. Правила проверяются в порядке deny → ask → allow, поэтому правило `ask` оставляет инструмент с подтверждением, даже если его разрешает более широкое правило. Добавьте правила через `/permissions` или в `.claude/settings.json` (проект) либо `~/.claude/settings.json` (все проекты):

```json
{
  "permissions": {
    "allow": [
      "mcp__papaproxy-net__list_countries",
      "mcp__papaproxy-net__quote_composite",
      "mcp__papaproxy-net__list_services",
      "mcp__papaproxy-net__get_service",
      "mcp__papaproxy-net__list_proxy_ips",
      "mcp__papaproxy-net__get_whitelist",
      "mcp__papaproxy-net__get_usage_overview",
      "mcp__papaproxy-net__get_diagnostics",
      "mcp__papaproxy-net__get_recommendations",
      "mcp__papaproxy-net__wallet_balance"
    ],
    "ask": [
      "mcp__papaproxy-net__order_composite",
      "mcp__papaproxy-net__order_dedicated",
      "mcp__papaproxy-net__add_ips",
      "mcp__papaproxy-net__renew_service",
      "mcp__papaproxy-net__purchase_addon",
      "mcp__papaproxy-net__refresh_ips",
      "mcp__papaproxy-net__rotate_proxy_credentials",
      "mcp__papaproxy-net__remove_whitelist_ip",
      "mcp__papaproxy-net__cancel_service",
      "mcp__papaproxy-net__disable_addon"
    ]
  }
}
```

Для `cancel_service` и `disable_addon` нужно ещё `confirm: true`. Настоящее ограничение — права ключа: ключ без `wallet:spend` ничего не оплатит, а ключ с ним платит только с баланса аккаунта.

## Сценарии

- Парсер на актуальных прокси: Claude использует `list_services` и `list_proxy_ips` и пишет код, который загружает список прокси из REST API при запуске и берёт ключ из `PAPAPROXY_API_KEY`.
- Привязка сервера, на котором вы работаете: `get_my_ip` возвращает IP, с которого пришёл запрос (на удалённом сервере — внешний IP сервера); `add_whitelist_ip` добавляет его.
- Ежедневный отчёт об ошибках без сессии: `claude -p "Кратко опиши вчерашние ошибки прокси" --allowedTools "mcp__papaproxy-net__get_usage_timeseries" "mcp__papaproxy-net__get_diagnostics"`. В режиме `-p` подтверждать вызовы некому, поэтому перечислите нужные инструменты только для чтения.
- Цена до покупки: `list_countries`, `quote_composite`; с `wallet:spend` — `order_composite` с ключом идемпотентности.

Большие списки прокси: `list_proxy_ips` возвращает весь список услуги одним ответом. Claude Code предупреждает при ответе больше 10 000 токенов и по умолчанию обрезает его на 25 000 токенов — пакет из нескольких тысяч IP может до этого дойти. Для больших пакетов попросите Claude написать код, который скачивает список через REST API (https://papaproxy.net/developers/reference/proxy-access.md), или поднимите `MAX_MCP_OUTPUT_TOKENS`.

Все инструменты с правами и REST-эндпоинтами: https://papaproxy.net/developers/reference/#mcp-tools (на английском).

## Решение проблем

Начните с `claude mcp list` или `claude mcp get papaproxy-net`.

| Что видно | Причина и решение |
|---|---|
| `Missing or malformed Authorization header` | Нет `--header`, или значение не начинается с `Bearer `; в способе 2 переменная `PAPAPROXY_API_KEY` не задана в терминале, из которого запускается `claude` |
| `Invalid or revoked API key` | Опечатка, отозванный ключ или заглушка `fb_YOUR_API_KEY` в команде; `claude mcp remove papaproxy-net` и добавьте заново |
| `Leading or trailing whitespace in: headers.Authorization` | В ключе пробел или перенос строки; удалите сервер и добавьте заново |
| `⏸ Pending approval` | Сервер из `.mcp.json` ещё не одобрен; запустите `claude` в проекте и одобрите его |
| Предупреждение с именем `PAPAPROXY_API_KEY` | Переменная не задана; добавьте строку с `export` и откройте новый терминал |
| Одно имя сервера в нескольких областях | Удалите дубль: `claude mcp remove papaproxy-net --scope local` |
| Вызов падает с ошибкой прав | У ключа нет нужного права; ошибки приходят текстом с коротким кодом и пояснением |
| Вызовы падают после серии запросов | 60 запросов в минуту на аккаунт, общий лимит для всех ключей API и MCP-сервера |
| Команда не работает в Windows | Используйте вариант в одну строку; переносы через `\` работают только в macOS и Linux |

Ошибки сервера: напишите на support@papaproxy.net и укажите время неудачного вызова.

## Другие MCP-клиенты

Руководство для Cursor: https://papaproxy.net/ru/developers/mcp/cursor.md. Руководство для n8n: https://papaproxy.net/ru/developers/mcp/n8n.md. VS Code, Windsurf, Cline, Codex CLI, Gemini CLI, Claude Desktop: https://papaproxy.net/ru/developers.php#mcp