Short answers
What does MCP do here?
The Model Context Protocol is an open standard for giving a model tools. It is not a proxy protocol and it does not carry your traffic: the MCP server exposes account and connection operations as tools, and the agent then connects through the gateway with an ordinary HTTP or SOCKS5 proxy URL.
Which tools does the server expose?
The GB-traffic workflow uses get_traffic, list_countries, build_proxy_url, test_connection, buy_traffic, get_pricing and get_status. These wrap API operations, with extra MCP confirmation checks and password masking. Other tools cover the separate dedicated-port product.
How does the agent pick a country it can actually use?
Call list_countries and choose a country reported online in the required pool. Check the response’s observation time and stale flag. Availability can change after the reading; a successful stock call or URL build does not reserve a device or establish the exit country.
Can an agent buy traffic on its own?
buy_traffic spends wallet money. It requires confirm: true, accept_terms: true and an idempotency_key, plus either whole gb or trial: true. The user must accept the terms, acceptable-use policy and immediate start of service. Tool inputs record that decision; the agent cannot supply the user’s acceptance for them.
Should the agent rotate its IP during a run?
Keep one sticky session name for related requests when the task needs continuity. Sticky aims to keep the same device; the carrier can still change its IP. Browser cookies, storage, consent and login state belong to the browser context. An IP change neither clears that state nor guarantees that a website will keep its session valid.
What does an agent run cost in GB?
Measure a representative authorised task. Browser assets, request and response sizes, retries and concurrency all affect usage; there is no fixed GB cost per agent step. The shared gateway balance counts traffic in both directions. A balance difference can include other jobs and delayed usage updates.
Does the API key go to the model?
Supply the API key to the server through its environment or your client’s secret facility. Do not paste it into a prompt. Connection passwords are masked by default; build_proxy_url with reveal_password: true deliberately returns a usable credential to the tool result. Consider what your MCP host stores before requesting it.
What an agent needs that a plain API key does not give it
For market research, ad verification or regional QA, an agent may need a particular network route. A proxy changes that route. It does not configure browser language, currency, cookies or account preferences, and it does not grant access permission.
Keep three decisions separate: which pool and country to request, which browser or HTTP session to retain, and what spending the user authorises. The tools help configure and inspect those choices. Verify the result in the client that will run the task.
The tools, and what each one answers
- list_countries
- Public stock reading per pool. Inspect
generated_atandstale; a reading is not a reservation. - build_proxy_url
- Validates connection settings and formats the username and URL. Passwords in the URL and snippets are masked by default. Requires
ports:write. - test_connection
- Makes one gateway request from the API, using a small amount of GB. Reports the exit IP and latency; a country is confirmed only when
country_verifiedis true. Requiresports:write; at most six calls a minute. - get_traffic
- Reads
gb_total,gb_used,gb_left, expiry and limits withports:readorports:write. Connection details requireports:write; the password stays masked. - buy_traffic
- Buys from the wallet with
ports:write. Requires purchase confirmation, user terms acceptance and an idempotency key; see the purchase checks below. - 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
Use Node.js 20 or newer and an MCP client that supports local stdio servers. npx -y @portproof/mcp starts the published server. The API URL defaults to production; the explicit URL below makes the destination visible. Adapt the configuration to your client’s supported format.
The package page is @portproof/mcp on npm, and the portproof-mcp repository on GitHub mirrors its releases from version 0.2.1 onward.
pk_... is a placeholder. Supply the real key through your client’s protected configuration or secret facility and keep that file out of source control. There is no sandbox: every key acts on your real balance, whatever its prefix.
{
"mcpServers": {
"portproof": {
"command": "npx",
"args": ["-y", "@portproof/mcp"],
"env": {
"PORTPROOF_API_KEY": "pk_...",
"PORTPROOF_API_URL": "https://api.portproof.org/v1"
}
}
}
}Start with get_status, get_pricing and list_countries; these public calls need no API key. Read the current stock before selecting a country. To inspect an existing balance use a key with ports:read. Building a connection, testing it and buying traffic need ports:write; that scope also permits purchases, so retain the host’s user-confirmation controls.
Use US only if a current stock reading confirms availability in the selected pool. This is the tool’s argument object, not a complete MCP protocol message.
{
"pool": "residential",
"country": "US",
"rotation": "sticky",
"session": "run_a1b2c3",
"protocol": "http",
"reveal_password": false
}Expect password_revealed: false and a masked URL. This call formats connection details; it sends no request through the proxy and does not prove country availability. A masked URL cannot authenticate a workload. For the first working request, use the connection builder and curl setup check, or explicitly request a usable URL only in a runtime where its secret can be handled appropriately.
MCP output differs from the raw API: the tools mask connection passwords, while authorised traffic API responses can contain usable credentials. Do not print raw API responses into an agent transcript or public log. Keep only the non-sensitive status needed for the task.
One session per run
Use one opaque session name for related requests, with lower-case letters, digits and underscores. A new task can use a new name. Different session names do not guarantee different devices or IP addresses, and the balance remains shared. Keep customer identifiers and destination details out of session names.
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.
This makes a gateway request and consumes some existing traffic; request it only when that test is intended.
{
"pool": "residential",
"country": "US",
"rotation": "sticky"
}test_connection does not accept a session name. It tests a request from the API, so it cannot establish that your browser used run_a1b2c3 or that your local client is configured correctly. If ok is true, inspect country_verified before interpreting exit_country. Never substitute the requested country for an unverified result.
| Result | Next step |
|---|---|
| Stale or unavailable stock | Wait for a current reading. Do not present an old count as online now. |
no_exit_available | Recheck stock and pause that country-specific task. Use a different country only if it meets the task’s requirements. |
Masked URL or insufficient_scope | Check credential access. Repeating the request does not make a masked password usable or expand a key’s scope. |
| Gateway test works; application fails | Check the application’s own proxy and authentication settings using the client troubleshooting guide. |
mobile and residential, and the proxy username calls them mbl and peer. Both are on the setup docs. If the agent runs inside a workflow tool rather than an MCP client, the same job is done with environment variables, as in use a proxy in n8n.Topping up from inside a run
Read get_pricing and get_traffic before proposing a purchase. Show the amount and applicable price, then get the user’s purchase confirmation and acceptance of the terms, acceptable-use policy and immediate start of service. Only after that decision may the tool receive confirm: true, accept_terms: true and an idempotency_key. Set either whole gb or trial: true, never both. Wallet funds, account eligibility and the server’s current limits still apply.
Keep the same idempotency key and purchase inputs when checking an uncertain retry; do not generate a new key after a timeout. Business refusals such as insufficient_funds or trial_already_used remain stored under the purchase key for 24 hours. After correcting that cause, a new attempt needs a new key and an applicable user decision. Local MCP confirmation or terms refusals have not reached the API; API rate-limit and server errors are not retained as completed responses. A key reused for different inputs can return idempotency_conflict. Buying with this tool uses the wallet; other configured payment methods go through checkout.
Budgeting a run, and reading it back
Measure a small representative task before scaling it. Use the proxy bandwidth calculator to model pages, transferred bytes and retries. If the task only needs an authorised API response, avoid loading unrelated browser assets. Keep any spending ceiling in the application controlling the agent; this guide does not configure one.
Usage normally refreshes every five minutes. A before/after gb_used difference on the shared account can include concurrent jobs and updates arriving after the task ends; it is not an exact per-run bill. What the meter counts, including handshakes and failed attempts, is in what counts as proxy traffic.
| Order size | Per GB | Saving |
|---|---|---|
| 1 to 4 GB | EUR 1.99 | |
| 5 to 24 GB | EUR 1.79−10 % | |
| 25 to 49 GB | EUR 1.49−25 % | |
| 50 to 99 GB | EUR 1.29−35 % | |
| 100 to 249 GB | EUR 1.09−45 % | |
| 250 GB and more | EUR 0.89−55 % |
GB never expire. What you buy stays on your balance until you use it; a new purchase adds to the same balance. The trial is 1 GB for EUR 1.49, once per customer. Cryptocurrency network minimums and fees vary.
Agent runs are metered like any other traffic: the same ladder, the same balance, no fee per session or per connection.
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 these examples establish
The argument objects, required purchase inputs and password-masking descriptions were checked against Portproof’s MCP schemas and tool handlers on 20 October 2026. The local MCP suite exercises confirmation, terms refusal and masking with fixtures. This guide does not record a live purchase, gateway benchmark, browser integration or country-verification result.
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
More in Agents and automation
Buy mobile and residential proxy GB
Choose your GB or reserve a mobile device.