How to Manage Proxies with an AI Agent: 4 Real Workflows

Your agent can already write and run a scraper. With an MCP server, it can also manage the proxies underneath it: price a setup, update IP whitelisting, find out why errors went up, and handle renewals. Here are four workflows, each with the prompt, what the agent does, and what you get back.

• Source: https://papaproxy.net/blog/manage-proxies-with-ai-agent.php
• Published: 2026-10-05
• Author: Alex Young
• Category: Automation · PapaProxy.net Blog

What your agent can do with your proxy account

The PapaProxy.net MCP server is a remote Model Context Protocol server that exposes 50 tools for your proxy account: stock and pricing, orders and renewals, IP whitelisting, credentials, IP refreshes, usage analytics, billing, and support tickets. It works with Cursor, Claude Code, and any MCP client that supports remote servers with custom headers. Access is included with every account at no additional charge.

The full list of tools and endpoints is on the developer page. This article focuses on how those tools fit together in practice.

Before you start: two keys instead of one

Every API key has an explicit set of scopes, and the MCP server enforces them the same way the REST API does. That makes the key itself your main safety control, so it’s worth creating two of them.

The first is a monitoring key with services:read and usage:read. Use it for everyday questions: what’s active, what expires soon, why errors went up. An agent with this key can see everything about your services and change nothing.

The second is a provisioning key that adds wallet:spend, plus services:write and catalog:read as needed. Switch to it only when the agent actually needs to buy, renew, or pay for an off-cycle IP refresh. Without wallet:spend, the agent can analyze, calculate, and configure, but it can’t pay for anything.

The scopes table on the developer page lists what each scope allows.

Workflow 1: Price a proxy setup without buying anything

Key: none. Country stock and quotes are public.

Prompt: the “Try it without a key” prompt from the developer page works as is:

Read https://papaproxy.net/developers.md. Using the public endpoints described there (no API key needed), show which countries have datacenter proxies in stock right now and quote 100 US IPs for 1 month. Then tell me what you could do with my PapaProxy.net account once I connect the MCP server with an API key.

What the agent does: it reads the developer brief, calls the public country list to check stock, and requests a quote for the mix. Ask it to repeat the quote for 3, 6, and 12 months, and it shows the term discount side by side. With the MCP server connected, the same steps run through the list_countries and quote_composite tools.

You can make the request as specific as your project: “300 IPs in the US and 200 in Germany” or “1,000 ISP proxies across the US and Spain for 3 months.” If a country doesn’t have enough IPs in stock, the quote says so before you spend anything.

Result: a priced configuration from a single prompt, before you even create an account. It’s a quick way to compare configurations, for example a single country against a country mix, or datacenter against ISP proxies.

Workflow 2: Your office IP changed

Key: services:read and services:write.

Prompt:

Our office IP changed to 198.51.100.24 — update IP whitelisting on all active services.

What the agent does: it lists your services and keeps the active ones. For each service, it reads the current whitelist entries, adds the new address with add_whitelist_ip, and removes the old one. A good habit is to tell it the old address too, or ask it to confirm which entry to replace, so it doesn’t remove an address your servers still use. Adding the new IP before removing the old one also avoids a gap in access.

IP whitelisting accepts single IPv4 addresses, not CIDR subnets, so the agent adds exactly the address you give it.

Result: a summary with one row per service, showing what was removed and what was added. In the Dashboard, the same change means opening each service, finding its whitelist, adding the new IP, and deleting the old one. With 5–10 services, that’s dozens of clicks, and it’s easy to miss one.

Workflow 3: Errors went up — find out why

Key: usage:read for the analysis. services:write for replacing IPs, plus wallet:spend if the replacement is paid.

Prompt:

Why did errors increase on my datacenter plan yesterday? Break them down by category.

What the agent does: this is where an agent does more than execute a command. It compares usage over time with get_usage_timeseries to find when the errors started, breaks them down by category and status code with get_diagnostics, and looks at which target hosts are affected. Then it uses get_recommendations to suggest what to change.

The breakdown usually points to one of a few causes. Authentication errors across all hosts typically mean a credentials or IP whitelisting problem on your side. Errors concentrated on one target site, such as HTTP 403 or 429, suggest that site is rate-limiting or blocking specific IPs. Timeouts that cluster at certain hours often point to concurrency or request rate.

If a handful of IPs are getting blocked on one site, follow up with:

Replace only the IPs that are getting blocked.

The agent can refresh specific addresses instead of the whole list. Before it does, ask it to check whether the next refresh is free or paid: scheduled refreshes are free, while an off-cycle refresh is charged to your balance and needs wallet:spend.

Result: a diagnosis with numbers behind it and a targeted fix, instead of refreshing the entire datacenter proxy list and hoping the errors go away.

Workflow 4: Monthly housekeeping

Key: services:read for the review. Renewals also need services:write and wallet:spend.

Prompt:

Which services expire this month, and which of them have auto-renewal turned off?

What the agent does: it lists your services with their expiration dates and auto-renewal status, and flags the ones that will lapse. From there, you can ask it to turn on auto-renewal or renew a service right away, for 1, 3, 6, or 12 months, with the term discount applied.

Before anything is paid, ask the agent to show the total and wait for your confirmation. Cursor and Claude Code also typically ask you to approve each tool call unless you’ve turned on automatic approval.

Result: a renewal review that takes one prompt instead of a pass through every service, and no payment happens without your explicit yes.

What the agent can’t do

The boundaries are set by the key and the billing system, not by the agent’s judgment:

• Without wallet:spend, it can’t pay. A key without that scope can read, quote, and configure, but every purchase, renewal, and paid refresh is rejected.
• It pays only from your balance. Card details stay with the payment processor and aren’t available to the agent.
• A retry doesn’t create a second order. Orders, renewals, paid IP refreshes, and top-ups accept an idempotency key, so a repeated request returns the original result instead of charging again.
• You can revoke the key at any time. Each key shows when and from which IP it was last used.

More details are in the safeguards section of the developer page.

Connect in two minutes

First, create an API key in the Dashboard under Settings → API keys, with the scopes from the section above.

Cursor: install the server in one click, then replace fb_YOUR_API_KEY with your key in the MCP settings.

Claude Code: run one command:

BashCopy code

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

For other clients and the manual mcp.json configuration, see MCP server setup. Ready-to-use configuration files are also in our GitHub repository.

When to move from MCP to the API

MCP is best for one-off tasks and troubleshooting: you describe the outcome, and the agent figures out the calls. That flexibility comes with a cost: the agent interprets your request each time, so the exact sequence of calls can vary from run to run.

When a workflow starts repeating on a schedule, move it into code. Updating IP whitelisting on every deploy, fetching a fresh proxy list before each scraper run, or exporting invoices at the end of the month are all better as a script that calls the REST API and reacts to webhooks. A script runs the same calls every time, and you can test it.

The agent helps with that step too. Ask it to perform the operation once and show you the raw API response, then write the same call in code. The API reference documents every endpoint, and the OpenAPI specification can be loaded into code generators or read by the agent directly.

FAQ

Can the agent see my proxy passwords?

Yes, if its key has services:read. That scope includes proxy credentials: passwords are masked by default, but the agent can request them in plain text. This is why the key shouldn’t be pasted into prompts or committed to a repository. Keep it in your MCP client configuration or a secrets manager.

What if the agent orders the wrong thing?

Ask for a quote before any order, and give the agent a key with wallet:spend only when you actually plan to buy. If a wrong service is ordered anyway, you can cancel it: unused paid time is refunded to your balance on a prorated basis. The guarantees and refund policy explains the terms in detail.

Can my whole team use it?

Yes. You can create as many API keys as you need and name them however you like, so the setup is up to you: one key per person, one per integration, or one per environment. Separate keys let you revoke one without affecting the others, and each key shows when and from which IP it was last used.

Does the agent need to know the API?

No. The MCP server describes each tool to the agent, and the agent picks the right ones from your request. You describe what you need in plain English.