VynVPN MCP Server

MCP (Model Context Protocol) server for VynVPN. Lets AI agents (Claude, Kiro, GPT, Copilot, etc.) manage VPN connections through natural tool calls.

Installation

Published on npm — no cloning or building required:

npx @vynvpn/mcp-server

Or install globally:

npm install -g @vynvpn/mcp-server

Requires Node.js 18+.

---

Authentication

API key only. The MCP server runs as a background process — there is no interactive login. Set your API key once in config and forget it.

To get an API key:

1. Register and verify your email at vynvpn.com
2. Go to Settings → API Keys → Create Key
3. Choose the scopes you need (see below)
4. Copy the key — it's only shown once

Why API key? API keys don't expire (unless you set a date), don't require re-authentication, and bypass the email verification gate on connect/disconnect. They are the correct auth mechanism for non-interactive agents and automation.

---

Setup

Claude Desktop / Kiro / Cursor

Add to your MCP config (mcp.json):

{
  "mcpServers": {
    "vynvpn": {
      "command": "npx",
      "args": ["@vynvpn/mcp-server"],
      "env": {
        "VYNVPN_API_KEY": "vyn_your_api_key_here"
      }
    }
  }
}

Alternative: local path (development)

If you've cloned the repo and built locally:

{
  "mcpServers": {
    "vynvpn": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "VYNVPN_API_KEY": "vyn_your_api_key_here"
      }
    }
  }
}

Environment Variables

Variable	Required	Default	Description
VYNVPN_API_KEY	Yes	—	Your API key (vyn_...). Server exits if missing.
VYNVPN_BASE_URL	No	https://api.vynvpn.com	Override for self-hosted or staging

---

Available Tools

Overview

Tool	Description
vynvpn_health	Start here. Full account state in one call.
vynvpn_list_nodes	List available VPN server locations
vynvpn_find_node	Search locations by country or name
vynvpn_connect	Connect to a VPN location
vynvpn_disconnect	Disconnect from a location
vynvpn_connection_status	Poll provisioning status
vynvpn_list_connections	List active connections
vynvpn_list_subscriptions	List subscriptions with usage
vynvpn_subscription_detail	Get one subscription
vynvpn_subscription_configs	Get provisioned VPN configs
vynvpn_list_plans	List available plans with pricing
vynvpn_ensure_free_sub	Ensure a free-tier subscription exists
vynvpn_usage_status	Data usage per subscription
vynvpn_create_checkout	Start Stripe checkout for a plan
vynvpn_billing_portal	Get Stripe portal URL
vynvpn_cancel_subscription	Cancel at end of billing period
vynvpn_list_invoices	List billing invoices
vynvpn_activate_trial	Activate one-time free trial
vynvpn_trial_status	Check trial availability
vynvpn_get_profile	Get account profile
vynvpn_list_tickets	List support tickets
vynvpn_get_ticket	Get ticket with messages
vynvpn_create_ticket	Open new support ticket
vynvpn_reply_ticket	Reply to a ticket
vynvpn_close_ticket	Close a ticket

---

VPN Connect Flow

Simple — let the API decide

vynvpn_connect()

No arguments needed. The API auto-detects your subscription and picks the best server based on your IP location and node load.

With country preference

vynvpn_connect(preferred_country: "Germany")

Explicit location

vynvpn_connect(location_slug: "de001")

If provisioning, poll until ready

vynvpn_connect() → { status: "provisioning", session_id: "..." }
vynvpn_connection_status(session_id: "...") → { status: "ready", config_link: "..." }

Disconnect

vynvpn_disconnect(location_slug: "de001")

---

Required API Key Scopes

Tool group	Required scope
Connect / disconnect / status	write:connect
List subscriptions / configs	read:subscriptions, read:config
Usage	read:usage
Plans	read:plans
Nodes	read:nodes
Account / health	read:account
Payments	read:payments

For full access, create a key with all scopes. For a read-only monitoring agent, use only read:* scopes.

---

Example Agent Conversations

"Connect me to a VPN" → vynvpn_health to check state → vynvpn_connect with no args

"Connect me to Germany" → vynvpn_connect(preferred_country: "Germany")

"What's my data usage?" → vynvpn_usage_status

"Show me available plans" → vynvpn_list_plans

"I'm having a connection issue" → vynvpn_health to diagnose → vynvpn_create_ticket(department: "technical", ...)

---

Development

git clone https://github.com/vynvpn/mcp-server.git
cd mcp-server
npm install
npm run build
VYNVPN_API_KEY=vyn_... npm start

Publishing

npm run build
npm publish --access public

The prepublishOnly script runs tsc automatically before publish.

License

MIT

---

Security

Found a vulnerability? Please do not open a public issue.

Report security concerns to security@vyntech.com.au with a description of the issue and steps to reproduce. We aim to respond within 48 hours.

We run a bug bounty program — responsible disclosures are eligible for rewards depending on severity. Details provided upon first contact.

---

Contributing

Contributions are welcome.

• Bug reports / feature requests → open an issue
• Code changes → open a pull request against next

Branch structure:

• next — active development, all PRs go here
• main — stable, merged from next when ready
• release/* — official rollouts cut from main

Please keep PRs focused — one concern per PR makes review faster. For significant changes, open an issue first to discuss the approach before writing code.