# PapaProxy.net — API and MCP for developers

Page: https://papaproxy.net/developers.php

PapaProxy.net Dashboard operations are available through a REST API and an MCP server. Both use the same API keys with scopes.

## Essentials

- Base URL: `https://papaproxy.net/account_new/api/v1`
- Authentication: `Authorization: Bearer <api_key>` header
- Create a key: https://papaproxy.net/account_new/settings?locale=en#api-keys
- OpenAPI 3.1 reference: https://papaproxy.net/account_new/docs?locale=en
- MCP endpoint: `https://papaproxy.net/account_new/api/v1/mcp` (remote server, HTTP)
- No key needed for: `GET /billing/countries` and `POST /billing/composite/quote`
- With a key, the MCP server gives the agent 50 tools

## Without a key

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

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":100}]}'
```

Quote prices are in cents (`total_price_cents`, `monthly_price_cents`).

## MCP connection

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

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

## Buying proxies

1. `list_countries` / `GET /billing/countries?product_kind=proxy_datacenter|proxy_isp` — countries and live stock.
2. `quote_composite` / `POST /billing/composite/quote` — free, non-binding price quote.
3. `order_composite` / `POST /billing/composite/order` — order paid from the account balance.

Order fields: `product_kind` (`proxy_datacenter`, `proxy_isp`, `proxy_personal` for dedicated proxies), `segments` (`[{"country":"US","count":300}]`, ISO-2), `period_months` (1, 3, 6, 12), `whitelist_ips` (required for proxy orders; otherwise HTTP 422 before any charge), `use_balance: true` (pay from the balance), `idempotency_key`. Repeating the same order returns the existing service without a second charge.

## Scopes

- `catalog:read` — products, countries, prices
- `services:read` — services, IP lists, credentials, IP whitelisting
- `services:write` — credentials, IP whitelisting, IP refresh, sticky sessions, cancellation
- `usage:read` — usage statistics
- `wallet:read` — balance, ledger, invoice PDFs
- `wallet:deposit` — balance top-ups
- `wallet:spend` — paying from the balance: purchases, renewals, add-ons, extra IPs, paid IP refreshes
- `tickets:read`, `tickets:write` — support tickets
- `customer:read`, `customer:write` — profile
- `webhooks` — webhook endpoints and deliveries

## Rules for agents

- Show the user a quote and get confirmation before any purchase.
- Send an `idempotency_key` with paid operations that may be retried.
- Don't print the API key in replies or save it to project files.
- If a scope is missing, tell the user which scope is required instead of working around it.