ProxyBase MCP Server

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

Related MCP server: Navvi

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`

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:password@api.proxybase.xyz: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

ProxyBase MCP

ProxyBase MCP Server

Installation

Download Pre-built Binary

Build from Source

Configuration

MCP Client Setup

Claude Desktop / Cursor

With Custom Backend URL

Available Tools

`register_agent`

`list_packages`

`list_currencies`

`create_order`

`check_order_status`

`topup_order`

`rotate_proxy`

Typical Agent Workflow

Protocol Details

Testing

License

Maintenance

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API