API and MCP: full proxy automation

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. Dedicated proxies have their own endpoints, starting with GET /billing/dedicated/countries.

   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. A package needs at least 100 IPs in total and at least 10 per country; a country below 10 IPs is listed in errors and left out of the total.

   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 PAPAPROXY_API_KEY="fb_..."
   
   curl -s https://papaproxy.net/account_new/api/v1/customer/services \
     -H "Authorization: Bearer $PAPAPROXY_API_KEY"

What the REST API covers

Every Dashboard operation has an endpoint. Request and response schemas, error codes, and code samples in cURL, Python, Node.js, PHP, and Go are in the API reference, built from the public OpenAPI 3.1 specification. To send test requests with your key, use the “try it” console in your Dashboard.

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 56 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. You can also install it in Cursor in one click and then replace fb_YOUR_API_KEY with your key. Step-by-step setup, safe tool approvals, and troubleshooting are in the Cursor MCP guide.

{
  "mcpServers": {
    "papaproxy-net": {
      "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. Scopes, permission rules, and troubleshooting are in the Claude Code MCP guide.

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

Other clients use the same URL and header; only the file and its format differ:

{
  "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

Any other MCP client that supports remote servers with custom headers works with the same URL and header. Connectors that sign in only with OAuth, such as custom connectors in ChatGPT and in Claude on the web, can’t connect yet: the server authenticates with API keys. Examples are also in our GitHub repository.

How an agent buys proxies

What else the agent can do

The full list of MCP tools in the API reference shows the scope each tool requires and the REST endpoint it calls.

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.

Every endpoint and every MCP tool in the API reference lists the scope it requires.

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.
• Each delivery is signed: X-FB-Signature carries an HMAC-SHA256 of the timestamp and the raw body, so your handler can confirm the event came from PapaProxy.net.
• Failed deliveries are retried 5 more times over about 8.5 hours; respond with any 2xx status within 10 seconds.

Signature verification code, headers, the retry schedule, and the full event list are in the API reference.

Safeguards for automation that spends money