Setup Guide — VPN MCP

Prerequisites

✓ Claude Code installed and working
✓ uv (recommended) or pip available in your terminal

1 Install the MCP server

Install the vpn-mcp package. This provides the MCP server binary that Claude Code will invoke.

Recommended (uv)

$ uv tool install vpn-mcp

Alternative (pip)

$ pip install vpn-mcp

The package installs the vpn-mcp command and its dependencies. No system-level changes.

2 Add to .mcp.json

Add the VPN MCP server to your Claude Code configuration. Create or edit .mcp.json in your project root (or ~/.claude/mcp.json for global access).

{
  "mcpServers": {
    "vpn": {
      "command": "vpn-mcp"
    }
  }
}

3 Activate your account

From within Claude Code, call vpn_activate() to start the activation flow. The free tier activates instantly with no payment needed.

claude-code

> vpn_activate()

Account activated — Free tier

Rate limit: 1 req / 30s

Bandwidth: 256 KB/s

# To upgrade, call vpn_activate() and follow payment instructions.

# Basic: 1 USDT/mo | Pro: 5 USDT/mo (TON network)

4 Connect and use

Connect to a VPN exit node. After connecting, use vpn_fetch() — the recommended tool for making requests through the VPN tunnel.

claude-code

> vpn_connect()

Connected to North America

> vpn_fetch("https://httpbin.org/ip")

{"origin": "185.xx.xx.xx"}

# Switch regions mid-session:

> vpn_switch("Europe")

Switched to Europe

> vpn_disconnect()

Disconnected

MCP Tools Reference

All tools available through the VPN MCP server in Claude Code.

Tool	Description
`vpn_setup()`	Download VPN binary. Auto on first connect.
`vpn_activate()`	Activate account (free instant, paid via TON).
`vpn_connect(node?)`	Start VPN. Optionally specify region.
`vpn_disconnect()`	Stop VPN.
`vpn_switch(node)`	Change exit node.
`vpn_status()`	Account status, tier, quota.
`vpn_nodes()`	List available exit nodes.
`vpn_fetch(url, ...)`	HTTP request through VPN. Recommended.

API Reference

Base URL: api.vpn-mcp.net

Endpoint	Auth	Description
`POST /api/mcp/register`	None	Register (send machine_fingerprint). Returns API key + tier.
`GET /api/mcp/status`	`Bearer`	Status, tier limits, quota.
`GET /api/mcp/nodes`	`Bearer`	List exit nodes (encrypted).
`POST /api/mcp/connect`	`Bearer`	Get connection params (encrypted).

Example: Register

{
  "client_id": "uuid...",
  "api_key": "vpn_mcp_...",
  "tier": "free",
  "payment": {
    "network": "TON",
    "currency": "USDT",
    "address": "UQ...",
    "amount": "1",
    "pro_amount": "5"
  }
}

Example: Status

{
  "status": "active",
  "tier": "free",
  "tier_limits": {
    "bandwidth_kb_per_sec": 256,
    "requests_per_minute": 2,
    "burst": 1
  },
  "quota": {
    "used_bytes": 0,
    "limit_bytes": 1073741824,
    "percent": 0
  }
}

Get running in 5 minutes