Proxy MCP server for AI agents

Short answers

What an agent needs that a plain API key does not give it

Agents fail on the web for dull, geographic reasons. The page renders in the wrong language, prices arrive in the wrong currency, a country-restricted page refuses, or fifty parallel runs share one address and get rate limited together.

The fix is a country-accurate exit per run, chosen at the moment of the run. That is a decision the agent has to make while it works, which is exactly what a tool call is for.

The tools, and what each one answers

list_countries

Countries with devices online now, per pool. Call it before choosing, not once at startup.

build_proxy_url

Validates pool, country, rotation, session and protocol, and returns a usable proxy URL.

test_connection

Sends one request through the gateway from our side and reports whether it worked, the exit IP and the latency. It does not confirm the country. Rate limited to six a minute.

get_traffic

Balance and expiry: gb_total, gb_used, gb_left, plus the credentials and the account limits.

buy_traffic

Tops up from the account balance. Needs confirm: true and an idempotency key.

get_pricing

The per-GB ladder, so an agent can reason about a top-up before making one.

get_status

Service status, for an agent deciding whether a failure is worth retrying.

Connecting the server

The server runs over stdio and takes two environment values: the API key and the API base URL. Most MCP clients read a block like this from their configuration file.

{
  "mcpServers": {
    "portproof": {
      "command": "npx",
      "args": ["-y", "@portproof/mcp"],
      "env": {
        "PORTPROOF_API_KEY": "pk_...",
        "PORTPROOF_API_URL": "https://api.portproof.org/v1"
      }
    }
  }
}

Every tool wraps a route you can call yourself, which is the fastest way to see what the agent will get back before you let it loose.

# what is online now, per pool: { "mobile": [ { "country": "US", "name": "...", "online": 33 } ], "residential": [ ... ] }
curl https://api.portproof.org/v1/traffic/countries -H "Authorization: Bearer $PORTPROOF_API_KEY"

# build and validate a URL for one run (the API takes mobile / residential / best)
curl -X POST https://api.portproof.org/v1/traffic/build-url \
  -H "Authorization: Bearer $PORTPROOF_API_KEY" -H "Content-Type: application/json" \
  -d '{"pool":"residential","country":"US","rotation":"sticky","session":"run_a1b2c3","protocol":"http"}'

# balance before and after the run
curl https://api.portproof.org/v1/traffic -H "Authorization: Bearer $PORTPROOF_API_KEY"

One session per run

Give each run its own session name and hold it for the whole task: sid-<name> with rot-sticky. The name is lower-case letters, digits and underscores, and a run id or task id makes a good one because it is unique and already in your logs.

Holding a session keeps the device, not the address, so write the run to survive a change rather than asserting on the exit address. Why that distinction matters, and what to do when the address moves mid-task, is in why a sticky session changed its IP.

import os, uuid
import requests

API = "https://api.portproof.org/v1"
HEAD = {"Authorization": "Bearer " + os.environ["PORTPROOF_API_KEY"], "Content-Type": "application/json"}
WANT = ["US", "NL", "GB"]          # in order of preference


def pick_country(pool: str, need: int = 1) -> str:
    """First preferred country with at least this many devices online in that pool."""
    live = requests.get(API + "/traffic/countries", headers=HEAD, timeout=10).json()
    online = {row["country"]: row["online"] for row in live[pool]}
    for code in WANT:
        if online.get(code, 0) >= need:
            return code
    raise RuntimeError("none of the preferred countries is online in " + pool)


country = pick_country("residential")
session = "run_" + uuid.uuid4().hex[:10]
built = requests.post(
    API + "/traffic/build-url",
    headers=HEAD,
    json={"pool": "residential", "country": country, "rotation": "sticky", "session": session, "protocol": "http"},
    timeout=10,
).json()

print(built["username"], built["url_masked"])
proxies = {"http": built["url"], "https": built["url"]}
print(requests.get("https://api.portproof.org/v1/echo-ip", proxies=proxies, timeout=30).json())

Topping up from inside a run

An agent that stops halfway because the balance ran out is worse than one that asks. buy_traffic exists for that, and it is deliberately awkward: without confirm: true it does nothing, and without an idempotency key the write is refused. A retried tool call with the same key is the same purchase, not a second one.

Keep the decision human where it matters. A sensible pattern is a hard ceiling in your own code, an alert at 80 percent of the balance, and an agent permitted to top up only up to a size you set. Buying from the API spends the account balance; every other payment method goes through checkout.

Budgeting a run, and reading it back

Size the run before it starts: steps times the weight of a step, times the retries you expect. A rendered page is the expensive unit, so an agent that can answer from an API or from HTML should not open a browser to do it.

Afterwards, read gb_used back and store it with the run id. Usage refreshes every five minutes, so compare across a wider window than a short run takes. What the meter counts, including the handshakes and the failed attempts, is in what counts as proxy traffic.

For the wider picture of what agents do with this, see proxies for AI agents, the two pools at mobile 4G/5G and residential, and the per-GB ladder on pricing.

What is not allowed

What is not allowed: an agent is held to the same rules as a person. Creating or farming accounts, solving or evading human checks, credential stuffing and anything else on the declined list are refused, whoever or whatever issues the request. Give an agent a task you would be happy to run yourself. See the acceptable-use policy.

Read next