agentleFS
bolivian-perubolivian-peru/proxies-sx-mcp-server/SKILL.md

proxies-sx-mcp-server

Skill0 starsChanged 28 days agoMITView on GitHub

Use Proxies.sx residential and mobile proxies from any MCP-compatible AI agent (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue). Trigger this skill when the user wants to install, configure or use the Proxies.sx MCP server, get a proxy URL for the Pool Gateway (gw.proxies.sx), check proxy stock per country, hold a session or an IP, rent or renew a Private modem (a dedicated 4G/5G modem with unlimited traffic), top up the balance by card, manage dedicated mobile ports, read usage and pricing, open a support ticket, debug an MCP tool or gateway error, or let an agent pay for proxies with USDC (x402). Also when the user mentions "@proxies-sx/mcp-server", "Proxies.sx MCP", "proxy MCP", PROXIES_API_KEY, AGENT_WALLET_KEY, psx_ keys or pak_ keys.

  • Reads credentials
  • In this repositoryOne other file it gives its agents.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every client runs npx -y @proxies-sx/mcp-server with the key in the environment.

    line 33
  2. Very specific:

    Do not commit .mcp.json or any config file that carries a key.

    line 343

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Proxies.sx MCP Server

Open-source Model Context Protocol server for Proxies.sx: residential and mobile proxy bandwidth, metered per GB.

Source: https://github.com/bolivian-peru/proxies-sx-mcp-server · npm: @proxies-sx/mcp-server · License: MIT.

What the product is

  • Pool Gateway (the main product): one endpoint, gw.proxies.sx (HTTP 7000, SOCKS5 7001). The proxy username chooses pool, country, IP class, session and rotation. One proxy password works for every country.
  • Private modems: one dedicated 4G/5G modem rented whole, by the day, week or month, unlimited traffic, paid from the account balance. The first answer to any dedicated, unlimited, exclusive-device, p0f or OpenVPN request (proxies_modem_* tools).
  • Dedicated ports: one port bound to one carrier modem, in the few countries that have modems.
  • Private Pools and Reserved IPs: a separate gateway credential scoped to chosen countries, which can hold individual devices for itself.

Pick the mode first

ModeEnvironmentUse it when
API key (standard)PROXIES_API_KEY=psx_...The user has, or can create, a Proxies.sx account with GB on it. This is the default.
x402 wallet (optional)AGENT_WALLET_KEY=0x...The agent must pay by itself in USDC on Base and cannot hold an account.
Bothboth variablesEvery tool of both modes is listed.

Create the key at client.proxies.sx/account. A customer key can hold ports:read, ports:write, ports:rotate, billing:read, account:read, account:write, traffic:read, tickets:read, tickets:write, plus two opt-in scopes that must be ticked on purpose: modems:purchase (buy or renew a Private modem) and billing:topup (card top-up link, under the key's daily cap). It cannot hold billing:write: buying GB through the API is for reseller and admin keys, and a customer buys GB in the dashboard at client.proxies.sx/purchase.

The server lists 20 tools by default (buy, use, manage). Start it with --toolset=full (or PROXIES_TOOLSET=full) for dedicated ports, Private Pools, crypto orders, coupons, pak_ keys and ops tools.

Install

Every client runs npx -y @proxies-sx/mcp-server with the key in the environment.

Claude Code

claude mcp add proxies-sx -e PROXIES_API_KEY=psx_YOUR_API_KEY -- npx -y @proxies-sx/mcp-server

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows), Cursor (~/.cursor/mcp.json or .cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json), Cline, Continue and Roo Code all take the same block:

{
  "mcpServers": {
    "proxies-sx": {
      "command": "npx",
      "args": ["-y", "@proxies-sx/mcp-server"],
      "env": { "PROXIES_API_KEY": "psx_YOUR_API_KEY" }
    }
  }
}

For wallet mode put AGENT_WALLET_KEY in env instead of, or next to, PROXIES_API_KEY. Restart the client after editing its config. To verify, ask the agent to call get_service_status (needs no account) and then get_account_summary.

Pool Gateway rules

Username grammar: psx_<account>-<pool>-<country>[-token-value ...]. Let pool_build_proxy_url write it; it refuses or warns about the mistakes below.

  • peer is the main pool: residential and mobile devices in most countries. mbl is carrier modems in exactly US, GB, FR, NL, PL and GE. GE is Georgia, not Germany: mbl-de never works, use peer-de.
  • IP class: -iptype-mobile, -iptype-residential, -iptype-isp. The ISP (static) class is served only when named.
  • Rotation: sticky and hard both hold one device; auto5/auto10/auto20/auto60 move to another device on that interval; ondemand picks again per connection.
  • sticky, hard and auto* persist across connections only with -sid-<id>. -session- is ignored by the gateway without an error.
  • Sticky holds the device, not the IP: a mobile carrier can change the exit IP. For an address that stays, use a residential peer or a Reserved IP.
  • Limits per account: 500 concurrent connections, 250 sessions.
  • You pay per GB; time is free. Never quote a price from memory: call get_pricing.
  • The gateway password is the proxy password from pool_get_my_credentials (or a pak_ key), not the account login password.

Common tasks

Get a proxy for a country (API key mode: start here)

1. pool_get_stock {country: "de"}            -> what is online there, per pool and class
2. pool_get_my_credentials                    -> proxyUsername and proxyPassword
3. pool_build_proxy_url {proxyUsername, password, pool: "peer", country: "de",
                         ipType: "residential", rotation: "sticky", sid: "job1"}
4. use the returned proxyUrl in any HTTP client

Target a city or carrier: pool_get_facets {country} lists the values with stock; pass one as city, state, carrier or asn to pool_build_proxy_url.

A request through the proxy failed: pass the gateway's error text to pool_explain_error. E_AUTH_INVALID is a wrong proxy password; E_BALANCE_EXHAUSTED is an empty balance (check get_account_usage, the password is fine); E_NO_STOCK_COUNTRY means nothing is online for that pool, country and filters; E_SESSION_LIMIT is cleared with pool_close_all_sessions.

Check balance and usage: get_account_summary, get_account_usage.

Hold one IP for yourself: private_pool_list (or private_pool_build {countries}), then reserved_ip_reserve {poolId, country}; release it with reserved_ip_release. The connection strings come back with pak_******** as the password: put the key from private_pool_reveal {poolId} in its place. The server refuses when a country has too little unreserved stock and says so.

A dedicated port on a carrier modem

1. list_available_countries                   -> countries with a free modem, and their countryId
2. create_port {countryId}                    -> connection strings
3. rotate_port {portId}                       -> another modem; the port numbers change
4. configure_auto_rotation {portId, enabled: true, intervalMinutes: 30}
5. delete_port {portId}

A dedicated device with unlimited traffic (Private modem)

1. proxies_modem_catalog {country: "de"}                        -> plans, price in USD per modem, stock
2. proxies_modem_quote {tariffId}                               -> current price; tell the user and wait for a yes
3. proxies_modem_buy {tariffId, expectedPriceUsd, confirm: true} -> order + the Idempotency-Key it used
4. proxies_modem_mine                                           -> credentials when the order succeeded (poll every 10 s)
5. proxies_modem_rotate {modemId}; proxies_modem_quote {modemId} then proxies_modem_renew {modemId, period, expectedPriceUsd, confirm: true}

Never set confirm: true before the user agreed to the exact USD amount. Retry a failed buy or renew with the same idempotencyKey; after insufficient_balance nothing was charged, so top up and order again with a new key. After price_changed quote again and confirm the new price.

Balance too low: proxies_topup_checkout {amountUsd, confirm: true} returns a Stripe Checkout url and sessionId. A person opens the url and pays by card; the agent cannot. Then proxies_topup_status {sessionId} about every 10 s until credited is true, and get_account_summary.

Reach a person: create_support_ticket {subject, message}, then get_ticket.

Pay with a wallet instead of an account (x402 mode)

1. x402_pool_pricing, pool_get_stock          -> tiers, live prices, stock
2. x402_wallet_balance                        -> USDC and gas on Base
3. x402_get_pool_access {tier: "peer", traffic_gb: 1}   -> pays on-chain, returns one credential
4. pool_build_proxy_url with that username and password
5. x402_pool_credit / x402_pool_topup         -> GB left / add more

Tool catalog

<!-- tools:start -->

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

ToolWhat it does
pool_get_stockGet live Pool Gateway stock, no account needed. Default. Also listed in wallet mode.
pool_get_facetsList the cities, states, carriers (with ASN and class) and IP classes that have stock in one country, with counts, no account needed. Also listed in wallet mode.
pool_build_proxy_urlBuild a ready-to-use Pool Gateway proxy URL (gw.proxies.sx, HTTP 7000 or SOCKS5 7001). Default. Also listed in wallet mode.
pool_explain_errorExplain a Pool Gateway error and say what to do about it. Default. Also listed in wallet mode.
pool_get_my_credentialsGet your Pool Gateway proxy username and proxy password with ready HTTP and SOCKS5 URLs. Default.
pool_set_proxy_passwordSet a new proxy password (at least 6 characters). Default.
pool_get_my_statsGet your own Pool Gateway traffic and open connections, plus the health score of the pool and how many devices are connected to it.
pool_list_sessionsList your saved Pool Gateway sessions: pool, country, carrier, rotation mode, bytes and last activity.
pool_close_sessionClose one Pool Gateway session by the sessionKey from pool_list_sessions.
pool_close_all_sessionsClose every saved Pool Gateway session of the account.

Private modems

ToolWhat it does
proxies_modem_catalogList the Private modem plans for sale right now: country, carrier, period (day, week or month), price in USD, stock, OpenVPN and p0f support, regions. Default.
proxies_modem_quotePrice check before spending. Default.
proxies_modem_buyRent a Private modem (one dedicated 4G/5G modem, unlimited traffic) from the account balance. Default.
proxies_modem_renewExtend the rental of one of your Private modems from the account balance. Default.
proxies_modem_rotateAsk one of your Private modems for a new IP address. Default.
proxies_modem_mineList your rented Private modems: status, expiry, online state, HTTP and SOCKS5 credentials, rotation settings, auto-renew, plus open orders and recent failures. Default.

Private Pool and Reserved IPs

ToolWhat it does
private_pool_listList your Private Pools with their countries, status, gateway username, connection strings with the password masked (private_pool_reveal shows the key) and remaining GB.
private_pool_buildCreate a Private Pool paid from the account's existing GB balance: no purchase, traffic is metered from the same balance.
private_pool_revealShow the gateway password (pak_ key) of a Private Pool.
private_pool_usageGet the traffic of a Private Pool per day, in MB.
reserved_ip_listList the Reserved IPs a Private Pool holds: country, class, carrier, city, rotation mode, whether the device is online, the exit IP last seen, and connection strings with the password masked.
reserved_ip_reserveReserve one device for a Private Pool so no other customer is routed through it, and get its connection strings with the password masked.
reserved_ip_rotateMove a Reserved IP to a different device in the same country now.
reserved_ip_extendChange how long a Reserved IP is kept without traffic.
reserved_ip_set_rotationSet whether a Reserved IP moves to another device on a schedule: off (hold the device, the default) or every 5, 10, 20 or 60 minutes.
reserved_ip_releaseGive a Reserved IP back to the shared pool.

Account

ToolWhat it does
get_account_summaryGet the account balance, free port slots, traffic bought and left, and any account alerts. Default.
get_account_usageGet traffic purchased, used and still available, split into Pool Gateway traffic and dedicated-port traffic. Default.

Billing

ToolWhat it does
get_pricingGet the live price per GB, the volume discounts, the free port-slot tiers and your current tier. Default.
calculate_priceCalculate what a GB amount costs with the volume discount applied.
purchase_shared_trafficBuy traffic in GB from the account balance.
coupon_validateCheck whether a coupon code is valid for an order, without using it.
coupon_redeemRedeem a standalone coupon that grants free GB or port slots to the account.
get_payment_historyList the account's past payments and crypto top-up orders.

Crypto payments

ToolWhat it does
proxies_topup_checkoutAdd money to the account balance by card: creates a Stripe Checkout page and returns its url and sessionId. Default.
proxies_topup_statusCheck whether a card top-up started with proxies_topup_checkout was paid and credited to the balance (credited true or false). Default.
create_crypto_paymentCreate a crypto order that tops up the account balance and return its hosted payment link.
check_crypto_payment_statusCheck whether a crypto order is still unpaid, confirming, paid, expired or cancelled, and whether the balance was credited.
get_pending_crypto_paymentsList the account's crypto orders that are not finished yet, with their payment links.
cancel_crypto_paymentCancel a crypto order that has not been paid yet.
get_crypto_payment_infoCheck whether crypto top-ups are available right now and which currencies the payment page accepts.

Dedicated ports

ToolWhat it does
list_available_countriesList the countries where a dedicated port can be created right now, with the countryId create_port needs.
list_portsList your dedicated ports with status, country, carrier, expiry and port ids.
get_portGet one dedicated port with its location and ready-to-use HTTP and SOCKS5 connection strings (contains the port password).
create_portCreate a dedicated port on a carrier modem and return its connection strings.
delete_portDelete a dedicated port and free its slot.
update_port_credentialsChange the login and/or password of a dedicated port.
update_os_fingerprintSet the OS fingerprint (TCP/IP signature) a dedicated port presents.
reconfigure_portMove a dedicated port to another country, carrier or city.
extend_portAdd hours to a dedicated port's expiry.

Port status

ToolWhat it does
get_port_statusCheck whether a dedicated port is online, offline or expired.
get_port_ipGet the server address a dedicated port listens on.
ping_portTest that a dedicated port answers and measure its latency.
speed_test_portRun a speed test through a dedicated port (download, upload, ping).

Port rotation

ToolWhat it does
rotate_portMove a dedicated port to another modem in the same location.
check_rotation_availabilityCheck whether a dedicated port can be rotated now, how long the cooldown still runs and how many other modems are free.
configure_auto_rotationTurn automatic rotation of a dedicated port on or off and set its interval.
get_rotation_historyGet the past rotations of a dedicated port: when, how triggered, the location it moved to and whether it worked.
get_rotation_token_urlGet the public rotation link of a dedicated port.

Utilities

ToolWhat it does
get_proxy_connection_stringBuild the HTTP or SOCKS5 connection string of a dedicated port (contains the port password).
get_all_proxy_formatsGet a dedicated port in every common format: URLs, host:port, environment variables, curl, Python and Node.js snippets, and its public rotation link.
get_service_statusCheck whether Proxies.sx is healthy right now: open Pool Gateway incidents, the state of the API, gateway and relay, and recent uptime. Default. Also listed in wallet mode.
get_os_fingerprint_optionsList the OS fingerprint values create_port and update_os_fingerprint accept.

Support

ToolWhat it does
create_support_ticketOpen a support ticket that a person at Proxies.sx reads and answers. Default.
list_my_ticketsList your support tickets with their status and IDs. Default.
get_ticketGet one support ticket with the original message and every reply. Default.
reply_to_ticketAdd a reply to one of your support tickets.
close_ticketClose one of your support tickets once the problem is solved.

Pool access keys (reseller accounts)

ToolWhat it does
pool_mint_keyCreate a Pool Access Key (pak_) for one of your customers; it is used as the proxy password.
pool_list_keysList your Pool Access Keys with usage, cap and expiry; the key values are masked.
pool_topup_keyAdd GB to a Pool Access Key's cap and/or extend its expiry in one step.
pool_update_keyChange a Pool Access Key's label, enabled flag, cap, expiry or quality tier.
pool_regenerate_keyReplace the secret pak_ value of a Pool Access Key.
pool_reveal_keyShow the full pak_ value of a Pool Access Key.
pool_delete_keyDelete a Pool Access Key.
pool_key_usageGet the traffic of one Pool Access Key per day, in MB.
pool_key_auditGet the audit log of one Pool Access Key, newest first: created, changed, topped up, regenerated, revealed, deleted, and gateway logins that worked or failed.

x402 session management

ToolWhat it does
get_x402_sessionGet details of your x402 session including all ports.
list_x402_portsList all ports in your x402 session with connection strings and expiration times
get_x402_port_statusGet detailed status of a specific port including traffic usage and connection info
get_sessions_by_walletList all x402 sessions associated with your wallet address.
get_session_statusGet quick status check for a session including traffic usage and expiration
replace_x402_portReplace an offline port of an x402 session with a new port on another device, at no charge.
calculate_x402_topupCalculate what it costs to add traffic and/or time to an x402 session.
topup_x402_sessionAdd traffic and/or time to an x402 session.

Ops (admin keys only)

ToolWhat it does
ops_get_userCustomer 360 view: balance, pool-gateway usage, ports, and (if a farmer) their AI note.
ops_get_user_auditRecent ops-agent actions taken on this user.
ops_reconcile_paymentsRead-only Stripe-vs-DB payment view for a user (confirmed total + pending).
ops_list_ticketsList support tickets (admin view).
ops_reply_ticketPost an admin reply to a ticket, optionally emailing the customer.
ops_set_slotsSet a user's port slot limit (capped).
ops_credit_balanceCredit a user's balance in USD (admin credit).
ops_email_userSend a personalized email to one user (hourly rate-capped).
ops_list_farmersList farmer AI notes (shared operational memory).
ops_get_farmerFarmer fleet funnel (total/online/verified/listed/routable) + AI note.
ops_write_farmer_noteWrite/append a farmer AI note (situation, nextAction, free note) — shared with future AI sessions.

x402 wallet (optional, no account)

ToolWhat it does
x402_get_proxyBuy a dedicated mobile proxy on one carrier modem by paying USDC from the agent wallet; no account needed.
x402_get_pricingGet the live x402 price per GB, the smallest purchase, the allowed duration and the payment networks, and compare the cost of a purchase with the wallet balance.
x402_list_sessionsList the active x402 proxy sessions this wallet bought from this machine, with location, expiry and proxy host.
x402_check_sessionGet status, time left, traffic used and the connection strings of an x402 proxy session.
x402_wallet_balanceGet the agent wallet address and its USDC and ETH (gas) balance on the Base network.
x402_rotate_ipMove an x402 proxy to another modem so it gets a different exit IP.
x402_list_countriesList the countries where x402_get_proxy can create a proxy right now, with the number of free modems.
x402_extend_sessionAdd hours to an x402 proxy session.
x402_service_statusCheck that the x402 payment service is up, and show the wallet balance and how many sessions are active or about to expire.
x402_get_pool_accessBuy Pool Gateway traffic by paying USDC from the agent wallet; no account needed.
x402_pool_creditGet the GB bought, used and left on an x402 pool session.
x402_pool_topupAdd GB and/or time to an x402 pool session.
x402_pool_regenerateReplace the password of an x402 pool credential, for example after a leak.
x402_pool_connectionShow the gateway host, port, username and password of an x402 pool session again.
x402_pool_usageGet the traffic of an x402 pool session per day, in MB.
x402_pool_pricingGet the Pool Gateway tiers that can be bought with x402 and their live price per GB and smallest purchase.
<!-- tools:end -->

Errors

A failing tool returns an MCP error result (isError: true). For the common cases the text ends with a What to do: line; follow it instead of retrying blindly.

ErrorCauseFix
401 on any API toolPROXIES_API_KEY missing, wrong, expired or revokedNew key at client.proxies.sx/account
403 "missing required scope"The key lacks that scopeCreate a key with it. billing:write and customers:* are not available to customer keys; modems:purchase and billing:topup are opt-in ticks
price_changed, no_stock, insufficient_balance, spend_cap_reached, recent_checkout, renewal_openA purchase the API refusedThe What to do: line is the API's own fix for that code
"confirm is not true"A spending tool was called before the user agreedShow the USD amount, get a yes, call again with confirm: true
"Unknown tool" for a port, pool-key or ops toolServer runs the default toolsetStart it with --toolset=full or PROXIES_TOOLSET=full
429Rate limitWait a minute; do not loop
5xxServer-side failureRetry once, then get_service_status
"Insufficient USDC balance" (x402)Wallet cannot cover the priceSend USDC on Base to the wallet address in the message
"Unknown tool: x402_..."Server started without AGENT_WALLET_KEYAdd it and restart the client
Client shows no toolsConfig file is not valid JSON, or no key is setFix the file, restart the client

Security

  1. PROXIES_API_KEY is a password. Never paste it into shared logs, gists or screenshots. If exposed, revoke it at client.proxies.sx/account.
  2. AGENT_WALLET_KEY controls real USDC. Use a wallet that holds only what the agent may spend.
  3. Tools whose description says "Returns a secret" print a proxy password or a pak_ key. Do not log their output.
  4. Do not commit .mcp.json or any config file that carries a key.
  5. The API never returns the exit IP of a dedicated port or pool session. reserved_ip_list shows the exit IP of a device you reserved and proxies_modem_mine the exit IP of your own modem; never publish them.
  6. proxies_modem_buy, proxies_modem_renew and proxies_topup_checkout move money. Set confirm: true only after the user agreed to the exact USD amount, and reuse the returned idempotencyKey for a retry.

Environment variables

VariablePurpose
PROXIES_API_KEYAPI key mode. Format psx_...
PROXIES_EMAIL, PROXIES_PASSWORDAlternative to the API key: account login
AGENT_WALLET_KEYx402 mode: 0x private key of a USDC wallet on Base
BASE_RPC_URLx402 mode, optional: custom Base RPC
PROXIES_API_URLOptional API base. Default https://api.proxies.sx; a trailing /v1 is accepted
PROXIES_TOOLSETdefault (20 tools) or full (every API-key tool); --toolset=full does the same

Links

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.