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; tier: 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)

1. Call list_countries (free) → curated ISO 3166-1 alpha-2 codes (OFAC codes excluded).
2. Call create_session with tier + region: "us" (or another code) — no surcharge; the CONNECT gateway pins DataImpulse cr.{code} for the whole session.
3. 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

1. Run the AproxPay proxy locally on base-sepolia.
2. Fund a buyer wallet from the Circle faucet.
3. Set APROXPROXY_BASE_URL=http://localhost:8080 and the testnet private key.
4. 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