Setup Guide

Get running in 5 minutes

Everything you need to give Claude Code internet access through VPN exit nodes.

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.

$ uv tool install vpn-mcp
$ 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": {
        "HTTPS_PROXY": "http://127.0.0.1:18080"
      }
    }
  }
}

The HTTPS_PROXY environment variable tells Claude Code's WebFetch to route all HTTP/HTTPS traffic through the local VPN proxy once connected.

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 remaining
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"
}