API и MCP: полная автоматизация прокси

REST API или MCP: кто принимает решение

Оба интерфейса дают доступ к одним и тем же операциям. Разница в том, где живёт логика: в коде, который вы написали и проверили, или в агенте, который сам разбирает запрос и выбирает вызовы. Часто их используют вместе: API — в рабочих пайплайнах, MCP — для разовых задач и разбора проблем.

Первый запрос за три шага

Начать можно ещё до создания ключа: список стран с остатками и расчёт цены доступны без авторизации.

1. Посмотрите страны и остатки

   Ответ содержит все страны с ISO-кодами и количеством IP, доступных прямо сейчас. Параметр product_kind принимает proxy_datacenter или proxy_isp. При расчёте и заказе можно также указать proxy_personal — персональные прокси.

   bashКопировать

   curl -s "https://papaproxy.net/account_new/api/v1/billing/countries?product_kind=proxy_datacenter"

2. Рассчитайте цену для набора стран

   Расчёт бесплатный и ни к чему не обязывает. В ответе — цена каждого сегмента, скидка за объём и итог за месяц в центах. Укажите period_months 3, 6 или 12, чтобы увидеть скидку за срок.

   bashКопировать

   curl -s -X POST https://papaproxy.net/account_new/api/v1/billing/composite/quote \
     -H "Content-Type: application/json" \
     -d '{
       "product_kind": "proxy_datacenter",
       "period_months": 1,
       "segments": [
         {"country": "US", "count": 300},
         {"country": "DE", "count": 200}
       ]
     }'

3. Создайте ключ и обратитесь к своему аккаунту

   В личном кабинете откройте Настройки → API-ключи, задайте название и отметьте только нужные права. Полный ключ показывается один раз, сразу после создания, — сохраните его в менеджере секретов или переменной окружения.

   bashКопировать

   export PAPAPROXY_API_KEY="fb_..."
   
   curl -s https://papaproxy.net/account_new/api/v1/customer/services \
     -H "Authorization: Bearer $PAPAPROXY_API_KEY"

Что умеет REST API

У каждой операции личного кабинета есть эндпоинт. Схемы запросов и ответов, коды ошибок и примеры на cURL, Python, Node.js, PHP и Go — в справочнике API (на английском), он построен по открытой спецификации OpenAPI 3.1. Отправить пробные запросы со своим ключом можно в консоли личного кабинета.

MCP-сервер: личный кабинет в виде инструментов для агента

Model Context Protocol позволяет агенту узнавать, какие инструменты есть на удалённом сервере, и вызывать их. Подключите сервер PapaProxy.net один раз — и агент получит 56 инструментов, чтобы работать с аккаунтом так же, как вы: проверит остатки, сравнит цены, купит, настроит и отчитается в чате.

Подключение

Вставьте конфигурацию в настройки MCP вашего клиента. В Cursor это файл .cursor/mcp.json в проекте или ~/.cursor/mcp.json для всех проектов. Название сервера можно выбрать любое. Можно также установить сервер в Cursor в один клик, а затем заменить fb_YOUR_API_KEY своим ключом. Пошаговая настройка, безопасные разрешения на вызовы и решение проблем — в руководстве по MCP для Cursor.

{
  "mcpServers": {
    "papaproxy-net": {
      "url": "https://papaproxy.net/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}

В Claude Code тот же сервер добавляется одной командой. Области хранения, правила разрешений и решение проблем — в руководстве по MCP для Claude Code.

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

Другие клиенты используют тот же адрес и заголовок, отличаются только файл и его формат:

{
  "servers": {
    "papaproxy-net": {
      "type": "http",
      "url": "https://papaproxy.net/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "papaproxy-net": {
      "serverUrl": "https://papaproxy.net/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "papaproxy-net": {
      "type": "streamableHttp",
      "url": "https://papaproxy.net/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}

[mcp_servers.papaproxy-net]
url = "https://papaproxy.net/account_new/api/v1/mcp"
bearer_token_env_var = "PAPAPROXY_API_KEY"

{
  "mcpServers": {
    "papaproxy-net": {
      "httpUrl": "https://papaproxy.net/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "papaproxy-net": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://papaproxy.net/account_new/api/v1/mcp",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}

Endpoint:          https://papaproxy.net/account_new/api/v1/mcp
Server Transport:  HTTP Streamable
Authentication:    Bearer Auth
Bearer Token:      fb_YOUR_API_KEY

Подойдёт и любой другой MCP-клиент, который поддерживает удалённые серверы с собственными заголовками: адрес и заголовок те же. Коннекторы, которые входят только через OAuth, — например, пользовательские коннекторы в ChatGPT и в веб-версии Claude, — пока подключить нельзя: сервер работает с API-ключами. Примеры конфигурации есть и в нашем репозитории на GitHub.

Как агент покупает прокси

Что ещё умеет агент

Полный список инструментов MCP в справочнике API (на английском): для каждого указаны нужное право и эндпоинт REST, который он вызывает.

Примеры запросов агенту

Права ключей: только то, что нужно

Запрос выполняется, только если у ключа есть право, которое требует эндпоинт. Права действуют одинаково для REST-вызовов и инструментов MCP: ключ без wallet:spend не сможет ничего оплатить ни через API, ни через агента.

В справочнике API у каждого эндпоинта и инструмента MCP указано нужное право.

Типовые наборы прав

Вебхуки: уведомления вместо опроса

Укажите HTTPS-адрес и выберите нужные события; актуальный список типов событий возвращает GET /customer/webhooks/events. Секрет адреса показывается только один раз, в ответе на создание, — сохраните его сразу.

• История доставок по каждому адресу: что отправлено и что ответил ваш сервер.
• Тестовое событие, чтобы проверить обработчик до прихода настоящих.
• Повторная отправка конкретного события после исправления ошибки в обработчике.
• В карточке адреса видно число неудачных доставок подряд и причину, если адрес отключён.
• Каждая доставка подписана: в X-FB-Signature передаётся HMAC-SHA256 от метки времени и сырого тела запроса, так обработчик проверяет, что событие отправил PapaProxy.net.
• Неудачная доставка повторяется ещё 5 раз в течение примерно 8,5 часа; отвечайте любым статусом 2xx в течение 10 секунд.

Код проверки подписи, заголовки, расписание повторов и полный список событий — в справочнике API (на английском).

Защита, когда автоматика тратит деньги