proxies-sx-mcp-server

name

proxies-sx-mcp-server

description

Manage Proxies.sx mobile/residential proxies, mint x402 USDC sessions, rotate IPs, and consume marketplace data services from any MCP-compatible AI agent (Claude Desktop, Cursor, Windsurf, Continue, Cline, Claude Code). Trigger this skill the moment the user wants to install / configure / use the Proxies.sx MCP server, integrate proxies into a Claude Desktop or Cursor workflow, mint a proxy without an API key (x402 autonomous mode), build an AI scraping agent that buys its own bandwidth, troubleshoot MCP tool errors, or pick between API-key mode and x402 wallet mode. Use it whenever the user mentions "Proxies.sx MCP", "@proxies-sx/mcp-server", "MCP proxy tools", "Claude Desktop proxy", "x402 mcp", "agent proxy purchase", "proxy MCP", or anything implying machine-driven proxy management — even if they don't explicitly ask for "this skill".

Proxies.sx MCP Server

Open-source Model Context Protocol server that exposes 89 typed tools to any MCP-compatible AI agent. Two operating modes:

• API Key mode (MAIN path) — agent acts on behalf of a logged-in Proxies.sx user with deposited GB balance (70 tools: ports, rotation, billing, pool gateway, payments, support, ops, etc.)
• x402 Autonomous mode (optional) — agent pays for its own proxies with USDC on Base or Solana, no human account needed (19 tools: x402_get_proxy, x402_rotate_ip, x402_get_pool_access, …)

API Key mode is the primary, recommended path for most integrations — it's simpler (no wallet/gas handling) and works for anyone with a Proxies.sx account. x402 exists specifically for account-less agents that need to pay per-request with crypto.

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

---

When to use this skill

Use it for any of these intents:

• "Set up Proxies.sx MCP in Claude Desktop / Cursor / Windsurf / Cline / Continue"
• "Configure my agent to buy proxies with USDC"
• "Add the proxy MCP server to my AI workflow"
• "Help me debug an MCP tool error from @proxies-sx/mcp-server"
• "Pick between API key and x402 mode"
• "What tools does the Proxies.sx MCP have?"
• "How do I scrape with mobile IPs from Claude / Cursor?"
• "Use x402 to mint a proxy from my agent"
• "My agent wallet balance is low — top up the session"
• "I need mobile vs residential exit IPs, not just any peer"

If the user mentions any of: @proxies-sx/mcp-server, MCP proxy, x402 MCP, agent-driven proxy buying, AGENT_WALLET_KEY, PROXIES_API_KEY env var, psx_ keys, pak_ keys (in MCP context), or mcp.json configuration — this skill applies.

---

Decide the mode FIRST

Before installing or generating code, ask which mode the user wants. They behave very differently.

Mode A — API Key (70 tools, requires a Proxies.sx account) — MAIN path

Use when the user already has a Proxies.sx account (or is willing to create one and deposit GB) and wants their agent to manage their proxy fleet. This is the default recommendation unless the user specifically needs an account-less, wallet-only agent.

• Tools: account, ports, rotation, billing, pool gateway (16), crypto payments, support tickets, x402 session management, ops (11, admin-only)
• Auth: PROXIES_API_KEY=psx_... env var (mint at client.proxies.sx/account)
• Cost: pays from the user's existing account balance (deposited GB, $4/GB, volume-discounted to $2.40/GB at 250 GB+)

Mode B — x402 Autonomous (19 tools, no account needed) — optional, for account-less agents

Use when the user is building a fully autonomous agent that must pay for its own bandwidth with crypto, with zero human account setup.

• Dedicated-proxy tools: x402_get_proxy, x402_get_pricing, x402_wallet_balance, x402_rotate_ip, x402_list_sessions, x402_check_session, x402_list_countries, x402_list_cities, x402_list_carriers, x402_extend_session, x402_service_status
• Pool Gateway tools: x402_get_pool_access, x402_pool_credit, x402_pool_topup, x402_pool_regenerate, x402_pool_connection, x402_pool_usage, x402_pool_pricing, get_pool_stock
• Auth: AGENT_WALLET_KEY=<base58 Solana key | hex EVM key> env var
• Cost: USDC paid per request from the agent's own wallet (Solana ~$0.0001 gas, Base ~$0.01 gas). $4/GB, metered, volume-discounted to $2.40/GB at 250 GB+.

Mode C — Both at once

The MCP server happily exposes both modes simultaneously. Set both env vars; tools that need API key use it, tools that need wallet use that. Many production setups run both.

---

Install — copy-paste configs

The user just needs one of these blocks in their MCP client's config file. Generate the right one based on their client + chosen mode.

Claude Desktop

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

Mode A (API Key):

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

Mode B (x402 Autonomous):

{
  "mcpServers": {
    "proxies-sx": {
      "command": "npx",
      "args": ["-y", "@proxies-sx/mcp-server"],
      "env": {
        "AGENT_WALLET_KEY": "your_solana_or_base_private_key",
        "PREFERRED_NETWORK": "solana"
      }
    }
  }
}

Mode C (both): combine both env vars in the same env object.

After editing, fully quit Claude Desktop and reopen — MCP servers are loaded at startup.

Cursor

File: .cursor/mcp.json in the project root.

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

Windsurf

Same JSON shape, in ~/.codeium/windsurf/mcp_config.json.

Cline / Continue / Roo Code

All use the same mcpServers JSON format. Drop the same block into their config (paths vary).

Verify install

npx -y @proxies-sx/mcp-server --help
# Should print version + usage.

If your MCP client has a "Tools" panel, you should see 89 tools prefixed proxies-sx (70 if only PROXIES_API_KEY is set, 19 if only AGENT_WALLET_KEY is set). If you see 0, the env vars are missing or the binary failed to download — check the client's MCP error log.

---

Tool catalog

89 tools organized by category. Use the table to pick the right tool for the user's intent.

API Key mode (70 tools)

Category	Count	Representative tools
Account	2	get_account_summary, get_account_usage
Port management	7	list_ports, create_port, delete_port, update_port_credentials, update_os_fingerprint, reconfigure_port, get_port
Port status	4	get_port_status, get_port_ip, ping_port, speed_test_port
Rotation	5	rotate_port, check_rotation_availability, configure_auto_rotation, get_rotation_history, get_rotation_token_url
Billing	3	get_pricing ($4/GB, volume-discounted to $2.40/GB at 250GB+), calculate_price, purchase_shared_traffic
Crypto payments	5	create_crypto_payment, check_crypto_payment_status, get_pending_crypto_payments, cancel_crypto_payment, get_crypto_payment_info
Reference	1	list_available_countries
Utilities	3	get_proxy_connection_string, get_all_proxy_formats, get_os_fingerprint_options
Support	5	create_support_ticket, list_my_tickets, get_ticket, reply_to_ticket, close_ticket
x402 session mgmt	8	get_x402_session, list_x402_ports, get_x402_port_status, get_sessions_by_wallet, get_session_status, , ,

Pool Gateway (16 tools) — the flagship one-port product, self-service + reseller management:

Tool	What it does
pool_get_stock	Online endpoint counts per country (no auth needed)
pool_build_proxy_url	In-tool DSL builder: pool/country/carrier/city/iptype/sid/rot — no network call
pool_list_sessions	List live gateway sessions (traffic, exit IP, country)
pool_close_session	Close one live session
pool_get_my_credentials	Your own proxyUsername + ready-to-use HTTP/SOCKS5 connect strings
pool_get_my_stats	Your own usage + aggregated pool health
pool_set_proxy_password	Set/update your proxy auth password (separate from account login)
pool_mint_key	Mint a Pool Access Key (pak_) for a customer (reseller role)
pool_list_keys	List your Pool Access Keys (masked)
pool_update_key	Update label/enabled/trafficCapGB/expiresAt/qualityTier
pool_topup_key	Atomically add cap/extend expiry
pool_regenerate_key	Rotate a key's secret
pool_reveal_key	Reveal the full pak_ secret (audit-logged)
pool_delete_key	Delete a key
pool_key_usage	Daily in/out MB time-series for one key
pool_key_audit	Forensic audit log for one key

x402 Autonomous mode (19 tools)

Dedicated proxy + session management (11 tools)

Tool	What it does
x402_get_proxy	Buy a dedicated proxy with USDC ($4/GB, metered). Pays on-chain, returns credentials.
x402_get_pricing	Get current pricing ($4/GB, metered, volume-discounted).
x402_wallet_balance	Check the agent's USDC balance on Base + Solana.
x402_list_sessions	List the agent's active sessions.
x402_check_session	Status of a specific session by token.
x402_rotate_ip	Rotate the IP for a session (free).
x402_list_countries	Available countries with live device counts. Currently: US, GB, FR, NL, PL, GE (Georgia).
x402_list_cities	Cities in a country.
x402_list_carriers	Mobile carriers in a country.
x402_extend_session	Extend session duration for FREE (duration-only top-up).
x402_service_status	Health check for the x402 service.

(To add traffic to a dedicated-port session, use calculate_x402_topup / topup_x402_session from the session-management group.)

Pool Gateway access (8 tools) — one credential reaches every country in your tier via the username DSL. v1 tier = mbl ($4/GB, production ProxySmart modems, 6 countries: US/GB/FR/NL/PL/GE, HTTP :7000).

Tool	What it does
x402_get_pool_access	Buy Pool Gateway access with USDC. Returns one DSL credential + caches the session token.
x402_pool_credit	Remaining GB for a pool session (cached token if omitted).
x402_pool_topup	Pay USDC for more GB (duration-only is free).
x402_pool_regenerate	Rotate the credential secret (same username, new password).
x402_pool_connection	Re-emit credentials (recovery).
x402_pool_usage	Per-day MB usage series (default 30 days, max 365).
x402_pool_pricing	Tier catalog + username DSL (no auth needed).
get_pool_stock	Public online endpoint counts per country (no IPs).

Pool quality copy: mbl is the production tier (6 countries: US/GB/FR/NL/PL/GE). Sticky pins the modem, not the IP — carrier NAT may still re-issue the egress IP. On the API-key side, pool_build_proxy_url also supports ipType (mobile/residential/datacenter) to hard-filter the peer pool to one exit class.

---

Common patterns

Generate code that matches the user's intent. Here are the recipes most users want:

"Manage my account's proxies" (API key mode — MAIN path, start here)

1. Tool: list_ports — see what you have
2. Tool: create_port with country="us" — add a new one
3. Tool: get_proxy_connection_string with portId — get formatted URLs
4. Tool: rotate_port — get a new IP on demand
5. Tool: configure_auto_rotation with interval=30 — set up auto IP rotation every 30 minutes

"Get one credential that works for every country in my tier" (API key mode, Pool Gateway)

1. Tool: pool_get_my_credentials — get your proxyUsername + connect strings
2. Tool: pool_build_proxy_url with pool="peer", country="us", ipType="residential", rotation="sticky", sid="job1"
   — builds a URL that hard-filters to residential peer exit IPs in the US, pinned for the session
3. Tool: pool_get_my_stats — check usage

"Buy a proxy and use it" (x402 mode)

1. Tool: x402_get_proxy with country="us", traffic=1
2. Save the returned sessionToken (x402s_...) and proxy credentials
3. Use the proxy in any HTTP client
4. When done, optional: calculate_x402_topup + topup_x402_session to add traffic

"Buy pool access, one credential for every country" (x402 mode)

1. Tool: x402_pool_pricing — see the tier catalog + username DSL (no wallet needed)
2. Tool: get_pool_stock — check which countries currently have capacity
3. Tool: x402_get_pool_access with traffic_gb=5 (tier defaults to mbl)
4. Use the returned credential, switching country via the username DSL:
   psx_xxx-mbl-us, psx_xxx-mbl-pl, ... (HTTP proxy on port 7000)
5. Tool: x402_pool_credit — check remaining GB; x402_pool_topup to add more

"Refill my proxy session before it expires"

1. Tool: x402_check_session with sessionToken — see remaining traffic + duration
2. Tool: calculate_x402_topup with addTrafficGB=2 — preview cost
3. Tool: topup_x402_session with addTrafficGB=2 + paymentSignature — pay USDC and extend

"Replace an offline port for free" (x402 mode)

1. Tool: list_x402_ports with sessionToken — find offline ones
2. Tool: replace_x402_port with portId — get a new port on a different device (free, max 3/session)

"Top up account balance with crypto" (API key mode)

1. Tool: create_crypto_payment with amount=50 — get a payment URL/QR
2. User pays at the URL with any of 50+ supported coins
3. Tool: check_crypto_payment_status with paymentId — confirm
4. Balance auto-credited

---

Environment variables

Var	Required for	Purpose
PROXIES_API_KEY	API key mode	Authenticates as a Proxies.sx user. Format: psx_*. Mint at client.proxies.sx/account.
AGENT_WALLET_KEY	x402 mode	Private key for the agent's wallet. Format: base58 (Solana) or 0x-hex (EVM/Base).
PREFERRED_NETWORK	x402 mode (optional)	solana or base. Defaults to solana (faster + cheaper).
BASE_RPC_URL	x402 mode (optional)	Override default Base RPC. Default uses public Base RPC.
PROXIES_API_URL	optional	Override https://api.proxies.sx/v1 base URL (rarely needed).

---

Errors and how to fix them

Error pattern	Likely cause	Fix
401 Unauthorized on API tool	PROXIES_API_KEY missing/revoked	Re-mint at client.proxies.sx/account
403 Forbidden	API key scope insufficient	Add customers:write (or whichever scope the tool needs)
429 Rate limited	Too many calls in short window	Back off, retry with exponential delay (start 1s)
Insufficient USDC balance from x402 tool	Wallet has no USDC on the chosen network	Top up the wallet, or PREFERRED_NETWORK=solana if cheaper
Tool not found: x402_*	Server started without AGENT_WALLET_KEY	Add the env var, restart the MCP client
MCP server not starting	npm registry / network issue	npx -y @proxies-sx/mcp-server@latest --help to force fresh install
MCP client shows 0 tools	Config syntax error	Validate claude_desktop_config.json is valid JSON; quit + reopen client

The server returns structured errors with a retryable boolean and a suggestion field — surface those to the user verbatim when an error happens.

---

Security non-negotiables

DO NOT skip these. Burn them into any setup the user follows:

1. PROXIES_API_KEY is sensitive. Treat it like a password. Don't paste it in shared chat logs, GitHub gists, or screenshots. If exposed, regenerate it at client.proxies.sx/account.
2. AGENT_WALLET_KEY is even more sensitive. It controls real USDC. Rotate it if exposed; transfer remaining funds to a fresh wallet first.
3. Don't run the MCP server with --inspect or any debugger flag when these env vars are set — heap dumps include them.
4. Audit mcp.json files in project repos before committing; the standard pattern is to use a local .env and reference it indirectly, not inline secrets.
5. The pak_ keys (Pool Gateway sub-keys) are scoped per-customer, not per-agent — a leaked pak_ only consumes the reseller's pool, not the platform's.

---

Pricing rule

Wholesale rates are platform-configurable and change. Don't hardcode dollar amounts when the user asks "how much does X cost". Instead:

• For a precise live answer: Tool: get_pricing (API key mode) or x402_get_pricing / x402_pool_pricing (x402 mode).
• For ballpark guidance: tell the user "$4/GB, volume-discounted to $2.40/GB at 250 GB+ — the live rate is confirmed via the pricing tool, pin nothing in code".

---

Reference files in the repo

File	When to read
README.md	Marketing-friendly overview, install, examples
CHANGELOG.md	Per-version breaking changes (read before bumping major)
CLAUDE.md	Repo invariants for agents working ON the MCP server code
recipes/	Per-framework integration examples (LangChain, CrewAI, raw MCP)
tests/	Verify behavior — useful when debugging tool responses
src/tools/index.ts	Tool registry — every API-key tool's source of truth
src/x402/tools.ts	x402 autonomous tools

---

Smoke test (run before reporting "done")

After setting up, verify the MCP client actually sees the tools.

# 1. Verify the package installs and runs
npx -y @proxies-sx/mcp-server --help
# Should print version + usage info.

# 2. (Optional) Run a single tool via curl-equivalent — only works if the MCP
#    client exposes a way to call tools directly. Most don't, so the real test
#    is asking your AI: "List my proxies via proxies-sx.list_ports"

In Claude Desktop / Cursor: ask the agent to call a tool and watch for the proxies-sx tool icon to appear in the response.

---

Checklist before handing off

• User has psx_* and/or AGENT_WALLET_KEY env vars set
• MCP client config file has the proxies-sx entry
• Client fully restarted (not just window reload)
• User can call at least one tool successfully
• User knows where to mint a fresh API key if leaked: client.proxies.sx/account
• User knows pricing is live (don't quote stale numbers)

---

Links

• npm: https://www.npmjs.com/package/@proxies-sx/mcp-server
• Source: https://github.com/bolivian-peru/proxies-sx-mcp-server
• Customer dashboard MCP page: https://client.proxies.sx/mcp-server
• Master Proxies.sx skill: https://agents.proxies.sx/skill.md
• LLM-friendly API reference: https://api.proxies.sx/v1/reseller/docs/llm
• Telegram support: @proxyforai