Proxy automation for your code and your AI agents

REST API or MCP: pick by who makes the decision

The two interfaces reach the same account operations. The difference is where the logic lives: in code you wrote and tested, or in an agent that interprets a request and chooses the calls itself. Many teams use both — the API for production pipelines, MCP for ad hoc work and troubleshooting.

Your first request in three steps

You can start before you even create a key: the country list with live stock and price quotes are open to everyone.

1. Check available locations and stock

   Returns every country with an ISO code and the number of IPs currently available. Set product_kind to proxy_datacenter or proxy_isp. Quotes and orders also accept proxy_personal for dedicated proxies.

   bashCopy

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

2. Get a price for your country mix

   A quote is free and non-binding. The response includes the price per segment, the volume discount, and the monthly total in cents. Set period_months to 3, 6, or 12 to see the term discount.

   bashCopy

   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. Create a key and call your account

   In the Dashboard, open Settings → API keys, name the key, and select only the scopes it needs. The full key is displayed once, right after creation — store it in a secrets manager or an environment variable.

   bashCopy

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

What the REST API covers

Every path below starts with the base URL. Request and response schemas, error codes, and a “try it” console are in the API reference in your Dashboard.

Placing an order from code

The order request takes the same segments as the quote, plus the IPs to whitelist and an idempotency key. If a network error makes you retry, the same order returns the existing service instead of charging you twice.

curl -s -X POST https://papaproxy.net/account_new/api/v1/billing/composite/order \
  -H "Authorization: Bearer $PAPA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_kind": "proxy_datacenter",
    "period_months": 1,
    "segments": [
      {"country": "US", "count": 300},
      {"country": "DE", "count": 200}
    ],
    "whitelist_ips": ["203.0.113.10"],
    "use_balance": true,
    "idempotency_key": "eu-us-500-2026-10"
  }'

MCP server: the Dashboard as tools for your agent

The Model Context Protocol lets an agent discover and call tools on a remote server. Connect the PapaProxy.net server once, and your agent gets 50 tools to work with your account the way you would: check stock, compare prices, buy, configure, and report back in the chat.

Connect it

Paste the configuration into your client’s MCP settings — in Cursor, that’s .cursor/mcp.json in your project or ~/.cursor/mcp.json for all projects. The server name is up to you.

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

Claude Code adds the same server from the command line:

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

Any other MCP client that supports remote servers with custom headers works with the same URL and header.

How an agent buys proxies

What else the agent can do

Requests that work well

Scopes: give each key only what it needs

A request succeeds only if the key holds the scope that endpoint requires. Scopes apply the same way to REST calls and MCP tools, so a key without wallet:spend can’t pay for anything through either interface.

Typical key setups

Webhooks: get notified instead of polling

Register an HTTPS URL and choose the events you care about; GET /customer/webhooks/events returns the current list of event types. The endpoint secret appears only once, in the creation response, so save it right away.

• Delivery history for each endpoint shows what was sent and how your server responded.
• Send a test event to check your handler before real events arrive.
• Redeliver a specific event after you fix a handler error.
• The endpoint record shows consecutive failed deliveries and the reason if it gets disabled.

Safeguards for automation that spends money