# 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 --- ## Key takeaways - The PapaProxy.net MCP server gives Cursor, Claude Code, and other MCP clients 50 tools for your proxy account, at no additional charge. - Use two keys: a monitoring key for everyday questions and a provisioning key with `wallet:spend` only when the agent needs to buy. - Pricing needs no key at all: country stock and quotes are public. - The strongest use case is diagnosis: the agent compares usage over time, breaks errors down by category, and suggests a fix. - Once a workflow repeats on a schedule, move it into code with the REST API and webhooks. AI agents already write scrapers, run them, and fix them when a target site changes its markup. The proxies underneath those scrapers are usually still managed by hand: log in to the Dashboard, find the right service, copy the IP list, and update IP whitelisting every time a server address changes. That changes when the agent gets access to your proxy account through an MCP server. Instead of switching to the Dashboard, you describe the outcome in the chat, and the agent picks the calls, runs them, and reports back. This article walks through four workflows: pricing a setup, updating IP whitelisting, diagnosing errors, and monthly housekeeping. For each one, you’ll see the prompt, the steps the agent takes, the API key scopes it needs, and the result. ## 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](/developers.php#mcp) 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](/developers.php#scopes) 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](/isp-proxy.php) 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](/server-proxy.php) 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](/developers.php#safety) of the developer page. ## Connect in two minutes First, [create an API key](https://papaproxy.net/account_new/settings#api-keys) in the Dashboard under Settings → API keys, with the scopes from the section above. **Cursor:** [install the server in one click](cursor://anysphere.cursor-deeplink/mcp/install?name=papaproxy&config=eyJ1cmwiOiJodHRwczovL3BhcGFwcm94eS5uZXQvYWNjb3VudF9uZXcvYXBpL3YxL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciBmYl9ZT1VSX0FQSV9LRVkifX0%3D), then replace `fb_YOUR_API_KEY` with your key in the MCP settings. **Claude Code:** run one command: BashCopy code ```bash 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](/developers.php#mcp). Ready-to-use configuration files are also in our [GitHub repository](https://github.com/alexyoungpapaproxy/papaproxy-mcp). ## 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](/developers/reference/) documents every endpoint, and the [OpenAPI specification](/openapi.json) 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](/docs/guarantees.php) 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. [Create an API key](https://papaproxy.net/account_new/settings#api-keys) [Try proxies for 48 hours](/free-test.php) New to the Dashboard? Here’s [what changed in the new Dashboard](/new-dashboard.php).