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

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

The file

Files
CLAUDE.md

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:

  1. API Key Mode - For users with Proxies.sx accounts
  2. 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
└── LICENSE

Key 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 authentication
  • AGENT_WALLET_KEY - x402 wallet private key
  • PROXIES_API_URL - Custom API base URL (default: https://api.proxies.sx; a trailing /v1 is accepted)
  • PROXIES_TOOLSET / --toolset=full - list every API-key tool instead of the default 20 (DEFAULT_TOOL_NAMES in src/tools/index.ts)
  • PREFERRED_NETWORK - base or solana for x402
  • BASE_RPC_URL - Custom RPC endpoint

API Client (src/api/client.ts)

HTTP client that:

  • Adds X-API-Key header for API key auth
  • Adds Authorization: Bearer for 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 viem library 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

EndpointMethodDescription
/v1/portsGETList all ports
/v1/portsPOSTCreate port
/v1/ports/:idDELETEDelete port
/v1/ports/:id/rotatePOSTRotate port IP
/v1/accountGETAccount summary
/v1/x402/proxyGET/POSTPurchase proxy (402 flow)
/v1/x402/countriesGETAvailable countries
/v1/x402/calculateGETCalculate cost
/v1/x402/manage/sessionGETSession details (X-Session-Token)
/v1/x402/manage/session/creditGETCheck remaining credit
/v1/x402/manage/portsGETList ports in session
/v1/x402/manage/ports/:id/statusGETPort status
/v1/x402/manage/ports/recreatePOSTRecreate deleted port (free)
/v1/x402/manage/ports/replacePOSTReplace offline port (free, max 3)
/v1/x402/manage/session/topup/calculateGETPreview top-up cost
/v1/x402/manage/session/topupPOSTPay to extend session (duration-only is FREE - used by x402_extend_session)
/v1/x402/pool/pricingGETPool Gateway tier catalog (no auth)
/v1/x402/poolGET/POSTBuy Pool Gateway access (402 flow, Payment-Signature)
/v1/x402/manage/pool/creditGETPool credit (X-Session-Token)
/v1/x402/manage/pool/topupPOSTPool top-up (X-Session-Token; traffic paid, duration free)
/v1/x402/manage/pool/regeneratePOSTRotate pool credential secret (X-Session-Token)
/v1/x402/manage/pool/connectionGETRe-emit pool credentials (X-Session-Token)
/v1/x402/manage/pool/usageGETPer-day MB usage series (X-Session-Token)
/v1/gateway/pool/stockGETPublic pool stock counts per country (no auth)
/v1/gateway/credentialsGETOwn pool proxyUsername + connect strings (JWT/API key)
/v1/gateway/pool/my-statsGETOwn pool usage + aggregated pool health (JWT/API key)
/v1/account/proxy-passwordPATCHSet/update the separate proxy auth password (JWT/API key)
/v1/reseller/pool-keys/:idPATCHUpdate a Pool Access Key (label/enabled/cap/expiry/qualityTier)
/v1/reseller/pool-keys/:idDELETEDelete a Pool Access Key
/v1/reseller/pool-keys/:id/regeneratePOSTRotate a Pool Access Key's secret
/v1/reseller/pool-keys/:id/revealPOSTReveal the full pak_ secret (audit-logged)
/v1/reseller/pool-keys/:id/usageGETDaily in/out MB series for one key
/v1/reseller/pool-keys/:id/auditGETForensic 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

  1. Agent requests /v1/x402/proxy?country=US&duration=3600&traffic=1
  2. Server returns 402 Payment Required with payment requirements
  3. Agent signs USDC transaction using viem
  4. Agent retries request with payment-signature header
  5. Server verifies payment on-chain
  6. Server returns proxy credentials

Payment Networks

NetworkUSDC ContractRecipient Wallet
Base0x833589fcd6edb6e08f4c7c32d4f71b54bda029130xF8cD900794245fc36CBE65be9afc23CDF5103042
SolanaEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv

Pricing

Duration is always FREE — you only pay for traffic.

TierPort PriceTraffic/GBMin Purchase
SharedFREE$4.000.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:manifest prints the live numbers and regenerates tools.json, manifest.json and 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 with npm run check:sync).

API Key Mode (70 Tools)

Account Tools:

  • get_account_summary - Balance, slots, traffic usage
  • get_account_usage - Detailed traffic breakdown

Port Management (7 tools):

  • list_ports - List all proxy ports
  • get_port - Get port details
  • create_port - Create new port
  • delete_port - Delete port
  • update_port_credentials - Change login/password
  • update_os_fingerprint - Set OS spoofing
  • reconfigure_port - Change port location

Status Tools (4 tools):

  • get_port_status - Online/offline status
  • get_port_ip - Current public IP
  • ping_port - Connectivity test
  • speed_test_port - Download/upload speed

Rotation Tools (5 tools):

  • rotate_port - Rotate to new IP
  • check_rotation_availability - Check cooldown
  • configure_auto_rotation - Set interval
  • get_rotation_history - View history
  • get_rotation_token_url - Public rotation URL

Billing Tools (3 tools):

  • get_pricing - Current pricing
  • calculate_price - Calculate price with volume discounts
  • purchase_shared_traffic - Buy shared GB ($4/GB, auto-upgrades slot tier)

Crypto Payment Tools (5 tools):

  • create_crypto_payment - Create CoinGate order
  • check_crypto_payment_status - Check status
  • get_pending_crypto_payments - List pending
  • cancel_crypto_payment - Cancel payment
  • get_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 string
  • get_all_proxy_formats - Get all formats
  • get_os_fingerprint_options - List OS options

Support Tools (5 tools):

  • create_support_ticket - Create ticket
  • list_my_tickets - List tickets
  • get_ticket - Get details
  • reply_to_ticket - Reply
  • close_ticket - Close ticket

x402 Session Management (8 tools):

  • get_x402_session - Session details
  • list_x402_ports - Ports in session
  • get_x402_port_status - Port status
  • get_sessions_by_wallet - Sessions by wallet
  • get_session_status - Quick status
  • replace_x402_port - Replace offline port (free, max 3)
  • calculate_x402_topup - Preview top-up cost
  • topup_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 user
  • ops_reconcile_payments - Read-only Stripe-vs-DB payment view
  • ops_list_tickets - List support tickets (admin view)
  • ops_reply_ticket - Post an admin reply to a ticket
  • ops_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 notes
  • ops_get_farmer - Farmer fleet funnel + AI note
  • ops_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 session
  • pool_get_my_credentials - Own proxyUsername + connect strings
  • pool_get_my_stats - Own usage + aggregated pool health
  • pool_set_proxy_password - Set/update proxy auth password
  • pool_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 USDC
  • x402_get_pricing - Calculate cost
  • x402_wallet_balance - Check wallet balance
  • x402_list_sessions - List active sessions
  • x402_check_session - Session details
  • x402_rotate_ip - Rotate IP
  • x402_extend_session - Extend session duration for FREE (duration-only top-up via POST /v1/x402/manage/session/topup; accepts session ID or x402s_ token)
  • x402_list_countries - Available countries
  • x402_list_cities - Cities in country
  • x402_list_carriers - Carriers in country
  • x402_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         # ESLint

Testing 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

  1. 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']
  }
};
  1. Add handler in src/tools/index.ts:
case 'my_new_tool':
  return await handleMyNewTool(args);
  1. 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
  • .env files are gitignored

Wallet Addresses (Public - Safe to Commit)

  • Base recipient: 0xF8cD900794245fc36CBE65be9afc23CDF5103042
  • Solana recipient: 6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv
  • Base USDC: 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
  • Solana USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Links


Last Updated: 2026-10-28

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.