aproxproxy-mcp

aproxproxy-mcp

MCP server for AproxPay — residential proxy built for autonomous AI agents, paid with x402 (USDC on Base).

Tools

Tool	Pays	Description
list_countries	free	ISO exit countries accepted by create_session region
proxy_get	~$0.003	Fetch a URL through residential IP (2MB cap). Billed per forward; returns origin status from X-Target-Status (use /v1/proxy/large for up to 5MB)
create_session	tiered	Buy a session pass + ephemeral CONNECT credentials. Response includes scheme (https in production), host, port, username, password — use https://user:pass@host:port (never plain http://). Production prefers gw.aproxpay.com:443; :8443 is a documented TLS fallback. Tiers: entry ($0.05 / 15MB / 30m), heavy ($0.50 / 200MB / 60m), gb ($2.50 / 1GB / ≤120m dedicated); optional region
extend_session	~$0.15	Top up +30 min / +50MB without changing exit IP or country (pooled sessions only; gb returns 409)
close_session	free	Invalidate credentials early (no automatic refund; upstream sub-user is not revoked)

Region (exit country)

• Call list_countries (free) → curated ISO 3166-1 alpha-2 codes (OFAC codes excluded).
• Call create_session with tier + region: "us" (or another code) — no surcharge; the CONNECT gateway pins DataImpulse cr.{code} for the whole session. Point Playwright/curl at https://user:pass@host:port from the JSON (scheme + host + port; production prefers 443; 8443 remains a TLS fallback with the same credentials). Never use plain http://.
• extend_session keeps the same country and sticky exit IP.

proxy_get still accepts region for forward-compat, but product A does not enforce it yet — use a session pass when you need a country-pinned IP.

Every request to the proxy API includes X-Client-Source: mcp for channel attribution.

Install / Claude Desktop

Add to your Claude Desktop MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "aproxproxy": {
      "command": "npx",
      "args": ["-y", "aproxproxy-mcp"],
      "env": {
        "APROXPROXY_PRIVATE_KEY": "0xYOUR_BUYER_PRIVATE_KEY",
        "APROXPROXY_BASE_URL": "https://proxy.aproxpay.com"
      }
    }
  }
}

Then ask Claude to call list_countries, or create_session with tier: "entry" and region: "us", or proxy_get with url: "https://example.com".

Environment

Variable	Required	Default	Notes
APROXPROXY_PRIVATE_KEY	yes	—	0x + 64 hex chars. Signs x402 payments. Never commit.
APROXPROXY_BASE_URL	no	https://proxy.aproxpay.com	Point at local proxy for testnet: http://localhost:8080
APROXPROXY_HTTP_PORT	no	3100	Only used with --http
APROXPROXY_HTTP_HOST	no	127.0.0.1	Only used with --http

Testnet smoke

• Run the AproxPay proxy locally on base-sepolia.
• Fund a buyer wallet from the Circle faucet.
• Set APROXPROXY_BASE_URL=http://localhost:8080 and the testnet private key.
• Call list_countries, then create_session with a tier and optional region, or proxy_get.

Transports

• stdio (default) — local agents / Claude Desktop: npx -y aproxproxy-mcp
• Streamable HTTP (self-hosted) — npx -y aproxproxy-mcp --http listens on http://127.0.0.1:3100/mcp

Remote HTTP is self-hosted only. The payment private key must stay on the operator's machine. AproxPay does not host a shared remote MCP endpoint (that would be custodial).

Security notes

• Prefer a dedicated low-balance buyer wallet for the MCP server.
• Do not put mainnet keys in chat logs or screenshots.
• close_session does not refund: x402 exact-scheme settlements are irreversible; manual refunds go through admin.

License

MIT