VPN pour agent d'IA — Guide de configuration

Ce que vous obtiendrez

X-VPN MCP transforme X-VPN en une couche réseau sur laquelle votre agent IA peut piloter tout seul. Après ce guide, votre agent IA sera capable de :

• Découvrez les régions et les protocoles disponibles.
• Connectez-vous à un pays, un État ou une ville que vousmentionnez dans une invite.
• Vérifier l'état de la connexion et les opérations actives.
• Déconnectez-vous lorsque la tâche est terminée.

Vous n'avez pas besoin d'utiliser l'application GUI de X-VPN. Tout fonctionne comme un petit démon local qui expose un point de terminaison MCP local uniquement à l'adresse http://127.0.0.1:3841/mcp.

Avant de commencer

Plateformes prises en charge

Agents d'IA pris en charge

L’assistant d’installation peut enregistrer X-VPN MCP dans l’un de ces clients automatiquement. Chacun d’entre eux est enregistré en écrivant dans le fichier de configuration MCP du client :

• Claude Code (~/.claude.json)
• Codex (~/.codex/config.toml)
• Gemini interface en ligne de commande (~/.gemini/settings.json)
• Curseur (~/.cursor/mcp.json)
• Continue.dev (~/.continue/config.yaml)
• Planche à voile (~/.codeium/mcp_config.json)
• Antigravité (~/.gemini/antigravity/mcp_config.json)

Si votre client n’est pas répertorié, vous pouvez quand même le pointer manuellement vers http://127.0.0.1:3841/mcp — voir ci-dessous la configuration MCP manuelle.

Vous aurez besoin

• Accès au terminal.
• sudo est recommandé; si ce n'est pas disponible, l'installateur bascule vers une installation utilisateur et affiche un indice PATH.
• Un compte X-VPN est facultatif. Vous pouvez utiliser le niveau gratuit sans vous connecter.

Étape 1 — Installer (une ligne)

Exécutez l'un des éléments suivants dans votre terminal :

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

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

L'installeur est non interactif et fera :

1. Détectez votre système d'exploitation et votre architecture.
2. Télécharger le binaire correspondant dans /tmp/.
3. Vérifier la signature / le hachage.
4. Installez dans /usr/local/bin/xvpn (ou ~/.local/bin/xvpn s'il ne peut pas écrire dans les chemins système).
5. Lancement automatique de xvpn install et passage à l’assistant à l’étape 2.

Si l'installateur se termine par une erreur, allez à Dépannage › Erreurs d'installation.

Étape 2 — Exécuter l’assistant d’installation

L'assistant a 7 étapes courtes. Chaque étape affiche un en-tête de progression clair [n/m].

2.1 Bienvenue

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

L'assistant n'accepte jamais automatiquement la politique de confidentialité. En appuyant sur Entrée, vous confirmez avoir lu les politiques liées.

2.2 Installer le démon

L’assistant enregistre xvpn en tant que démon système (par exemple via systemd sur Linux ou launchd sur macOS) et le met en service. Vous devriez voir :

[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.

Si l'une de ces étapes échoue, l'assistant affichera la ligne qui échoue. La cause la plus fréquente est des privilèges manquants — réexécutez avec sudo.

2.3 Choisir quels agents d'IA à enregistrer

[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]

• basculer uneligne.
• confirme.
• Si vous confirmez avec rien sélectionné, l'assistant vous demande une seconde fois afin de ne pas manquer l'inscription par accident.

2.4 Appliquer l'inscription

L’assistant écrit dans le fichier de configuration de chaque client sélectionné. Deux choses à connaître sur le comportement de fusion :

• La configuration existante est analysée et modifiée de manière incrémentielle. Vos autres serveurs MCP, les paramètres du modèle et les commandes personnalisées restent intacts — l'assistant n'ajoute que l'entrée X-VPN plutôt que de réécrire le fichier entier.
• Les sauvegardes ne se remplacent jamais entre elles. Avant d'écrire, l'assistant copie la configuration actuelle dans un fichier frère .bkp. Si .bkp existe déjà d'une exécution précédente, la nouvelle copie est enregistrée sous .bkp.1, .bkp.2, et ainsi de suite, afin que vous puissiez revenir à l'état au moment de toute installation antérieure.

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

Si aucun fichier de configuration n'existe à l'emplacement prévu, l'assistant en crée un nouveau avec seulement l'enregistrement X-VPN.

2.5 Vérifier l'installation

L'assistant exécute trois vérifications de bout en bout :

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

  ✓ All checks passed.

Ce que fait chaque vérification :

1. Démon répondant — teste le canal IPC local.
2. MCP handshake — curl http://127.0.0.1:3841/mcp performs the MCP initialize handshake.
3. Appel d'outil — émet un appel en lecture seule à xvpn_get_overview et analyse la réponse.

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

2.6 Se connecter (optionnel)

[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

Se connecter déverrouille l'expérience premium complète : 250+ emplacements et trafic illimité par connexion. Vous pouvez vous connecter via :

1. Adresse e-mail et mot de passe
2. Jeton d'identification — générez-en un sur https://xvpn.io/account/settings
3. Code d'accès à partir d'autres appareils — si vous êtes déjà connecté sur d'autres appareils

2.7 Terminé

─────────────────────────────────────
  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

L'assistant se ferme automatiquement.

Redémarrez votre client d'agent avant de continuer. Étant donné que l'enregistrement se fait en écrivant le fichier de configuration du client, un agent en cours d'exécution (Claude Code, Cursor, Codex, etc.) ne le rechargera pas tout seul. Quittez et rouvrez le client maintenant — sinon les invites dans l'Étape 3 indiqueront que les outils X-VPN ne sont pas disponibles.

Étape 3 — Essayez votre premier prompt qui prend en compte le VPN

Ouvrez l'Agent que vous avez enregistré et essayez l'un des suivants :

Utilisez X-VPN pour vous connecter aux États-Unis, puis récupérez la page d'accueil de reddit.com.

Connectez-vous via Tokyo et effectuez un rapide test de vitesse sur notre site web.

Récupérez les sujets tendance sur twitter.com du point de vue de l'Allemagne.

Dans les coulisses, l'Agent va appeler une séquence comme :

1. xvpn_get_overview — confirme l'état de la connexion et du compte
2. xvpn_list_locations(search="united-states") — trouve le nœud
3. xvpn_connect(location="united-states") — établit le tunnel
4. xvpn_get_status — attend que connected
5. (ta tâche)
6. xvpn_disconnect — met fin à la connexion

Si vous souhaitez voir les appels en ligne, la plupart des agents disposent d’un panneau « MCP debug » ou « outils » — activez-le.

Gérez votre installation

Commandes quotidiennes que vous pourriez vouloir :

État (connexion, auto-split, mcp-server) est persistant au cours des mises à niveau de version.

Configuration manuelle de MCP

Si votre client n’est pas dans la liste de l’assistant, dirigez-le vers le point de terminaison local :

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

Le point de terminaison est lié à 127.0.0.1 et rejette les origines qui ne proviennent pas de la boucle locale ; aucune règle de pare-feu supplémentaire n'est donc nécessaire.

Dépannage

Erreurs d'installation

Erreurs de vérification

L'agent client ne voit pas X-VPN MCP après l'installation.

L'assistant enregistre X-VPN en écrivant dans le fichier de configuration du client (par exemple ~/.claude.json, ~/.cursor/mcp.json). Un client en cours d'exécution ne recharge pas ce fichier tout seul. Quittez et rouvrez le client. Si le problème persiste, réexécutez xvpn install et surveillez les erreurs d'enregistrement dans la sortie de l'assistant avant de redémarrer à nouveau.

Plusieurs clients MCP

X-VPN MCP est sûr à utiliser à partir de plusieurs agents simultanément — les écritures IPC sont sérialisées afin que vous ne voyiez pas d'états de connexion croisés. Si vous observez un comportement étrange, redémarrez le daemon avec xvpn install.

Qu'est-ce qui vient ensuite ?

• Compétence — déposez notre compétence préconçue dans votre agent pour lui apprendre les schémas d'appel recommandés : https://github.com/x-vpn/xvpn-mcp-skill
• Communauté — questions et retours sur notre Reddit et sur les issues GitHub

Si vous rencontrez quelque chose qui n’est pas couvert ici, envoyez un courriel à support@xvpn.io avec la sortie de xvpn version et l’étape de l’assistant qui échoue — nous lisons chaque rapport.