io.github.bolivian-peruPublished by GitHub account bolivian-peruv3.2.0Updated Oct 30, 2026
Residential and mobile proxies and Private modems for AI agents: proxy URLs, stock, rotation, top-up
Lets an assistant check residential and mobile proxy stock, build rotating or sticky proxy URLs, and buy or manage Proxies.sx proxy traffic and modems.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.bolivian-peru%2Fproxies-sx-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"proxies-sx": {
"type": "http",
"url": "https://api.proxies.sx/mcp"
}
}
}[npm version] [License: MIT] [Proxies.sx MCP server on Glama]
MCP (Model Context Protocol) server for Proxies.sx: residential and mobile proxies for AI agents, metered per GB. Claude, Cursor and any MCP client can get rotating or sticky HTTP/SOCKS5 proxy URLs, check live stock per country, rotate IPs and manage usage by themselves, for web scraping, data collection and browser automation.
The main product is the Pool Gateway: one endpoint, gw.proxies.sx (HTTP 7000, SOCKS5 7001), where the proxy username says which pool, country and session you want. With this server an agent reads live stock, gets its credentials, builds the proxy URL, watches usage and opens a support ticket when something is wrong. For a dedicated, unlimited-traffic device it rents a Private modem (one 4G/5G modem, by the day, week or month) and tops up the balance by card through a link a person pays. It can also manage dedicated ports on carrier modems, Private Pools and Reserved IPs.
Every tool carries MCP annotations (readOnlyHint, destructiveHint), so a client can ask before a delete, rotate, cancel or purchase. The tools that spend money do nothing until the agent passes confirm: true, which it sets only after the user agreed to the exact USD amount.
Or install it as a Claude Code plugin, which connects to the hosted server below, adds the Proxies.sx skill and asks for your API key once (stored masked in secure storage):
Or connect to the hosted server, with nothing to install: https://api.proxies.sx/mcp (Streamable HTTP). Send the key as Authorization: Bearer psx_...; without a key only the public tools are listed (stock, proxy URL format, error help, service status).
Add ?toolset=full to the URL for every API-key tool. The x402 wallet mode runs only locally (npx), because the hosted server never holds a wallet key.
Check Pool Gateway stock for Germany, then give me a sticky residential proxy URL there.
The agent calls pool_get_stock, pool_get_my_credentials and pool_build_proxy_url and answers with a URL such as http://psx_abc123-peer-de-iptype-residential-sid-job1-rot-sticky:[email protected]:7000.
A customer key can hold: ports:read, ports:write, ports:rotate, billing:read, account:read, account:write, traffic:read, tickets:read, tickets:write. Select all of them for the full customer tool set. Two opt-in scopes are never in the default set and must be ticked on purpose: modems:purchase (proxies_modem_buy, proxies_modem_renew) and billing:topup (proxies_topup_checkout, proxies_topup_status; each key has a daily top-up cap, spendCapUsdPerDay, default 100 USD, set in the dashboard).
billing:write is not available to customer keys. The tools that need it (purchase_shared_traffic, create_crypto_payment, cancel_crypto_payment) work with reseller and admin keys only; a customer buys traffic in the dashboard.pak_ key tools (pool_mint_key and the other pool_*_key tools) need a reseller account, whose keys hold customers:read and customers:write.ops_* tools answer only to admin keys with ops:* scopes.The username grammar is psx_<account>-<pool>-<country>[-token-value ...]. pool_build_proxy_url writes it for you; these are the rules behind it.
peer is the main network: residential and mobile devices in most countries. mbl is carrier modems in exactly six countries: US, GB, FR, NL, PL and GE. GE is Georgia, not Germany, so mbl-de never works: use peer-de. any and best let the gateway choose. pool_get_stock shows what is online now.-iptype-mobile, -iptype-residential or -iptype-isp. The ISP (static) class is addresses on ISP-registered networks hosted on servers; it is served only when you name it.sticky and hard both hold one device. auto5, auto10, auto20 and auto60 move to another device on that interval (auto10 is the default). ondemand picks again on each new connection.-sid-. sticky, hard and auto* only persist across connections when the username carries -sid-<id> (lowercase letters, digits and _). -session- is not a token: the gateway ignores it without an error.get_pricing reads the live price list. Both pools cost the same.pool_get_my_credentials), or a pak_ key. It is not the account login password.The gateway answers a failed request with CODE: message (req: id). pool_explain_error turns any of them into what to do next.
A tool that fails returns an MCP error result (isError: true) whose text ends with a What to do: line for the common cases: a missing or revoked API key, a missing scope, a rate limit, a server error. Keys and passwords are masked in error text.
By default the server lists 20 tools, grouped by what an agent does: buy (proxies_modem_catalog, proxies_modem_quote, proxies_modem_buy, proxies_modem_renew, proxies_topup_checkout, proxies_topup_status, get_pricing), use (pool_get_stock, pool_get_my_credentials, pool_build_proxy_url, pool_explain_error, proxies_modem_mine, proxies_modem_rotate) and manage (get_account_summary, get_account_usage, pool_set_proxy_password, get_service_status, create_support_ticket, list_my_tickets, get_ticket). Fewer tools in the list means a client picks the right one more often.
Everything else (dedicated ports, Private Pools and Reserved IPs, crypto orders, coupons, pak_ keys, x402 session management, ops) is listed with the full toolset:
The wallet tools are not affected by the toolset: they are always listed when AGENT_WALLET_KEY is set. The tool tables below mark the default tools.
Every client runs the same command, npx -y @proxies-sx/mcp-server, with PROXIES_API_KEY in the environment.
Add -s user to make it available in every project. A project can instead carry a .mcp.json in its root with the JSON below.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart Claude Desktop:
The same JSON in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).
The same JSON in ~/.codeium/windsurf/mcp_config.json.
The container speaks MCP over stdio (-i is required).
recipes/ has working examples for LangChain, CrewAI and a raw MCP client.
Generated from the code of version 3.2.0 by npm run build:manifest. Do not edit by hand.
The 20 tools marked "Default" are listed without a flag; the others need --toolset=full (or PROXIES_TOOLSET=full). Wallet tools are always listed when a wallet is set.
Pool Gateway
Private modems
Private Pool and Reserved IPs
Account
Billing
Crypto payments
Dedicated ports
Port status
Port rotation
Utilities
Support
Pool access keys (reseller accounts)
x402 session management
Ops (admin keys only)
x402 wallet (optional, no account)
tools.json carries the same list in machine-readable form (name, category, title, first sentence of the description, read-only and destructive flags, mode, parameters).
A Private modem is one dedicated 4G/5G modem rented whole, by the day, week or month, with unlimited traffic, paid from the account balance. It is the first answer to a request for a dedicated, unlimited, exclusive-device, p0f or OpenVPN proxy; per-GB traffic stays on the Pool Gateway.
expectedPriceUsd; the API refuses a stale price with price_changed. They send an Idempotency-Key and return it: retry a failed call with the same idempotencyKey and you get the same order, never a second charge. After insufficient_balance nothing is charged; top up, then order again with a new key.proxies_topup_checkout {amountUsd, confirm: true} returns a Stripe Checkout url that a person opens and pays by card (the agent cannot pay it); proxies_topup_status {sessionId} says when the balance is credited.proxies_modem_mine for its owner only. Do not publish it.A dedicated port binds one port to one carrier modem. Modems exist only in US, GB, FR, NL, PL and GE (Georgia); list_available_countries shows where a modem is free right now. For every other country use the Pool Gateway.
rotate_port moves the port to another modem. The login and password stay, the port numbers change, and one rotation per 5 minutes is allowed.reconfigure_port creates a new port in another location and removes the old one: the port ID changes.A Private Pool is a separate gateway credential limited to the countries you choose and paid from the account's GB balance (private_pool_build). A Reserved IP holds one device for that pool alone (reserved_ip_reserve) until you release it or the idle window ends. The server keeps part of each country's stock unreserved and limits how long a peer device can be held; when it refuses a reservation, its message says why. The ISP (static) class cannot be reserved.
The connection strings of a pool or a Reserved IP come back with pak_******** as the password: put the key from private_pool_reveal in its place.
reserved_ip_list shows the exit IP last seen on a reserved device. It is shown to the owner only: do not publish it.
An agent with a funded USDC wallet on the Base network can buy traffic without a Proxies.sx account through the x402 protocol: the API answers 402 Payment Required with the price, the server pays on-chain and retries with the transaction hash. Set AGENT_WALLET_KEY to enable the wallet tools.
x402_get_pool_access buys Pool Gateway traffic: one credential for every country of the tier (peer or mbl). x402_pool_pricing reads the live tiers and prices.x402_get_proxy buys one dedicated port on a carrier modem. x402_list_countries shows where one is free, x402_get_pricing the live price.x402_wallet_balance shows both. (The API also accepts USDC on Solana from clients that pay by themselves; this server's wallet pays on Base.)The account path (API key and deposited GB) is the standard one; x402 is an alternative for agents that cannot hold an account.
Devices that share their connection through the peer SDK are paid per GB served. Terms and setup: agents.proxies.sx/peer/skill.md.
PROXIES_API_KEY nor AGENT_WALLET_KEY is set in the environment the client starts the server with.billing:write and customers:* cannot be given to a customer key (see above). modems:purchase and billing:topup are opt-in: tick them when creating the key.price_changed, no_stock, insufficient_balance or spend_cap_reached. The What to do: line is the API's own fix for that code; follow it rather than retrying the same call.proxies_modem_buy answers "confirm is not true". Nothing was bought. Show the user the USD price from proxies_modem_quote and call again with confirm: true once they agree.E_AUTH_INVALID is a wrong proxy password (use pool_get_my_credentials), E_BALANCE_EXHAUSTED is an empty balance (use get_account_usage).E_NO_STOCK_COUNTRY. Nothing is online for that pool, country and filters: check pool_get_stock and pool_get_facets, and remember that mbl exists in six countries only.create_support_ticket tool, client.proxies.sx/tickets or [email protected]MIT License, see LICENSE.
Source: README.md at commit 661bb90
Pool: Get Stock
Get live Pool Gateway stock, no account needed. With a country: the mbl and peer endpoint counts there and the peer counts per class (mobile, residential, isp). Without: totals plus the count per country for both pools. Use it to pick a pool and country before pool_build_proxy_url.
countryPool: Get Targeting Options
List the cities, states, carriers (with ASN and class) and IP classes that have stock in one country, with counts, no account needed. The values are the ones pool_build_proxy_url accepts for city, state, carrier and asn. Pass city, state or carrier to see what remains once that filter is applied.
citypoolstatecarriercountryrequiredPool: Build Proxy URL
Build a ready-to-use Pool Gateway proxy URL (gw.proxies.sx, HTTP 7000 or SOCKS5 7001). Local, no network. Take proxyUsername and password from pool_get_my_credentials (a reseller passes a customer pak_ key as password). pool: "peer" is the main network (residential and mobile, most countries), "mbl" is carrier modems in US, GB, FR, NL, PL and GE (Georgia) only, "any" or "best" let the gateway choose. Rotation: sticky and hard both hold one device, auto5/auto10/auto20/auto60 move to another device on that interval, ondemand picks again on each new connection; sticky, hard and auto* only persist across connections with a sid. Sticky holds the device, not the IP: a mobile carrier can still change the exit IP. The result contains the password.
asnispsidttlcitypoolstateipTypepakKeystrictcarriercountry+5 morePool: Explain Gateway Error
Explain a Pool Gateway error and say what to do about it. Pass the error text your HTTP client got from gw.proxies.sx (it looks like "E_NO_STOCK_COUNTRY: ... (req: ...)") or just the code. Covers E_AUTH_INVALID, E_BALANCE_EXHAUSTED, E_NO_STOCK_COUNTRY, the rate and session limits and the rest. Local, no network.
errorrequiredGet Service Status
Check whether Proxies.sx is healthy right now: open Pool Gateway incidents, the state of the API, gateway and relay, and recent uptime. No account needed. Call it when requests fail with 5xx or E_INTERNAL before retrying in a loop.
Takes no parameters.
100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
claude mcp add proxies-sx -e PROXIES_API_KEY=psx_your_api_key_here -- npx -y @proxies-sx/mcp-server/plugin marketplace add bolivian-peru/proxies-sx-mcp-server/plugin install proxies-sx@proxies-sxclaude mcp add --transport http proxies-sx https://api.proxies.sx/mcp --header "Authorization: Bearer psx_your_api_key_here"{ "mcpServers": { "proxies-sx": { "url": "https://api.proxies.sx/mcp", "headers": { "Authorization": "Bearer psx_your_api_key_here" } } } }npx -y @proxies-sx/mcp-server --toolset=full # or PROXIES_TOOLSET=full in the environmentclaude mcp add proxies-sx -e PROXIES_API_KEY=psx_your_api_key_here -- npx -y @proxies-sx/mcp-server{ "mcpServers": { "proxies-sx": { "command": "npx", "args": ["-y", "@proxies-sx/mcp-server"], "env": { "PROXIES_API_KEY": "psx_your_api_key_here" } } }}docker build -t proxies-sx-mcp https://github.com/bolivian-peru/proxies-sx-mcp-server.gitdocker run -i --rm -e PROXIES_API_KEY=psx_your_api_key_here proxies-sx-mcp1. proxies_modem_catalog {country: "de"} -> plans with carrier, period, price in USD, stock2. proxies_modem_quote {tariffId} -> the current price; show it to the user3. proxies_modem_buy {tariffId, expectedPriceUsd, confirm: true} -> order; returns the Idempotency-Key it used4. proxies_modem_mine -> credentials once the order succeeded (10-60 s)5. proxies_modem_rotate {modemId} -> new IP; proxies_modem_quote {modemId} + proxies_modem_renew to extendnpm installnpm run build # compile to dist/npm test # unit tests: registry, routes, username grammar, error mappingnpm run lintnpm run build:manifest # regenerate manifest.json, tools.json and the tool lists in the docs
# Read-only check of every tool against production (needs a real key, changes nothing):PROXIES_API_KEY=psx_... node tests/live-smoke.mjs