PrivadoVPN x402 Payer

@privadovpn/x402-mcp

为 AI Agent 提供按使用量付费的 VPN 和 SOCKS5 代理访问，由 x402 USDC 付款提供支持。这是一个本地 stdio MCP 服务，可签署并广播付款（Solana、EVM）；每种套餐均包含 HTTP 代理和 SOCKS5 代理。

定价

无需订阅——只需为实际使用的访问权限付费，价格低至 $0.05。本客户端不会硬编码套餐和价格：list_vpn_catalog 始终从后端的 .well-known/x402-payment 清单获取最新权威列表。截至 2026-10-21，已批准的定价方案如下：

套餐 ID	显示名称	时长	价格
PREMIUMM15	Premium M15	15 分钟	$0.05
PREMIUMX1	Premium X1	1 小时	$0.15
PREMIUMX3	Premium X3	3 小时	$0.39
PREMIUMD1	Premium D1	24 小时	$0.99
PREMIUMD7	Premium D7	7 天	$2.99
PREMIUMD30	Premium D30	30 天	$5.99

目前，每种套餐均包含 HTTP 代理和 SOCKS5 代理（后端目录会针对每种套餐列出 services: ["http_proxy", "socks5_proxy"]）——没有单独的 SOCKS5 套餐可供选择。购买前务必调用 list_vpn_catalog——它会返回当前权威的套餐、价格和所含服务列表。

安全模型

此服务在本地签署付款，绝不会将你的私钥传输到任何地方。

• SOLANA_PRIVATE_KEY 和 EVM_PRIVATE_KEY 从本地进程环境变量中读取。它们仅用于在进程内签署交易，绝不会通过网络发送，也不会由此服务写入磁盘。
• 离开设备的唯一数据是已签名的付款授权（EVM EIP-3009）或已广播的交易签名（Solana），这些数据会发送到 X402_BASE_URL 以完成购买。
• 请为此服务使用余额较低的专用钱包——切勿将其指向主要钱包或高余额钱包。
• wallet_status 仅返回已配置的地址和网络选择，不会返回私钥或任何机密信息。
• 成功购买后返回的凭据（包括代理和 SOCKS5 密码）仅写入本地设备上的 ~/.privado/，此服务绝不会将它们记录到 stdout/stderr。

快速开始

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

配置

变量	必需	默认值	说明
SOLANA_PRIVATE_KEY	SOLANA_PRIVATE_KEY / EVM_PRIVATE_KEY 至少设置一个	—	Base58 编码的 Solana 密钥（32 或 64 字节），用于签署交易并支付 SPL USDC。
EVM_PRIVATE_KEY	SOLANA_PRIVATE_KEY / EVM_PRIVATE_KEY 至少设置一个	—	十六进制编码的 EVM 私钥，用于签署 EIP-3009 USDC 授权。
PREFERRED_NETWORK	否	如果设置了 SOLANA_PRIVATE_KEY，则为 solana；否则为 evm	报价同时提供两种网络时优先使用的网络。接受 solana 或 evm（eip155 是 evm 的有效别名）。
X402_BASE_URL	否	https://x402.privadovpn.com	x402 付款后端的基础 URL，用于目录、报价和付款完成请求。
SOLANA_RPC_URL	否	https://api.mainnet-beta.solana.com	用于查询余额和广播交易的 Solana RPC 端点。
EVM_RPC_URL	EVM 付款必需	—	用于查询余额和广播交易的 EVM RPC 端点。

工具

工具	用途
wallet_status	显示已配置的钱包地址和网络选择。绝不会返回私钥。
list_vpn_catalog	列出可购买的 VPN 套餐（包括每个套餐包含的服务——HTTP 代理、SOCKS5）以及支持的服务器国家/地区代码。
buy_vpn	首选购买流程：一次调用即可报价、签名并在链上付款、完成交付并保存凭据。
fulfill_payment	仅用于恢复：将已广播的付款兑换为 VPN 凭据。
sign_and_pay	仅用于调试：签名并广播付款，但不完成交付。优先使用 buy_vpn。

购买流程与恢复

每个 GET /pay 请求都会在服务端创建一张新发票。因此，每次购买尝试只能调用一次 buy_vpn——资金已发送后再次调用，会创建第二张发票并导致重复扣款。

如果 buy_vpn 报告链上付款成功，但交付失败（例如，将付款兑换为凭据时发生网络错误），请勿再次调用 buy_vpn。应改为使用错误中的 plan、invoice_no、payment_signature 和 settlement_tx 值调用 fulfill_payment。此操作会将已完成的付款兑换为凭据，不会创建新发票或发送额外资金。

buy_vpn 和 sign_and_pay 都接受 dry_run 标志，可在不广播交易的情况下检查余额。请注意，试运行仍会在服务端创建真实发票；之后无需进行真实购买，但同一次购买尝试不应重复试运行。

凭据

一次购买涵盖套餐包含的所有服务——SOCKS5 无需单独结账。buy_vpn/fulfill_payment 返回（并保存到 ~/.privado/）的 vpn 对象包含：

字段	存在条件	说明
vpn.port, vpn.connection_string	始终存在	HTTP 代理。connection_string 的格式为 https://user:pass@host:port。
vpn.socks5_port, vpn.socks5_connection_string	套餐的 services 包含 socks5_proxy	SOCKS5 代理，用户名/密码与 HTTP 代理相同。socks5_connection_string 的格式为 socks5://user:pass@host:port。

此客户端不会解析这些字段，也不会对其进行特殊处理——后端返回的内容会原样传递给 Agent 并写入已保存的凭据文件，因此字段名称始终与购买时 list_vpn_catalog/buy_vpn 实际返回的名称一致。

购买 SOCKS5 代理后，可通过 vpn.socks5_connection_string 使用 curl，示例如下：

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

此服务绝不会配置系统范围或操作系统级别的代理设置——它只会返回凭据。要通过这些凭据路由任何流量，需要你另行明确操作。

工作原理

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

支持的网络：Solana（SPL USDC 转账）和 EVM（EIP-3009 transferWithAuthorization USDC）。

服务端发现

• 目录和付款发现：https://x402.privadovpn.com/.well-known/x402-payment
• Agent 可读取的服务说明：https://x402.privadovpn.com/llms.txt
• 远程 MCP（仅限目录/文档，不访问钱包）：https://x402.privadovpn.com/mcp

开发

git clone [email protected]:privadovpn/x402-mcp.git
cd x402-mcp
npm install
npm run build
npm test

使用 MCP Inspector 运行：

npx @modelcontextprotocol/inspector node dist/index.js

许可证

MIT。参见 LICENSE。

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