X402 MCP Server

@privadovpn/x402-mcp

Pay-per-use VPN and SOCKS5 proxy access for AI agents, powered by x402 USDC payments. Local stdio MCP server that signs and broadcasts payments (Solana, EVM); every plan includes both an HTTP proxy and a SOCKS5 proxy.

Pricing

No subscription required — pay only for the access you use, starting at $0.05. Plans and prices are never hardcoded in this client: list_vpn_catalog always fetches the live, authoritative list from the backend's .well-known/x402-payment manifest. As of 2026-10-21, the approved pricing lineup is:

Every plan currently includes both an HTTP proxy and a SOCKS5 proxy (the backend's catalog lists this per plan as services: ["http_proxy", "socks5_proxy"]) — there is no separate SOCKS5-only plan to choose. Always call list_vpn_catalog before purchasing — it returns the current, authoritative set of plans, prices, and included services.

Security model

This server signs payments locally and never transmits your private key anywhere.

• SOLANA_PRIVATE_KEY and EVM_PRIVATE_KEY are read from local process environment variables. They are used only to sign transactions in-process and are never sent over the network or written to disk by this server.
• The only data that leaves the machine is a signed payment authorization (EVM EIP-3009) or a broadcast transaction signature (Solana), sent to X402_BASE_URL to fulfill a purchase.
• Use a dedicated, low-balance wallet for this server — never point it at a primary or high-balance wallet.
• wallet_status returns configured addresses and network selection only. It never returns private keys or any secret material.
• Credentials returned after a successful purchase (including proxy and SOCKS5 passwords) are written only to ~/.privado/ on your local machine and are never logged to stdout/stderr by this server.

Quick start

npx -y @privadovpn/x402-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "privadovpn-x402-mcp": {
      "command": "npx",
      "args": ["-y", "@privadovpn/x402-mcp"],
      "env": {
        "SOLANA_PRIVATE_KEY": "<your-base58-key>"
      }
    }
  }
}

Claude Code:

claude mcp add privadovpn-x402-mcp -e SOLANA_PRIVATE_KEY=<your-base58-key> -- npx -y @privadovpn/x402-mcp

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "privadovpn-x402-mcp": {
      "command": "npx",
      "args": ["-y", "@privadovpn/x402-mcp"],
      "env": {
        "SOLANA_PRIVATE_KEY": "<your-base58-key>"
      }
    }
  }
}

Configuration

Tools

Purchase flow and recovery

Each GET /pay request creates a new invoice on the server. Because of this, buy_vpn must be called exactly once per purchase attempt — calling it again after funds have already been sent creates a second invoice and results in a duplicate charge.

If buy_vpn reports that the on-chain payment succeeded but fulfillment failed (for example, due to a network error when exchanging the payment for credentials), do not call buy_vpn again. Instead call fulfill_payment with the plan, invoice_no, payment_signature, and settlement_tx values from the error. This exchanges the already-completed payment for credentials without creating a new invoice or sending additional funds.

buy_vpn and sign_and_pay both accept a dry_run flag that performs balance checks without broadcasting a transaction. Note that a dry run still creates a real invoice on the server; it does not need to be followed by a real purchase, but it should not be repeated for the same purchase attempt.

Credentials

A single purchase covers every service the plan includes — there is no separate checkout for SOCKS5. The vpn object returned by buy_vpn/fulfill_payment (and saved to ~/.privado/) contains:

This client does not parse or special-case these fields — whatever the backend returns is passed straight through to the agent and to the saved credentials file, so field names always match what list_vpn_catalog/buy_vpn actually return at the time of purchase.

Example of using a purchased SOCKS5 proxy with curl, once you have vpn.socks5_connection_string:

curl -x "$SOCKS5_CONNECTION_STRING" https://ifconfig.me

This server never configures system-wide or OS-level proxy settings — it only returns credentials. Routing any traffic through them is a separate, explicit step you take.

How it works

sequenceDiagram
    participant Agent
    participant MCP as Local MCP (this server)
    participant Backend as x402.privadovpn.com

    Agent->>MCP: buy_vpn(plan, country)
    MCP->>Backend: GET /pay?plan=...
    Backend-->>MCP: 402 Payment Required + quote (accepts[])
    MCP->>MCP: sign payment locally (private key never leaves process)
    MCP->>Backend: broadcast transaction on-chain
    Backend-->>MCP: transaction confirmed
    MCP->>Backend: GET /pay (PAYMENT-SIGNATURE, X-Settlement-Transaction)
    Backend-->>MCP: VPN credentials
    MCP-->>Agent: credentials + settlement_tx + credentials_path

Supported networks: Solana (SPL USDC transfer) and EVM (EIP-3009 transferWithAuthorization USDC).

Server-side discovery

• Catalog and payment discovery: https://x402.privadovpn.com/.well-known/x402-payment
• Agent-readable service description: https://x402.privadovpn.com/llms.txt
• Remote MCP (catalog/docs only, no wallet access): https://x402.privadovpn.com/mcp

Development

git clone git@github.com:privadovpn/x402-mcp.git
cd x402-mcp
npm install
npm run build
npm test

Run with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

License

MIT. See LICENSE.

mcp-name: io.github.privadovpn/x402-mcp