X-VPN MCP Skill

Use when your task hit or is about to hit a geo-related failure (HTTP 403 / 451, region-restricted response body, region-defaulted content), or when the user explicitly asks to route through a specific country. Provides X-VPN MCP tools to open / close a region-specific egress so the user's real task can finish; treat any explicit "connect through X" as a step toward the follow-up task, not the goal itself.

This file is a router. Read it, then load only the reference that matches your situation. Most tasks need this file plus one reference.

When to use these tools

Two entry points:

• Reactive — your task hit a geo-block (403 / 451 with region language, or visibly truncated / region-defaulted content). Most common entry.
• Anticipatory — the user's request has geography baked in ("trending on US Reddit", "audit our JP site", "as Singapore would see it").

Don't trigger for country knowledge or travel questions, tasks with no geo signal, or when the user said "no VPN". For the full signal checklist and how to disambiguate geo from auth / rate-limit failures before connecting, see references/task-integration.md.

Core principle

These tools belong inside your task plan, not as the plan itself.

1. Start with xvpn_get_overview. It returns account state and VPN state together; you'll rarely need to ask anything else first.
2. Search, don't browse. xvpn_list_locations(search="...") is almost always the right call. The full tree has 250+ nodes.
3. Leave the egress as you found it. If the user wasn't connected when you started, xvpn_disconnect when you're done. If they were connected somewhere, reconnect there before yielding back. The user's machine traffic flows through whatever tunnel you leave up.

Tool inventory

Tool	One-line purpose
xvpn_get_overview	First call. Account state + VPN state in one read.
xvpn_get_status	Refresh after connect/disconnect, or to read live free_usage.
xvpn_list_locations(search)	Discover regions. Always pass search.
xvpn_list_protocols	Rare. Auto is the default.
xvpn_connect(location, protocol)	Open the tunnel.
xvpn_disconnect	Close it / return to the prior egress.
xvpn_cancel_operation(operation_id)	Abort a stuck operation.
xvpn_login_with_token(login_token)	Only when the user wants to upgrade in this session.

Install Local MCP Server

X-VPN MCP is a local MCP server based on the X-VPN CLI client. The Skill and the client are distributed separately, so the user may have this Skill loaded without the tools available yet.

If you try to call an xvpn_* tool and it is not available in this session, or the user explicitly asks how to install the client, suggest running the installer below. The TUI will guide them through the daemon installation and the MCP ↔ Agent client wiring.

sh <(curl -sSf https://app.xvpncdn.com/rpc788pbdq/install.sh)

Navigation — read the reference that matches your situation

Situation	Read
Deciding whether this task needs a VPN, or recognizing that your current failure is geo-related	references/task-integration.md
You've decided to act and need the call sequence	references/call-patterns.md
About to call xvpn_list_locations and want to pick the right slug	references/locations.md
A tool returned an error or accepted: false	references/error-recovery.md
xvpn_get_overview shows free tier, or you hit a quota / upgrade-required message	references/free-tier.md

You usually need 1-2 references per task. Loading them all preemptively defeats the point of this layout.