proxies-sx-mcp-server
CLAUDE.md0 starsChanged 28 days agoMITView on GitHub
This is an MCP (Model Context Protocol) server that enables AI agents to manage mobile proxy infrastructure on Proxies.sx. It supports two authentication modes: Package: @proxies-sx/mcp-server npm: https://www.npmjs.com/package/@proxies-sx/mcp-server License: MIT Node.js: >= 18.0.0
- Reads credentials
- Installs packages
In this repositoryOne other file it gives its agents.
The file
Files
CLAUDE.md - AI Assistant Context for @proxies-sx/mcp-server
Project Overview
This is an MCP (Model Context Protocol) server that enables AI agents to manage mobile proxy infrastructure on Proxies.sx. It supports two authentication modes:
- API Key Mode - For users with Proxies.sx accounts
- x402 Payment Mode - Autonomous USDC payments without accounts
Package: @proxies-sx/mcp-server
npm: https://www.npmjs.com/package/@proxies-sx/mcp-server
License: MIT
Node.js: >= 18.0.0
Architecture
proxies-sx-mcp/
├── src/
│ ├── index.ts # Entry point (CLI with shebang)
│ ├── server.ts # MCP server setup & config loading
│ ├── api/ # API Key mode - REST client
│ │ ├── client.ts # HTTP client with auth headers
│ │ ├── auth.ts # Login & JWT token handling
│ │ ├── types.ts # TypeScript interfaces
│ │ ├── account.ts # Account/balance API
│ │ ├── ports.ts # Port CRUD operations
│ │ ├── rotation.ts # Port rotation API
│ │ ├── billing.ts # Purchases API
│ │ ├── payments.ts # Crypto payments (CoinGate) + card top-up (Stripe Checkout)
│ │ ├── private-modems.ts # Private modems: catalog, orders (Idempotency-Key), renew, rotate
│ │ └── reference.ts # Countries/cities/carriers
│ ├── tools/ # MCP tool definitions (API-key tools; 20 listed by default, all with --toolset=full)
│ │ ├── index.ts # Tool registry (exports all tools)
│ │ ├── account.ts # get_account_summary, get_account_usage
│ │ ├── ports.ts # create_port, delete_port, etc.
│ │ ├── status.ts # get_port_status, ping_port, etc.
│ │ ├── rotation.ts # rotate_port, configure_auto_rotation
│ │ ├── billing.ts # purchase_shared_traffic, etc.
│ │ ├── reference.ts # list_available_countries, etc.
│ │ ├── utilities.ts # get_proxy_connection_string, etc.
│ │ ├── payments.ts # proxies_topup_checkout/status, create_crypto_payment, etc.
│ │ ├── private-modems.ts # proxies_modem_catalog/quote/buy/renew/rotate/mine
│ │ ├── structured.ts # structured() result + confirm: true check shared by the spending tools
│ │ ├── support.ts # create_support_ticket, etc.
│ │ └── x402-session.ts # get_x402_session, list_x402_ports
│ ├── x402/ # x402 Protocol - autonomous payments (19 tools)
│ │ ├── index.ts # x402 module setup
│ │ ├── client.ts # x402 HTTP client (402 flow)
│ │ ├── wallet.ts # USDC wallet & transaction signing
│ │ ├── handlers.ts # x402 tool implementations
│ │ ├── session-cache.ts # Local session caching
│ │ ├── tools.ts # x402 tool definitions
│ │ └── types.ts # x402 TypeScript types
│ └── utils/
│ └── formatting.ts # Text formatting helpers
├── tests/ # Test files
├── dist/ # Compiled output (generated)
├── package.json
├── tsconfig.json
├── README.md # User documentation
├── CLAUDE.md # This file - AI context
├── llm.txt # AI discovery document
└── LICENSEKey Files
Entry Point (src/index.ts)
#!/usr/bin/env node
import { startMcpServer, getConfigFromEnv } from './server.js';
async function main() {
const config = getConfigFromEnv(); // Reads environment variables
await startMcpServer(config); // Starts stdio transport
}
main();Server Configuration (src/server.ts)
Handles environment variable parsing and MCP server initialization:
PROXIES_API_KEY- API key authenticationAGENT_WALLET_KEY- x402 wallet private keyPROXIES_API_URL- Custom API base URL (default:https://api.proxies.sx; a trailing/v1is accepted)PROXIES_TOOLSET/--toolset=full- list every API-key tool instead of the default 20 (DEFAULT_TOOL_NAMESinsrc/tools/index.ts)PREFERRED_NETWORK-baseorsolanafor x402BASE_RPC_URL- Custom RPC endpoint
API Client (src/api/client.ts)
HTTP client that:
- Adds
X-API-Keyheader for API key auth - Adds
Authorization: Bearerfor JWT auth - 30-second timeout on all requests
- Automatic error handling and user-friendly messages
x402 Wallet (src/x402/wallet.ts)
Handles USDC transactions on Base network:
- Uses
viemlibrary for Ethereum interactions - Signs ERC-20 transfers using private key
- 60-second transaction confirmation timeout
- Balance checking before transactions
API Integration
Backend API
Base URL: https://api.proxies.sx/v1
Authentication:
- API Key:
X-API-Key: psx_...header - JWT:
Authorization: Bearer <token>header - x402 Session:
X-Session-Token: x402s_...header
Key Endpoints
| Endpoint | Method | Description |
/v1/ports | GET | List all ports |
/v1/ports | POST | Create port |
/v1/ports/:id | DELETE | Delete port |
/v1/ports/:id/rotate | POST | Rotate port IP |
/v1/account | GET | Account summary |
/v1/x402/proxy | GET/POST | Purchase proxy (402 flow) |
/v1/x402/countries | GET | Available countries |
/v1/x402/calculate | GET | Calculate cost |
/v1/x402/manage/session | GET | Session details (X-Session-Token) |
/v1/x402/manage/session/credit | GET | Check remaining credit |
/v1/x402/manage/ports | GET | List ports in session |
/v1/x402/manage/ports/:id/status | GET | Port status |
/v1/x402/manage/ports/recreate | POST | Recreate deleted port (free) |
/v1/x402/manage/ports/replace | POST | Replace offline port (free, max 3) |
/v1/x402/manage/session/topup/calculate | GET | Preview top-up cost |
/v1/x402/manage/session/topup | POST | Pay to extend session (duration-only is FREE - used by x402_extend_session) |
/v1/x402/pool/pricing | GET | Pool Gateway tier catalog (no auth) |
/v1/x402/pool | GET/POST | Buy Pool Gateway access (402 flow, Payment-Signature) |
/v1/x402/manage/pool/credit | GET | Pool credit (X-Session-Token) |
/v1/x402/manage/pool/topup | POST | Pool top-up (X-Session-Token; traffic paid, duration free) |
/v1/x402/manage/pool/regenerate | POST | Rotate pool credential secret (X-Session-Token) |
/v1/x402/manage/pool/connection | GET | Re-emit pool credentials (X-Session-Token) |
/v1/x402/manage/pool/usage | GET | Per-day MB usage series (X-Session-Token) |
/v1/gateway/pool/stock | GET | Public pool stock counts per country (no auth) |
/v1/gateway/credentials | GET | Own pool proxyUsername + connect strings (JWT/API key) |
/v1/gateway/pool/my-stats | GET | Own pool usage + aggregated pool health (JWT/API key) |
/v1/account/proxy-password | PATCH | Set/update the separate proxy auth password (JWT/API key) |
/v1/reseller/pool-keys/:id | PATCH | Update a Pool Access Key (label/enabled/cap/expiry/qualityTier) |
/v1/reseller/pool-keys/:id | DELETE | Delete a Pool Access Key |
/v1/reseller/pool-keys/:id/regenerate | POST | Rotate a Pool Access Key's secret |
/v1/reseller/pool-keys/:id/reveal | POST | Reveal the full pak_ secret (audit-logged) |
/v1/reseller/pool-keys/:id/usage | GET | Daily in/out MB series for one key |
/v1/reseller/pool-keys/:id/audit | GET | Forensic audit log for one key |
Full API Documentation: https://proxies.sx/docs
x402 Protocol
Overview
The x402 protocol enables machine-to-machine payments using HTTP 402 Payment Required.
Flow
- Agent requests
/v1/x402/proxy?country=US&duration=3600&traffic=1 - Server returns 402 Payment Required with payment requirements
- Agent signs USDC transaction using
viem - Agent retries request with
payment-signatureheader - Server verifies payment on-chain
- Server returns proxy credentials
Payment Networks
| Network | USDC Contract | Recipient Wallet |
| Base | 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 | 0xF8cD900794245fc36CBE65be9afc23CDF5103042 |
| Solana | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v | 6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv |
Pricing
Duration is always FREE — you only pay for traffic.
| Tier | Port Price | Traffic/GB | Min Purchase |
| Shared | FREE | $4.00 | 0.1 GB ($0.40) |
Available countries (dedicated mbl modem tier): US, GB, FR, NL, PL, GE (the peer network / Pool Gateway covers ~80 more)
Tools
Counts drift:
npm run build:manifestprints the live numbers and regeneratestools.json,manifest.jsonand the tool tables in README/SKILL/llm.txt. As of 3.1.0: 96 API-key tools (20 listed by default) + 16 wallet tools. The list below is older and kept as a map of the groups. Includes the ops group (11 — admin/ops agent, scoped+capped+audited), the API-key pool group (16 — Pool Gateway: stock, DSL URL builder, sessions, own credentials/stats/proxy-password, pak mint/list/topup/update/regenerate/reveal/delete/usage/audit), and the wallet-side x402 pool group (8 — buy Pool Gateway access with USDC: purchase, credit, topup, regenerate, connection, usage, pricing, public stock). Source of truth:agents-landing/docs-manifest.json(validate withnpm run check:sync).
API Key Mode (70 Tools)
Account Tools:
get_account_summary- Balance, slots, traffic usageget_account_usage- Detailed traffic breakdown
Port Management (7 tools):
list_ports- List all proxy portsget_port- Get port detailscreate_port- Create new portdelete_port- Delete portupdate_port_credentials- Change login/passwordupdate_os_fingerprint- Set OS spoofingreconfigure_port- Change port location
Status Tools (4 tools):
get_port_status- Online/offline statusget_port_ip- Current public IPping_port- Connectivity testspeed_test_port- Download/upload speed
Rotation Tools (5 tools):
rotate_port- Rotate to new IPcheck_rotation_availability- Check cooldownconfigure_auto_rotation- Set intervalget_rotation_history- View historyget_rotation_token_url- Public rotation URL
Billing Tools (3 tools):
get_pricing- Current pricingcalculate_price- Calculate price with volume discountspurchase_shared_traffic- Buy shared GB ($4/GB, auto-upgrades slot tier)
Crypto Payment Tools (5 tools):
create_crypto_payment- Create CoinGate ordercheck_crypto_payment_status- Check statusget_pending_crypto_payments- List pendingcancel_crypto_payment- Cancel paymentget_crypto_payment_info- Supported currencies
Reference Tools (1 tool):
list_available_countries- Available countries (cities/carriers/regions removed Jan 2026)
Utility Tools (3 tools):
get_proxy_connection_string- Generate connection stringget_all_proxy_formats- Get all formatsget_os_fingerprint_options- List OS options
Support Tools (5 tools):
create_support_ticket- Create ticketlist_my_tickets- List ticketsget_ticket- Get detailsreply_to_ticket- Replyclose_ticket- Close ticket
x402 Session Management (8 tools):
get_x402_session- Session detailslist_x402_ports- Ports in sessionget_x402_port_status- Port statusget_sessions_by_wallet- Sessions by walletget_session_status- Quick statusreplace_x402_port- Replace offline port (free, max 3)calculate_x402_topup- Preview top-up costtopup_x402_session- Pay to extend session
Ops Tools (admin/ops agent, 11 tools):
ops_get_user- Customer 360 view (balance, gateway usage, ports, farmer note)ops_get_user_audit- Recent ops-agent actions on a userops_reconcile_payments- Read-only Stripe-vs-DB payment viewops_list_tickets- List support tickets (admin view)ops_reply_ticket- Post an admin reply to a ticketops_set_slots- Set a user's port slot limits (capped)ops_credit_balance- Credit a user's balance (capped + audited)ops_email_user- Send a personalized email (rate-capped)ops_list_farmers- List farmer AI notesops_get_farmer- Farmer fleet funnel + AI noteops_write_farmer_note- Write/append a farmer AI note
Pool Gateway Tools (16 tools):
pool_get_stock- Live availability, online counts per country (no auth)pool_build_proxy_url- In-tool DSL builder (no network call)pool_list_sessions- List live sessions (optional pakId scope)pool_close_session- Close one live sessionpool_get_my_credentials- Own proxyUsername + connect stringspool_get_my_stats- Own usage + aggregated pool healthpool_set_proxy_password- Set/update proxy auth passwordpool_mint_key- Mint a Pool Access Key (reseller)pool_list_keys- List Pool Access Keys (masked, reseller)pool_update_key- Update label/enabled/cap/expiry/qualityTier (reseller)pool_topup_key- Atomically add cap/extend expiry (reseller)pool_regenerate_key- Rotate a key's secret (reseller)pool_reveal_key- Reveal full pak_ secret, audit-logged (reseller)pool_delete_key- Delete a key (reseller)pool_key_usage- Daily in/out MB series for one key (reseller)pool_key_audit- Forensic audit log for one key (reseller)
x402 Mode (19 Tools)
x402_get_proxy- Purchase proxy with USDCx402_get_pricing- Calculate costx402_wallet_balance- Check wallet balancex402_list_sessions- List active sessionsx402_check_session- Session detailsx402_rotate_ip- Rotate IPx402_extend_session- Extend session duration for FREE (duration-only top-up viaPOST /v1/x402/manage/session/topup; accepts session ID or x402s_ token)x402_list_countries- Available countriesx402_list_cities- Cities in countryx402_list_carriers- Carriers in countryx402_service_status- Health check
x402 Pool Gateway (wallet-side, 8 tools):
x402_get_pool_access- Buy Pool Gateway access with USDC (one credential, every country in tier, username DSL, HTTP :7000)x402_pool_credit- Remaining pool credit (GB, pak-backed)x402_pool_topup- Add GB (paid, $4/GB) and/or duration (free)x402_pool_regenerate- Rotate pool credential secret (same username)x402_pool_connection- Re-emit pool credentials (recovery)x402_pool_usage- Per-day MB usage series (default 30d, max 365d)x402_pool_pricing- Pool tier catalog (no auth)get_pool_stock- Public stock counts per country, no IPs (no auth)
Development
Commands
npm install # Install dependencies
npm run build # Build TypeScript
npm run dev # Watch mode development
npm run start # Run compiled server
npm test # Run tests
npm run lint # ESLintTesting with Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"proxies-sx": {
"command": "node",
"args": ["/path/to/proxies-sx-mcp/dist/index.js"],
"env": {
"PROXIES_API_KEY": "psx_your_key"
}
}
}
}Adding New Tools
- Define the tool in appropriate
src/tools/*.ts:
export const myNewTool: Tool = {
name: 'my_new_tool',
description: 'Description of what it does',
inputSchema: {
type: 'object',
properties: {
param1: { type: 'string', description: 'Parameter 1' }
},
required: ['param1']
}
};- Add handler in
src/tools/index.ts:
case 'my_new_tool':
return await handleMyNewTool(args);- Implement handler:
async function handleMyNewTool(args: any) {
const result = await apiClient.get('/endpoint');
return {
content: [{ type: 'text', text: JSON.stringify(result) }]
};
}Security Notes
- API keys are read from environment variables only
- Private keys for x402 are stored in memory
- No secrets are hardcoded in source code
.envfiles are gitignored
Wallet Addresses (Public - Safe to Commit)
- Base recipient:
0xF8cD900794245fc36CBE65be9afc23CDF5103042 - Solana recipient:
6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv - Base USDC:
0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 - Solana USDC:
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
Links
- Proxies.sx: https://proxies.sx
- Customer Portal: https://client.proxies.sx
- API Documentation: https://proxies.sx/docs
- MCP Integration: https://proxies.sx/mcp
- x402 Protocol: https://proxies.sx/x402
- npm Package: https://www.npmjs.com/package/@proxies-sx/mcp-server
- GitHub: https://github.com/bolivian-peru/proxies-sx-mcp-server
Last Updated: 2026-10-28
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
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.

