VPN para Agente de IA — Guia de Configuração

O que você vai receber

X-VPN MCP transforma o X-VPN em uma camada de rede que o seu Agente de IA pode operar por conta própria. Após este guia, o seu Agente será capaz de:

• Discover available regions and protocols
• Conecte-se a um país, estado ou cidade que você mencionar em um prompt.
• Check connection status and active operations
• Desconecte-se quando a tarefa estiver concluída.

Você não precisa usar o aplicativo GUI do X-VPN. Tudo funciona como um pequeno daemon local que expõe um endpoint MCP apenas local em http://127.0.0.1:3841/mcp.

Antes de começar

Plataformas suportadas

Agentes de IA suportados

O assistente de configuração pode registrar o X-VPN MCP em qualquer um desses clientes automaticamente. Cada um deles é registrado escrevendo no arquivo de configuração MCP do cliente:

• Código Claude (~/.claude.json)
• Codex (~/.codex/config.toml)
• CLI do Gemini (~/.gemini/settings.json)
• Cursor (~/.cursor/mcp.json)
• Continue.dev (~/.continue/config.yaml)
• Windsurf (~/.codeium/mcp_config.json)
• Antigravidade (~/.gemini/antigravity/mcp_config.json)

Se o seu cliente não estiver listado, você ainda pode apontá-lo manualmente para http://127.0.0.1:3841/mcp — veja a configuração manual do MCP abaixo.

Você precisará

• Acesso ao terminal.
• sudo é recomendado; se não estiver disponível, o instalador recorre à instalação pelo usuário e imprime uma dica do PATH.
• Uma conta X-VPN é opcional. Você pode usar o nível gratuito sem fazer login.

Passo 1 — Instalar (em uma linha)

Execute um dos seguintes comandos no seu terminal:

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

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

O instalador não é interativo e irá:

1. Detecte o seu SO e a arquitetura.
2. Baixe o binário correspondente para /tmp/.
3. Verifique a assinatura / hash.
4. Instale em /usr/local/bin/xvpn (ou ~/.local/bin/xvpn se não puder gravar em caminhos do sistema).
5. Auto-launch xvpn install and hand you off to the wizard in Step 2.

Se o instalador sair com um erro, vá para Resolução de problemas › Erros de instalação.

Etapa 2 — Execute o assistente de configuração.

O assistente tem 7 etapas curtas. Cada etapa imprime um cabeçalho de progresso claro [n/m].

2.1 Bem-vindo

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

O assistente nunca aceita automaticamente a política de privacidade. Ao pressionar ENTER, você confirma que leu as políticas vinculadas.

2.2 Instale o daemon

O assistente registra xvpn como um daemon do sistema (por exemplo, via systemd no Linux ou launchd no macOS) e o coloca em funcionamento. Você deve ver:

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

Se alguma dessas etapas falhar, o assistente exibirá a linha que falhou. A causa mais comum é a falta de privilégios — execute novamente com sudo.

2.3 Escolha quais agentes de IA cadastrar

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

• Alterna uma linha.
• confirma.
• Se você confirmar com nenhuma opção selecionada, o assistente solicitará novamente para que você não pule o cadastro por engano.

2.4 Aplicar o cadastro

O assistente grava no arquivo de configuração de cada cliente selecionado. Duas coisas para saber sobre o comportamento da mesclagem:

• A configuração existente é analisada e alterada incrementalmente. Seus outros servidores MCP, configurações do modelo e comandos personalizados permanecem intactos — o assistente apenas adiciona a entrada X-VPN, em vez de reescrever todo o arquivo.
• Cópias de segurança nunca se sobrescrevem entre si. Antes de escrever, o assistente copia a configuração atual para um .bkp arquivo-irmão. Se .bkp já existir de uma execução anterior, a nova cópia é salva como .bkp.1, .bkp.2, e assim por diante, para que você possa reverter para o estado no momento de qualquer instalação anterior.

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

Se não existir um ficheiro de configuração no caminho esperado, o assistente cria um novo apenas com o cadastro do X-VPN.

2.5 Verificar a instalação

O assistente executa três verificações de ponta a ponta:

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

  ✓ All checks passed.

O que cada verificação faz:

1. Daemon respondendo — faz o ping no canal IPC local.
2. Aperto de mão MCP — curl http://127.0.0.1:3841/mcp realiza o aperto de mão de inicialização do MCP.
3. Chamada de ferramenta — emite uma chamada de somente leitura para xvpn_get_overview e analisa a resposta.

Se a verificação de chamada de ferramenta falhar, o assistente oferece [r]etry / [q]uit.

2.6 Entrar (opcional)

[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

Fazer login desbloqueia a experiência premium completa: 250+ locais e tráfego ilimitado por conexão. Você pode fazer login via:

1. Endereço de e-mail e senha
2. Token de credencial — gere um em https://xvpn.io/account/settings
3. Código de acesso de outros dispositivos — se você já estiver conectado em outros dispositivos

2.7 Concluído

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

O assistente sai automaticamente.

Reinicie o cliente do seu agente antes de continuar. Como o registro ocorre ao escrever o arquivo de configuração do cliente, um agente em funcionamento (Claude Code, Cursor, Codex, etc.) não recarregará esse arquivo por conta própria. Feche e reabra o cliente agora — caso contrário, as solicitações da Etapa 3 indicarão que as ferramentas X-VPN estão indisponíveis.

Etapa 3 — Experimente o seu primeiro prompt que leva em conta a VPN

Abra o agente que você registrou e tente uma das opções:

Use o X-VPN para se conectar aos Estados Unidos, depois acesse a página inicial do reddit.com.

Conecte-se via Tóquio e realize um teste rápido de velocidade no nosso site.

Busque os tópicos em alta no twitter.com da perspectiva da Alemanha.

Nos bastidores, o agente chamará uma sequência como:

1. xvpn_get_overview — confirma o estado da conexão e da conta
2. xvpn_list_locations(search="united-states") — encontra o nó
3. xvpn_connect(location="united-states") — estabelece o túnel
4. xvpn_get_status — aguarda por connected
5. (sua tarefa)
6. xvpn_disconnect — derruba a conexão.

Se quiser ver as chamadas em linha, a maioria dos agentes tem um painel “MCP debug” ou “tools” — ative-o.

Gerencie a sua instalação

Comandos do dia a dia que você pode querer:

Estado (login, auto-split, mcp-server) é persistente ao longo das atualizações de versão.

Manual de Configuração do MCP

Se o seu cliente não estiver na lista do assistente, aponte-o para o endpoint local:

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

O endpoint está vinculado a 127.0.0.1 e rejeita origens que não sejam loopback, portanto não são necessárias regras adicionais de firewall.

Resolução de problemas

Erros de instalação

Erros de verificação

O cliente do agente não vê o X-VPN MCP após a instalação.

O assistente registra o X-VPN escrevendo no arquivo de configuração do cliente (por exemplo, ~/.claude.json, ~/.cursor/mcp.json). Um cliente em execução não recarrega esse arquivo por conta própria. Feche o cliente e abra-o novamente. Se o problema persistir, execute novamente xvpn install e observe quaisquer erros de registro na saída do assistente antes de reiniciar novamente.

Múltiplos clientes MCP

X-VPN MCP is safe to use from multiple Agents simultaneously — IPC writes are serialized so you won’t see crossed connection states. If you do see odd behavior, restart the daemon with xvpn install.

E agora?

• Habilidade — adicione nossa Habilidade pré-construída ao seu Agente para ensiná-lo aos padrões de chamadas recomendados: https://github.com/x-vpn/xvpn-mcp-skill
• Comunidade — perguntas e feedback em nosso Reddit e nas Issues do GitHub

Se encontrar qualquer coisa que não esteja coberta aqui, envie um e-mail para support@xvpn.io com a saída de xvpn version e a etapa do assistente que falhou — lemos todos os relatos.