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": {
      "type": "stdio",
      "command": "uv",
      "args": ["tool", "run", "vpn-mcp"],
      "env": {
      }
    }
  }
}

3 Activate your account

From within Claude Code, call vpn_activate() to start the payment flow.

claude-code

> vpn_activate()

Payment address generated:

TON USDT: EQC...abc123

Amount: 1 USDT

Expires: 30 minutes

Send exactly 1 USDT (TON network) to the address above.

# After sending payment, check status:

> vpn_status()

Account active

Quota: 2 GB/month (resets in 30 days)

Expires: 2026-04-20

You can also activate via the web payment page and paste the API key into your config.

4 Connect and use

Connect to a VPN exit node. All WebFetch calls from Claude Code now route through the VPN automatically.

claude-code

# Connect to the default (nearest) node:

> vpn_connect()

Connected to na-1 (Dallas)

Proxy: 127.0.0.1:18080

# Or specify a region:

> vpn_connect("eu-1")

Connected to eu-1 (Frankfurt)

# WebFetch now routes through the VPN:

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

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

# Switch nodes mid-session:

> vpn_switch("ap-1")

Switched to ap-1 (Tokyo)

# Disconnect when done:

> vpn_disconnect()

Disconnected

MCP Tools Reference

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

Tool	Description
`vpn_setup()`	Download the xray binary for your OS. Called automatically on first connect.
`vpn_connect(node?)`	Start VPN proxy on `127.0.0.1:18080`. Optionally specify a node ID (e.g., `"eu-1"`).
`vpn_disconnect()`	Stop the VPN proxy and terminate the xray process.
`vpn_switch(node)`	Change exit node without disconnecting. Seamless IP rotation.
`vpn_status()`	Show account status: active/inactive, quota remaining, expiry date.
`vpn_nodes()`	List all available exit nodes with region, load, and latency info.
`vpn_activate()`	Start payment flow. Generates a TON USDT address and polls for payment.

API Endpoints

For custom integrations. Base URL: api.vpn-mcp.net

Endpoint	Auth	Description
`POST /api/mcp/register`	None	Register a new account. Returns API key and payment address.
`GET /api/mcp/status`	`Bearer`	Account status: active, quota remaining, expiry.
`GET /api/mcp/nodes`	`Bearer`	List available exit nodes. Response is encrypted.
`POST /api/mcp/connect`	`Bearer`	Get connection parameters for a specific node. Response is encrypted.

Example: Register

$ curl -X POST https://api.vpn-mcp.net/api/mcp/register

{
  "api_key": "vmcp_a1b2c3d4e5f6...",
  "payment_address": "EQC...abc123",
  "amount": "1",
  "currency": "USDT",
  "network": "TON",
  "expires_in": 1800
}

Example: Check Status

$ curl -H "Authorization: Bearer vmcp_a1b2c3d4e5f6..." \
     https://api.vpn-mcp.net/api/mcp/status

{
  "active": true,
  "quota_bytes": 2147483648,
  "quota_used": 524288000,
  "expires_at": "2026-04-20T00:00:00Z"
}

Get running in 5 minutes