VPN für KI-Agent — Installationsanleitung

Was Sie bekommen

X-VPN MCP turns X-VPN into a network layer your AI Agent can drive on its own. After this guide, your Agent will be able to:

• Verfügbare Regionen und Protokolle entdecken
• Verbinden Sie sich mit einem Land, einem Bundesland oder einer Stadt, die Sie in einer Eingabeaufforderung erwähnen.
• Verbindungsstatus und laufende Operationen überprüfen
• Trennen Sie die Verbindung, sobald die Aufgabe abgeschlossen ist.

Sie müssen die X-VPN GUI-App nicht verwenden. Alles läuft als ein kleiner lokaler Daemon, der einen nur lokal erreichbaren MCP-Endpunkt unter http://127.0.0.1:3841/mcp bereitstellt.

Bevor Sie beginnen

Unterstützte Plattformen

Unterstützte KI-Agenten

Der Setup-Assistent kann X-VPN MCP automatisch in jeden dieser Clients registrieren. Jeder von ihnen wird registriert, indem in die MCP-Konfigurationsdatei des Clients geschrieben wird:

• Claude Code (~/.claude.json)
• Codex (~/.codex/config.toml)
• Gemini CLI (~/.gemini/settings.json)
• Cursor (~/.cursor/mcp.json)
• Continue.dev (~/.continue/config.yaml)
• Windsurfen (~/.codeium/mcp_config.json)
• Antigravitation (~/.gemini/antigravity/mcp_config.json)

Wenn Ihr Client nicht aufgeführt ist, können Sie ihn dennoch manuell auf http://127.0.0.1:3841/mcp verweisen — siehe unten die manuelle MCP-Konfiguration.

Du wirst brauchen

• Terminalzugang.
• sudo wird empfohlen; falls es nicht verfügbar ist, fällt der Installer auf die Benutzerinstallation zurück und gibt einen PATH-Hinweis aus.
• Ein X-VPN-Konto ist optional. Sie können den kostenlosen Tarif nutzen, ohne sich anzumelden.

Schritt 1 — Installieren (eine Zeile)

Führen Sie einen der folgenden Befehle in Ihrem Terminal aus:

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

sh <(wget -qO - https://app.xvpncdn.com/rpc788pbdq/install.sh)

Der Installer ist nicht interaktiv und wird:

1. Ermitteln Sie Ihr Betriebssystem und Ihre Architektur.
2. Lade die passende Binärdatei in /tmp/ herunter.
3. Signatur / Hash überprüfen.
4. Installieren Sie es unter /usr/local/bin/xvpn (oder ~/.local/bin/xvpn, falls es nicht in Systempfade schreiben kann).
5. Starte automatisch xvpn install und leite dich im Schritt 2 zum Assistenten weiter.

If the installer exits with an error, jump to Troubleshooting › Install errors.

Schritt 2 — Den Installationsassistenten ausführen

The wizard has 7 short stages. Each stage prints a clear [n/m] progress header.

2.1 Willkommen

Welcome to use X-VPN MCP Wizard
       Version 1.0.0_1014

  PrivacyPolicy: https://xvpn.io/policy
  Terms:        https://xvpn.io/terms-service

This wizard will:

1. Install the X-VPN daemon
2. Register X-VPN with your AI Agents
3. (Optional) Sign in
4. Verify everything works

Estimated time: ~2 minutes
Press ENTER to continue, or Ctrl-C to exit

Der Assistent akzeptiert die Datenschutzerklärung niemals automatisch. Durch das Drücken von ENTER bestätigen Sie, dass Sie die verlinkten Richtlinien gelesen haben.

2.2 Daemon installieren

Der Assistent registriert xvpn als Systemdaemon (z. B. über systemd unter Linux oder launchd unter macOS) und startet ihn. Sie sollten Folgendes sehen:

[1/6] Install X-VPN Daemon
─────────────────────────────────────
  [1/3] Writing service file        OK
  [2/3] Loading service             OK
  [3/3] Verifying daemon            OK

  ✓ daemon is up.

Wenn einer dieser Schritte fehlschlägt, wird der Assistent die fehlerhafte Zeile anzeigen. Die häufigste Ursache sind fehlende Berechtigungen — führen Sie erneut mit sudo aus.

2.3 Wählen Sie aus, welche KI-Agenten registriert werden sollen.

[2/5] Register X-VPN MCP
─────────────────────────────────────
  [x] Claude Code           write: ~/.claude.json
  [ ] Codex                 write: ~/.codex/config.toml
  [ ] Gemini CLI            write: ~/.gemini/settings.json
  [x] Cursor                write: ~/.cursor/mcp.json
  [ ] Continue.dev          write: ~/.continue/config.yaml
  [ ] Windsurf              write: ~/.codeium/mcp_config.json
  [ ] Antigravity           write: ~/.gemini/antigravity/mcp_config.json

[SPACE select · ENTER continue]

• Schaltet eine Zeile um.
• Bestätigt.
• Wenn Sie mit nichts ausgewählt bestätigen, fordert der Assistent ein zweites Mal auf, damit Sie die Registrierung nicht versehentlich überspringen.

2.4 Registrierung anwenden

Der Zauberer schreibt in die Konfigurationsdatei jedes ausgewählten Clients. Zwei Dinge, die man über das Merge-Verhalten wissen sollte:

• Die vorhandene Konfiguration wird inkrementell geparst und angepasst. Ihre anderen MCP-Server, Modelleinstellungen und benutzerdefinierte Befehle bleiben unverändert — der Assistent fügt lediglich den X-VPN-Eintrag hinzu, anstatt die gesamte Datei neu zu schreiben.
• Backups überschreiben sich niemals gegenseitig. Vor dem Schreiben kopiert der Assistent die aktuelle Konfiguration in eine .bkp-Datei im selben Verzeichnis. Wenn .bkp bereits aus einer früheren Ausführung existiert, wird die neue Kopie als .bkp.1, .bkp.2 und so weiter gespeichert, damit Sie auf den Zustand zum Zeitpunkt jeder früheren Installation zurückrollen können.

[3/5] Connect X-VPN MCP
─────────────────────────────────────
Registering with Cursor...
  Copy current config file for backup...
  Write to ~/.cursor/mcp.json ...
  ✓ Added.

Wenn im erwarteten Pfad keine Konfigurationsdatei existiert, erstellt der Assistent eine neue Datei, die nur die X-VPN-Registrierung enthält.

2.5 Die Installation überprüfen

Der Assistent führt drei End-to-End-Tests durch:

[4/5] Verifying Installation
─────────────────────────────────────
  [1/3] Daemon responding        OK
  [2/3] MCP handshake            OK
  [3/3] Tool call                OK

  ✓ All checks passed.

Was jeder Check macht:

1. Daemon antwortet — pingt den lokalen IPC-Kanal an.
2. MCP handshake — curl http://127.0.0.1:3841/mcp performs the MCP initialize handshake.
3. Tool-Aufruf — führt einen Nur-Leseaufruf der Funktion xvpn_get_overview aus und analysiert die Antwort.

If the Tool call check fails, the wizard offers [r]etry / [q]uit.

2.6 Anmelden (optional)

[5/5] Sign In (Optional)
─────────────────────────────────────
  Without signing in, you'll use the free tier:
    • 50MB per connection
    • Connect free locations only

  > 1. Continue with free
    2. Sign in/Sign up

Durch das Anmelden wird das volle Premium-Erlebnis freigeschaltet: 250+ Standorte und unbegrenzter Datenverkehr pro Verbindung. Sie können sich über folgende Optionen anmelden:

1. E-Mail-Adresse und Passwort
2. Authentifizierungs-Token — generieren Sie einen Token unter https://xvpn.io/account/settings
3. Passcode von anderen Geräten — falls Sie bereits woanders angemeldet sind

2.7 Erledigt

─────────────────────────────────────
  X-VPN MCP is ready. Restart your agent clients to activate
  new settings.

  Try in your Agent:
    "Use X-VPN to connect to the United States."

  Manage mcp server:    xvpn mcp-server [on|off]
  Toggle auto-split:    xvpn auto-split [on|off|list]
  Reconfigure:          xvpn install      (any time)
  Uninstall:            xvpn uninstall

  Help:    https://xvpn.io/help-center
  Report:  mailto:support@xvpn.io

Der Assistent schließt sich automatisch.

Restart your agent client before continuing. Because registration happens by writing the client’s config file, a running agent (Claude Code, Cursor, Codex, etc.) won’t reload that file on its own. Quit and reopen the client now — otherwise the prompts in Step 3 will report the X-VPN tools as unavailable.

Schritt 3 — Probiere deinen ersten VPN-bewussten Prompt.

Öffnen Sie den von Ihnen registrierten Agenten und probieren Sie einen von ihnen aus:

Verwenden Sie X-VPN, um eine Verbindung zu den Vereinigten Staaten herzustellen, und rufen Sie anschließend die Startseite von reddit.com auf.

Stellen Sie eine Verbindung über Tokio her und führen Sie einen kurzen Geschwindigkeitstest auf unserer Website durch.

Rufe die Trendthemen von twitter.com aus der Perspektive Deutschlands ab.

Hinter den Kulissen wird der Agent eine Sequenz wie folgt aufrufen:

1. xvpn_get_overview — bestätigt Verbindungsstatus und Konto
2. xvpn_list_locations(search="united-states") — findet den Knoten
3. xvpn_connect(location="united-states") — stellt den Tunnel her
4. xvpn_get_status — wartet auf connected
5. (deine Aufgabe)
6. xvpn_disconnect — beendet die Verbindung

If you’d like to see the calls inline, most Agents have an “MCP debug” or “tools” panel — toggle it on.

Verwalten Sie Ihre Installation.

Alltägliche Befehle, die Sie möglicherweise wünschen:

Zustand (Anmeldung, auto-split, mcp-server) ist dauerhaft über Versions-Upgrades hinweg.

Manuelle MCP-Konfiguration

Wenn Ihr Client nicht in der Liste des Wizards ist, richten Sie ihn auf den lokalen Endpunkt aus:

URL:       http://127.0.0.1:3841/mcp
Transport: HTTP (Streamable HTTP)
Auth:      none (loopback only)

Der Endpunkt ist an 127.0.0.1 gebunden und verweigert Nicht-Loopback-Ursprünge, daher sind keine zusätzlichen Firewallregeln erforderlich.

Fehlerbehebung

Installationsfehler

Verifizierungsfehler

Der Agent-Client sieht X-VPN MCP nach der Installation nicht.

Der Assistent registriert X-VPN, indem er in die Konfigurationsdatei des Clients schreibt (z. B. ~/.claude.json, ~/.cursor/mcp.json). Ein laufender Client lädt diese Datei nicht von selbst neu. Beenden Sie den Client und öffnen Sie ihn erneut. Falls das Problem weiterhin besteht, führen Sie xvpn install erneut aus und achten Sie auf Registrierungsfehler in der Ausgabe des Assistenten, bevor Sie erneut neu starten.

Mehrere MCP-Clients

X-VPN MCP ist sicher, gleichzeitig von mehreren Agenten verwendet zu werden — IPC-Schreibvorgänge werden serialisiert, damit Sie keine inkonsistenten Verbindungszustände sehen. Wenn Sie merkwürdiges Verhalten feststellen, starten Sie den Daemon neu mit xvpn install.

Was kommt als Nächstes?

• Skill — drop our prebuilt Skill into your Agent to teach it the recommended call patterns: https://github.com/x-vpn/xvpn-mcp-skill
• Community — Fragen und Feedback auf Reddit und auf GitHub Issues

If you hit anything not covered here, email support@xvpn.io with the output of xvpn version and the failing wizard step — we read every report.