ProxyBase

A Model Context Protocol (MCP) server that lets AI agents purchase and manage SOCKS5 proxies programmatically through ProxyBase.

Installation

Download Pre-built Binary

Grab the latest binary for your platform from Releases:

Platform	Binary
Linux x86_64	proxybase-mcp-linux-x86_64
Linux aarch64	proxybase-mcp-linux-aarch64
macOS x86_64	proxybase-mcp-macos-x86_64
macOS Apple Silicon	proxybase-mcp-macos-aarch64
Windows x86_64	proxybase-mcp-windows-x86_64.exe

Build from Source

git clone https://github.com/proxybasehq/proxybase-mcp.git
cd proxybase-mcp
cargo build --release
# Binary at: target/release/proxybase-mcp

Configuration

Environment Variable	Default	Description
PROXYBASE_API_URL	https://api.proxybase.xyz	ProxyBase backend URL
RUST_LOG	info	Log level (logs go to stderr)

MCP Client Setup

Add to your MCP client config:

Claude Desktop / Cursor

{
  "mcpServers": {
    "proxybase": {
      "command": "/path/to/proxybase-mcp"
    }
  }
}

With Custom Backend URL

{
  "mcpServers": {
    "proxybase": {
      "command": "/path/to/proxybase-mcp",
      "env": {
        "PROXYBASE_API_URL": "https://api.proxybase.xyz"
      }
    }
  }
}

Available Tools

register_agent

Register a new AI agent and receive an API key. Always the first step.

Parameters: None

Returns:

{
  "agent_id": "6xAMqAGN",
  "api_key": "pk_c8c91c8a0e5b3e2c..."
}

---

list_packages

List available proxy bandwidth packages with pricing.

Param	Required	Description
api_key	✅	Your API key (starts with pk_)

---

list_currencies

List available payment currencies (cryptocurrencies) for the pay_currency field.

Param	Required	Description
api_key	✅	Your API key (starts with pk_)

Returns:

{
  "currencies": ["btc", "eth", "sol", "usdcsol", "ltc", ...]
}

---

create_order

Purchase a proxy package. Generates a cryptocurrency payment invoice.

Param	Required	Description
api_key	✅	Your API key
package_id	✅	Package to purchase (e.g., us_residential_1gb)
pay_currency		Crypto to pay with (default: usdcsol). Use list_currencies for valid values
callback_url		Webhook URL for status notifications

Returns:

{
  "order_id": "kQx7p3Wn",
  "payment_id": "5832461907",
  "pay_address": "TXyz...",
  "pay_currency": "usdcsol",
  "pay_amount": 10.15,
  "price_usd": 10.00,
  "status": "payment_pending"
}

---

check_order_status

Poll order status. Returns proxy credentials once active.

Param	Required	Description
api_key	✅	Your API key
order_id	✅	Order ID from create_order

Returns (when proxy is active):

{
  "order_id": "kQx7p3Wn",
  "status": "proxy_active",
  "bandwidth_bytes": 1073741824,
  "used_bytes": 52428800,
  "remaining_bytes": 1021313024,
  "usage_percentage": 4.88,
  "proxy": {
    "host": "api.proxybase.xyz",
    "port": 1080,
    "username": "pb_a1b2c3d4e5f6g7h8",
    "password": "9f8e7d6c5b4a3210"
  }
}

Status Flow: payment_pending → confirming → paid → proxy_active → bandwidth_exhausted

---

topup_order

Add bandwidth to an existing proxy. Same credentials, more bandwidth.

Param	Required	Description
api_key	✅	Your API key
order_id	✅	Order to top up
package_id	✅	Bandwidth package to add
pay_currency		Crypto to pay with. Use list_currencies for valid values

---

rotate_proxy

Rotate the proxy to get a fresh IP address. Calls the upstream partner's reset endpoint. Only works on active proxies.

Param	Required	Description
api_key	✅	Your API key
order_id	✅	The order whose proxy should be rotated

Returns:

{
  "order_id": "kQx7p3Wn",
  "message": "Proxy rotated successfully. You will receive a fresh IP on your next connection.",
  "rotated": true
}

---

Typical Agent Workflow

1. register_agent      → Save your api_key
2. list_packages       → Choose a package
3. list_currencies     → See valid pay_currency values
4. create_order        → Get payment address
5. [Pay via blockchain]
6. check_order_status  → Poll until status = "proxy_active"
7. Use proxy: socks5://username:[email protected]:1080
8. check_order_status  → Monitor bandwidth usage
9. rotate_proxy        → Get a fresh IP when needed
10. topup_order        → When bandwidth runs low

Protocol Details

• Transport: stdio (JSON-RPC 2.0, one message per line)
• MCP Version: 2024-11-05
• Capabilities: tools only

Testing

cargo test

# Manual: send JSON-RPC over stdio
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | cargo run 2>/dev/null

License

MIT