Connect Claude Code, Cursor, VS Code, Codex, or another MCP client to VeePN for Windows in a few minutes.
Overview
VeePN MCP Server lets an AI tool control your VPN through Model Context Protocol (MCP). Ask it to check VPN status, list locations, or connect before a test, without switching to the VeePN app.
The server runs inside VeePN for Windows on a local address, usually http://127.0.0.1:20091/mcp (Streamable HTTP). If port 20091 is busy, VeePN uses the next free port. The app always shows the current address. It accepts requests only from the same PC with a valid token. MCP controls the VPN. Opening websites and running tests use your AI tool’s own browser and terminal tools.
Requirements
- VeePN 2.8.1 or later on Windows 10 or 11, downloaded from the VeePN website. The Microsoft Store version does not support MCP Server.
- A VeePN trial or any paid plan.
- An AI tool on the same Windows PC that supports Streamable HTTP.
- VeePN running in a window or the system tray.
The server is available on the local Windows PC. This guide does not cover macOS, Linux, mobile, WSL, containers, remote agents, or CI/CD.
Enable MCP Server in VeePN
- Open VeePN for Windows and sign in.
- Go to Settings → Connect AI apps and turn on Allow AI apps to control VeePN. It is off by default.
- Copy Your private server address. It already contains the port and your token.
- Keep VeePN running in its window or tray.
Connect your AI tool
The fastest way is to copy the steps for your client from Settings → Connect AI apps: your private server address is already filled in. To set it up by hand, select your client below and replace the example address with Your private server address from VeePN. It contains the current port and your token.
Claude Code
Run the command in a native Windows terminal on the same PC as VeePN, then open /mcp in Claude Code to check the server. Paste your private server address from VeePN in place of the example. User scope keeps the address in your personal ~/.claude.json instead of the project. The command stays in terminal history, so treat that history as sensitive.
PowerShell
claude mcp add --transport http --scope user veepn "http://127.0.0.1:20091/mcp?token=<token>"
Official Claude Code documentation ↗
Cursor
Open your personal ~/.cursor/mcp.json (on Windows, under your user folder), add the veepn entry next to existing servers with your private server address from VeePN, save, and restart Cursor. Check the server in Cursor Settings → MCP. Keep this file out of repositories.
~/.cursor/mcp.json
{
"mcpServers": {
"veepn": {
"url": "http://127.0.0.1:20091/mcp?token=<token>"
}
}
}Official Cursor documentation ↗
VS Code
Run “MCP: Open User Configuration” from the Command Palette, add the veepn entry to servers with your private server address from VeePN, and save. Enable the VeePN tools in Agent mode. Keep the user profile file outside your workspace and source control.
User mcp.json
{
"servers": {
"veepn": {
"type": "http",
"url": "http://127.0.0.1:20091/mcp?token=<token>"
}
}
}Official VS Code documentation ↗
Codex
Add the server to %USERPROFILE%\.codex\config.toml with your private server address from VeePN, then run codex mcp list to check it. Keep this file out of repositories.
%USERPROFILE%\.codex\config.toml
[mcp_servers.veepn] url = "http://127.0.0.1:20091/mcp?token=<token>"
Official Codex documentation ↗
Other MCP clients
Add a Streamable HTTP server and paste Your private server address from VeePN as the URL, for example http://127.0.0.1:20091/mcp?token=<token>. The address contains your token: keep client configs and logs that include it private.
Verify the connection
- Open the list of MCP tools in your client and make sure the VeePN tools are enabled.
- Ask: “Use the VeePN MCP tool veepn_ping and show the result. Do not use curl or a shell command.”
- The tool result must be
pong. A reply that says “connected” without a tool call does not count. - Ask the client to call
veepn_list_locationsand pick a location ID from the response. - Ask it to call
veepn_connectwith that ID aslocation. - Check
veepn_statusandveepn_get_ip. The VeePN app shows the same change.
Available tools
Use the tools listed by your AI client. Use the slug returned by veepn_list_locations as the location ID, or optimal for automatic selection.
| Tool | Purpose | Parameters | Result |
|---|---|---|---|
veepn_ping |
Checks whether the MCP server responds. | None | pong |
veepn_status |
Reads VPN status and protection settings. | None |
state, location, protocol, vpn_ip, app_version, kill_switch, dns_protected, split_tunnel_enabled, double_vpn, and netguard with ads, trackers, and malware. |
veepn_get_connection_state |
Reads the connection state. | None |
state: connected, connecting, or disconnected. |
veepn_get_ip |
Reads cached IP values. | None |
public_ip is the cached real IP, including while connected. vpn_ip can be null. The tool does not look up a fresh public IP. |
veepn_get_location |
Reads location selection details. | None |
location, recommended, resolved. |
veepn_list_locations |
Lists available VPN locations. | Optional country (ISO alpha-2), tag, query. |
locations[] with slug, country, country_code, city, available, load, tags. |
veepn_get_settings |
Reads VPN settings. | None |
protocol, available_protocols[], kill_switch, auto_connect, dns_protected, double_vpn, debug_logging, and split_tunnel with enabled, mode, apps[]. |
veepn_get_netguard |
Reads the configured NetGuard settings. | None |
ads, trackers, malware. These values describe settings. |
veepn_get_dns_state |
Reads DNS policy and evidence. | None |
configured, policy_state, scope, stale, leak_evidence. |
veepn_diagnose_dns |
Runs A/AAAA lookups for veepn.com through the system resolver. | None | The check takes up to 7 seconds and may make an external DNS query. |
veepn_connect |
Connects or reconnects VeePN. Reconnecting can briefly interrupt network traffic. | Optional location (slug or optimal), wait (default true), timeout_sec (5–60 seconds, default 30). |
state, location, protocol, vpn_ip. |
veepn_disconnect |
Disconnects VeePN. |
wait defaults to true. |
During connection setup it can return Another operation is in progress. Wait for the operation to finish. See the Kill Switch note below. |
veepn_set_location |
Selects a location for the next connection. |
location. |
The active VPN connection stays on its current location. |
veepn_set_protocol |
Selects the VPN protocol. |
protocol: https, wireguard, ikev2, openvpn_tcp, openvpn_udp, shadowsocks, auto, or a name shown in the app. |
If connected, the change applies on the next connection (next_connect). |
veepn_set_setting |
Changes one VPN setting. |
setting: kill_switch, auto_connect, allow_lan, debug_logging, split_tunnel, or double_vpn. value: boolean. |
You can enable Kill Switch only while the VPN is connected. |
veepn_set_netguard |
Updates NetGuard settings. | At least one boolean: ads, trackers, malware. |
Changes apply on the next connection. |
DNS tools work only while the VPN is connected. Connect VeePN before running a DNS check.
Example workflows
Check protection before running a script
“Check that VeePN is connected and Kill Switch is on. Only then run my script.”
Ask your AI tool to check both the VPN connection and Kill Switch before it runs the script in its terminal.
Test your website from another country
“List VeePN locations and let me choose one. Connect, confirm the VPN IP, then open my website in your browser tool and report what you see.”
A verified connection, then a separate browser check.
Check localization
“Connect to the location I choose and verify it. Then check my site’s regional content and note the browser language and cookies separately.”
A report that separates IP-based behavior from browser settings.
Connect before a local test run
“Use the location I select and verify that VeePN is connected. Only then run the test command I approve.”
Tests start after the connection is confirmed. MCP does not run the command itself.
Repeat checks across locations
“For each location I select, connect, wait for a confirmed connection, record the VPN IP, and run my test. Stop on an error and report the last confirmed state.”
One location and one test at a time, with the IP recorded for each result.
Security and privacy
- Local only. The server listens on 127.0.0.1 and is not reachable from other devices or the internet. Do not forward its port or put it behind a tunnel.
- Token required. Every request needs the token from your app. Keep populated config files and screenshots out of repositories and shared logs.
- VPN controls only. MCP does not expose your account, password, or payment details. The release version of the VeePN app does not log MCP requests. Your AI client connects over loopback. Each tool call also contacts VeePN servers over HTTPS, so tools need an internet connection even when they return cached values.
-
Your AI provider may process tool results. VPN status, location, and IP returned by VeePN go to your AI tool and may be sent to its model provider, depending on the tool’s settings.
veepn_get_ipalso returns your real public IP. Review its data handling before use. -
Confirmations depend on the client. Read tools declare
readOnlyHint: true. Connect, disconnect, and changing a setting declaredestructiveHint: true. Your client controls when it asks for approval. - Network changes. Switching locations can briefly interrupt your network. With Kill Switch enabled, disconnecting can block internet access. While Kill Switch is blocking traffic, VeePN rejects disconnect requests from AI tools.
Turn off access or update the token
To stop MCP access, turn off Allow AI apps to control VeePN. This does not disconnect the VPN.
The token in your private server address persists after restarting the app and changes when you sign out and sign back in. After signing back in, copy the new address from VeePN and update it in each AI client. Remove the VeePN entry from any clients that should lose access.
Troubleshooting
Start with the error shown in your client. Before repeating a command that changes the VPN, check the connection state in the app. Remove tokens from any logs you send to Support.
Cannot connect: server is off or the app is closed
Open VeePN on this PC, turn on MCP Server, and keep the app running in its window or tray. Reconnect the server in your AI tool and run veepn_ping again.
MCP Server is missing in the app
Make sure you installed VeePN from the website, not from the Microsoft Store, and installed version 2.8.1 or later. If the option is still missing, contact VeePN Support.
401: outdated or wrong token
Copy the current private server address from VeePN, replace it in your client configuration, and reconnect. After signing out and back in, every client needs the new address. Do not paste the address into a support ticket.
403: Host or Origin rejected
Use the exact 127.0.0.1 address shown in VeePN from a client running natively on Windows. The server accepts Host values 127.0.0.1:<port> and localhost:<port> for the port shown in VeePN. Send requests without an Origin header or from the matching loopback Origin, for example http://127.0.0.1:20091. The server does not send CORS headers and rejects cross-origin preflights from external origins. If the error persists, send redacted client logs to Support.
Worked before, cannot connect now
If port 20091 was busy when VeePN started, the app may use a different port. Copy the address from Settings → Connect AI apps again and update your client.
404: endpoint not found
Use the address shown in VeePN, usually http://127.0.0.1:20091/mcp. Keep /mcp at the end. Do not use an /sse path.
daemon_unreachable
The app cannot reach its VPN background service. Check that VPN controls work in the app, restart VeePN, and try once more. If the app also fails, contact Support.
invalid_location
Run veepn_list_locations again and use an ID from its response. Location IDs cannot be guessed.
busy
Another connection or settings change is in progress. Wait for it to finish, check the connection state, and send one request at a time.
timeout
Check the connection state in VeePN before retrying: the action may have completed even though the client timed out.
not_entitled
MCP Server is available during a VeePN trial and on all paid plans. Check that your trial or subscription is active, or contact Support.
The AI tool uses curl instead of VeePN tools
Stop the request. Check that the VeePN server is connected and its tools are enabled in your client, then ask: “Use the VeePN MCP tool veepn_ping. Do not use curl or a shell command.”
Security software blocks the local connection
Allow the official VeePN app and the exact 127.0.0.1 endpoint in your antivirus or firewall, or ask your administrator for a narrow rule. Do not open an external port or expose the server through a tunnel.
Contact VeePN Support with your Windows version, VeePN version, AI client and its version, the error text, and steps to reproduce.
FAQ
What is VeePN MCP Server?
VeePN MCP Server is a local Model Context Protocol server built into VeePN for Windows. It lets AI tools such as Claude Code, Cursor, VS Code, and Codex check your VPN status, list locations, and connect or disconnect VeePN on your PC.
Which AI tools can I use?
Setup guides cover Claude Code, Cursor, VS Code, and Codex. For other clients, use the Streamable HTTP setup instructions and check that the VeePN tools appear.
Which devices are supported?
VeePN 2.8.1 or later on Windows 10 or 11, downloaded from the VeePN website. The Microsoft Store version, macOS, Linux, mobile apps, and browser extensions do not support MCP Server.
Is MCP Server included in my plan?
MCP Server is included at no extra cost during a VeePN trial and on all paid plans.
Can the AI tool see my account or payment details?
No. MCP gives access to VPN controls only. Results such as VPN status, location, and IP go to your AI tool and may be processed by its model provider, depending on the tool’s settings.
Can I use it remotely or in CI/CD?
No. The server runs only on 127.0.0.1 inside the desktop app. Remote machines, containers, WSL, and headless CI/CD runners cannot reach it.
How do I turn access off?
Turn off MCP Server in the VeePN app. Signing out and back in changes the token. Reconnect only the clients you want to keep using. Turning off MCP Server does not disconnect the VPN.
Is this the same as VeePN AI Assistant?
No. MCP Server lets an external AI tool control VeePN. AI Assistant is a separate feature inside the VeePN app.