Vpsnet MCP Server

vpsnet-mcp

Model Context Protocol (MCP) server for managing VPSnet.com services. Gives AI assistants access to VPS lifecycle operations, managed applications, DNS zones, domain registration and contacts, billing, API-key metadata, SSH-key provisioning, and related account tooling through the VPSNet API.

Features

• 280+ tools covering VPSNet service management, managed applications, free and paid TLS certificates, Automatic SSL subscriptions, DNS, domains, billing, API keys, and account operations
• Account & profile management
• VPS lifecycle (start, stop, restart, reinstall OS)
• Plan changes (free upgrades/downgrades; KVM/Firecracker disks cannot shrink)
• Service reverse DNS (rDNS/PTR records)
• Forward DNS zones, records, DNSSEC, templates, import/export, and DDNS tokens
• Domain availability, contacts, register/transfer/renew/restore quotes, and paid confirmations
• Publication-gated managed applications with install, health, events, and typed lifecycle actions
• SSH key management — deploy keys and gain direct server access
• API-key metadata inspection (key creation, changes, and revocation remain session-only)
• Backups, billing, invoices
• Ordering new VPS instances
• System status & pricing

Remote OAuth connector

The remote profile also includes scoped DNS, domain and certificate management, public SSH keys, server recovery and backup browsing. It uses the same customer APIs as the panel; permissions are enforced by the backend on every request.

The remote connector uses https://mcp.vpsnet.com/mcp and customer consent through VPSnet. See Remote AI connections for connection setup, permissions and supported operations. For expired or revoked authorization and unavailable consent choices, see reconnecting and requested permissions.

The distributable plugin README, manifests and skills are in English. See directory readiness for package validation and publisher requirements, and supported use cases for server, application and networking scenarios. Directory publication and provider account availability are separate from installing this source code.

See AI client setup for Gemini CLI, Cursor, Kimi Code, Kiro, Cline and other remote OAuth clients. Their packages share the same VPSnet endpoint and task skills. The npm package supplies the local MCP server; installable plugin bundles also carry the AI application's manifest and skills.

Build all client bundles with python3 scripts/package-distribution.py. The same build creates four self-contained skill imports for clients that import one skill folder or ZIP at a time. The output includes checksums and identifies each format. Public directory submission materials are in the catalog kit.

Ordering uses the existing VPSnet connection, with customer-controlled purchase permissions and spending limits. The AI shows the final price and asks for approval before charging the account balance. Availability follows the application’s distribution rules.

The instructions below describe the existing local stdio/API-key client.

Prerequisites

Before installing, ensure you have:

1. Node.js 20 or newer

   • Check: node --version
   • Linux/macOS: nodejs.org or your package manager
   • Windows: winget install OpenJS.NodeJS.LTS or download from nodejs.org
   • After installing Node.js, restart your terminal/editor

2. For Claude Code (CLI or VS Code extension) users:

   • Claude Code CLI installed globally: npm install -g @anthropic-ai/claude-code
   • Check: claude --version

3. Active VPSnet.com account with an API key (see Getting an API key)

Credential configuration paths

VPSNET_API_KEY is the preferred per-launch credential and takes precedence over files. For file-based configuration, set VPSNET_CONFIG_DIR to the absolute directory containing .vpsnet-mcp-key or .mcp.json. The key file takes precedence over mcpServers.vpsnet.env.VPSNET_API_KEY in that JSON file. Alternatively, VPSNET_API_KEY_FILE selects one absolute key-file path; an unreadable or invalid explicit file fails startup instead of choosing another account.

Without VPSNET_CONFIG_DIR, files are read only from the process's launch directory (cwd). This is the same for node /path/to/vpsnet-mcp/build/index.js and npx vpsnet-mcp: the package installation/cache directory and parent directories are never searched. Set the directory explicitly when an editor or MCP client launches from a different working directory. Keep credential files out of version control. VPSNET_API_URL takes precedence over the URL in that same .mcp.json; the existing trusted-host and HTTPS checks apply to either source.

Managed applications

Managed Applications, manual SSH, DNS, APIs, and other deployment surfaces are peer capabilities. Their order in this document and in the tool list is not a recommendation. Choose the path that best matches the user's requested outcome, target support, existing state, and explicit constraints. A catalog entry is one available managed path, not a reason to override a valid manual or custom deployment request. Catalog applications run as Docker containers in the customer's server and use typed installation and lifecycle tools.

Application reads require applications:read. Installation and lifecycle changes require applications:manage and an idempotency key; ordinary application lifecycle changes are not paid API-key operations. CPU, RAM, and disk figures are sizing recommendations, not installation gates: a supported application remains selectable during ordering and installable below those figures. Product, OS, architecture, and runtime compatibility remain hard requirements. Changes are asynchronous, so verify them with get_application_installation and get_application_events. Use get_application_health for a fresh container-health inspection and get_application_logs for recent size-bounded troubleshooting logs, optionally limited to one exact Compose service. Log inspections accept at most 500 lines and 131,072 bytes. These two read-scoped inspections create short-lived inspection jobs, so the API key must permit POST requests.

Installation detail includes bounded application and per-container CPU, memory, network, restart, and storage history when the worker reports it. Containers are identified only by Compose service and ordinal. Use configure_application_resource_thresholds after explicit confirmation to replace optional display thresholds. Omitted values clear a threshold; the thresholds only highlight measurements and do not enforce resources, trigger server actions, or affect billing. Set email_enabled after explicit confirmation to send one account email when a threshold is reached and one when it recovers; repeated measurements above the same threshold do not resend.

Use configure_application_access to change how an installed application is reached. Read the installation first and pass its current revision with a new idempotency key. platform_https allocates an opaque VPSnet hostname with automatic DNS and HTTPS, private has no public listener, public_http uses the server's public IP over HTTP, and managed_https uses an eligible VPSnet-managed DNS zone. external_https records an existing customer-managed HTTPS address; VPSnet does not configure or validate its DNS, TLS certificate, or reverse proxy.

A managed_https access may also list additional_addresses (up to 4 per endpoint, 8 per application): other names in the customer's own VPSnet DNS zones, each with zone_id, name, action and approve_dns: true. An empty name or "@" is the zone's bare domain, so example.com can sit next to www.example.com. action is redirect (default; a 301 to the main address that keeps the path and query) or serve (opens the same application). Adding or removing an additional address never changes the main address. The list is the complete wanted set: an access change that omits additional_addresses removes the saved ones, so pass them again to keep them. Additional addresses are refused on every other access mode, and VPSnet charges nothing for them.

list_application_registry_credentials exposes only private registry credential metadata. Registry token creation and rotation are intentionally not MCP tools: use the VPSnet panel or direct REST API so a token never enters a model prompt or tool argument. Metadata can identify Docker Hub, GHCR, or an exact custom HTTPS registry hostname.

Customer recipes are customer-owned Compose definitions, separate from VPSnet catalog blueprints. They can be validated on the target worker, saved as immutable revisions, installed through the managed lifecycle, and exported without secret values. VPSnet catalog recipes are never exportable. Container discovery is bounded and read-only: it reports customer and managed containers without returning environment values or mounts, and it never adopts or modifies detected containers. Controlled adoption is a separate prepare, inspect, and explicit-confirm flow for an eligible Compose project. The initial takeover is one-time, but its exact external-volume binding remains signed into later lifecycle actions. Recovery restarts the source only after the managed replacement is conclusively contained; uncertain outcomes fail closed.

An immutable update is available only when get_application_installation returns an available_actions entry with type: "update". After explicit user confirmation, call update_application with the exact advertised expected_blueprint_version and expected_upstream_version, and a new idempotency key. Keys are client-global: reuse a key only to replay the exact same request, never for another service or operation. The backend selects and freezes the eligible published release; the caller does not submit an image, tag, or target version.

No separate application backup is created. On supported Firecracker services, list_application_restore_points returns opaque application-consistent nightly whole-VM points for the exact current installation revision. Viewing points is free, but API keys require applications:manage, paid operations enabled, applications:restore paid scope, and full access because the response includes the account balance. quote_application_data_restore freezes the exact charge without debiting the account. restore_application_data requires the returned quote token, the same idempotency key, and explicit confirmation of both payment and data replacement. Paid API keys also require applications:restore, paid operations enabled, and daily/monthly spend caps. It replaces only worker-derived declared application data, excludes secrets and unrelated Docker/server data, and requires rollback capacity. Poll get_application_data_restore; needs_attention remains locked and must not be treated as success. These tools never accept or expose PBS credentials, archive names, devices, or filesystem paths.

Installation list and detail responses carry a per-platform capabilities block — data_restore, console, compose_adoption, custom_projects and log_service_filter — plus a separate access.capabilities.can_configure flag. Treat those flags as the authority on what an installation supports rather than attempting an action and reading the failure.

Uninstall permanently deletes the managed containers, configuration, saved credentials, and application data; existing server backups are retained. The uninstall_application call requires acknowledge_data_loss=true, and it must only be set after explicit user confirmation.

The MCP surface is task-oriented rather than a one-to-one mirror of every REST route. Legacy SMS micro-payment and macro-payment callback integrations remain available through the documented REST API and control panel, but are intentionally not exposed as MCP tools. Public pre-login order and domain-search routes likewise have authenticated MCP equivalents where an account operation needs them.

TLS certificates and Automatic SSL

Certificate products are not limited to managed applications. Portable DV, OV, and EV orders can be installed on customer-controlled web servers, proxies, mail servers, load balancers, APIs, or other TLS-capable systems. Automatic SSL subscriptions instead connect a compatible ACME client on VPSnet or another provider and keep short-lived certificates current during the paid term.

Eligible accounts can also request no-cost portable DV certificates through get_free_certificate_eligibility → preflight_free_certificate → create_free_certificate. For API or assistant deployment, create a CSR on the destination and keep its private key there; MCP accepts only the public CSR and later returns only the public certificate chain. VPSnet-managed keys support unattended early renewal, but their export remains portal-only behind two-factor verification. Free certificates, paid certificate files, paid Automatic SSL, and application Managed HTTPS are separate products and lifecycle surfaces.

Use list_certificate_catalog to distinguish portable_certificate from acme_subscription offers. Automatic SSL follows quote_automatic_ssl_subscription → order_automatic_ssl_subscription, with the exact unchanged request, quote token, idempotency key, and explicit payment approval. Read state with list_automatic_ssl_subscriptions and get_automatic_ssl_subscription. Additional names use quote_automatic_ssl_domain → order_automatic_ssl_domain; the API prevents paying twice for names already covered by base/www or wildcard/base rules. During the final 30 days, an eligible next term uses quote_automatic_ssl_renewal → order_automatic_ssl_renewal and is prepaid from account balance only after the exact EUR total is approved. Cancellation, domain removal, and same-type correction use cancel_automatic_ssl_subscription, remove_automatic_ssl_domain, and replace_automatic_ssl_domain; ambiguous state is reconciled with refresh_automatic_ssl_subscription, never by inventing a second mutation. Private ACME server and EAB credentials stay in the two-factor-protected customer portal and are intentionally unavailable to API keys and MCP, so they cannot enter model context.

Restoring a whole service

request_restore is paid and destructive: it charges the restore price from the account balance and overwrites the whole service disk with the backup point, losing everything written since. It is a confirmation call, not a price enquiry — the API refuses a body that does not carry an explicit confirmation, and refuses the charge outright if the price has moved since it was disclosed.

There is no dialog on this surface to collect that confirmation, so the tool does not manufacture it. acknowledge_data_replacement and acknowledge_restore_charge must each be true, and are only to be set after the user has actually approved the disk replacement and the charge — the same rule as acknowledge_data_loss on uninstall_application. Omitting either is a schema error, so an unattended caller cannot fall through to a charge: nothing is even quoted.

expected_total_charged is the VAT-inclusive total_charged you read from get_restore_status and showed the user, passed back unchanged. Do not re-read it just before the call: it is meant to be the figure the customer agreed to, and a freshly fetched number would agree with whatever the price has become and defeat the check entirely. If the price has moved, the restore is refused as restoreQuoteChanged with the current total and nothing is charged; disclose the new figure, get approval again, and retry.

Browsing inside a backup

Looking inside a backup is free and completely separate from paying to restore one. list_restore_file_points, browse_restore_files and get_restore_file_browse only read a backup's directory listing: they never charge the account, never overwrite the disk, and never put a file back on the server. Initially supported on Firecracker VPS.

Browsing is asynchronous. browse_restore_files creates a persisted job and queues worker activity, so its MCP annotation is readOnlyHint: false even though the backup and running server are unchanged. It returns a browse id in a pending state; poll get_restore_file_browse until state is succeeded. Entries exist only in that state — a failed browse carries an errorCode and no listing, and must not be presented as an empty directory.

Directories can hold an enormous number of files, so the server selects pages of 200 or 1,000 entries according to the worker capability. When result.nextOffset is non-null, call again with the same sourceBrowseId and directoryEntryId and set offset to that cursor. Use result.pageSize rather than assuming 200 when moving backwards. Subdirectories are entered with the opaque id of a type: "directory" entry; filesystem paths are never accepted. Entry types are file, directory, symlink and unsupported.

Folder search (the filter argument) matches entry names in the one directory being listed — case-insensitive substring, never a path, never recursive. It depends on a worker capability that older nodes do not report, so list_restore_file_points returns searchAvailable. browse_restore_files checks that flag before sending a filter and fails with serviceFileBrowseSearchUnavailable when search is unsupported, rather than quietly returning an unfiltered listing that would be mistaken for search results. Plain browsing keeps working on those nodes.

Restoring selected files back onto the server is a paid operation and is deliberately not exposed here; use the VPSnet panel for it.

SSH access workflow

This MCP server manages your VPS infrastructure through the VPSnet.com API, including SSH key provisioning. Once an SSH key is deployed to a VPS, the AI assistant can connect directly using its environment's terminal (e.g. Claude Code's Bash tool, Cline's terminal).

Typical flow:

1. AI reads the local machine's public key (~/.ssh/id_rsa.pub)
2. Uploads it to VPSnet.com via create_ssh_key
3. Deploys it to a VPS via deploy_ssh_key with explicit vm:exec permission for remote OAuth (or passes it when ordering with order_service)
4. Connects directly: ssh root@<vps_ip>

Most AI coding environments (Claude Code, Cline, Cursor, Codex) have built-in terminal access, so the AI can SSH into your VPS immediately after deploying a key — no extra tools needed.

For environments without native SSH access, pair this with mcp-server-ssh for direct server connectivity via MCP tools.

Combined config:

{
  "mcpServers": {
    "vpsnet": {
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here"
      }
    },
    "ssh": {
      "command": "npx",
      "args": ["-y", "mcp-server-ssh"]
    }
  }
}

Getting started

Choose your environment:

• Claude Code (CLI) — Terminal-based AI coding
• Claude Code for VS Code — VS Code extension
• Claude Desktop — Desktop app
• VS Code with GitHub Copilot — Copilot agent mode
• Cline / Cursor / Windsurf / Roo Code / Codex — Other clients

The following local stdio example uses the mcpServers configuration format supported by several MCP clients. Use your client's native schema; VS Code's .vscode/mcp.json uses servers instead. For customer OAuth and the hosted connector, use AI client setup.

{
  "mcpServers": {
    "vpsnet": {
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here",
        "VPSNET_API_TIMEOUT_MS": "45000"
      }
    }
  }
}

claude mcp add vpsnet -- npx -y vpsnet-mcp

Set the environment variable before running:

export VPSNET_API_KEY="your_api_key_here"
export VPSNET_API_TIMEOUT_MS="45000"

This section is for the Claude Code VS Code extension, not GitHub Copilot. If you use VS Code with GitHub Copilot, see the VS Code with GitHub Copilot section instead.

Step 1: Install Claude Code CLI globally (required for the extension):

npm install -g @anthropic-ai/claude-code

Step 2: Add the MCP server via CLI:

claude mcp add vpsnet -- npx -y vpsnet-mcp

Step 3: Add your API key. Edit ~/.claude.json (or C:\Users\<username>\.claude.json on Windows), find the vpsnet server section and add the env block:

"vpsnet": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "vpsnet-mcp"],
    "env": {
        "VPSNET_API_KEY": "your_api_key_here",
        "VPSNET_API_URL": "https://api.vpsnet.com"
    }
}

Step 4: Restart VS Code completely (Ctrl+Shift+P > "Reload Window" or close and reopen).

Step 5: Verify by asking Claude: "Get my VPSnet account info"

Windows users: Use PowerShell or CMD (not Git Bash) when running claude mcp add commands.

The code --add-mcp command does NOT work with Claude Code extension — that's for VS Code Copilot only.

Follow the MCP install guide, use the standard config above.

Open Cline MCP settings and add to your cline_mcp_settings.json:

{
  "mcpServers": {
    "vpsnet": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here"
      },
      "disabled": false
    }
  }
}

Use the Codex CLI:

codex mcp add vpsnet --env VPSNET_API_KEY=your_api_key_here -- npx -y vpsnet-mcp

Or edit ~/.codex/config.toml:

[mcp_servers.vpsnet]
command = "npx"
args = ["-y", "vpsnet-mcp"]

[mcp_servers.vpsnet.env]
VPSNET_API_KEY = "your_api_key_here"

If your system's default Node.js is older than 20 (common with nvm — check with node --version), wrap the command so nvm loads the right version:

codex mcp add vpsnet --env VPSNET_API_KEY=your_api_key_here -- bash -lc 'source ~/.nvm/nvm.sh >/dev/null 2>&1 && nvm use --silent 20 && npx -y vpsnet-mcp'

Note: Codex requires network access to install packages via npx. If you run Codex in a restricted sandbox without network, npx installs will fail.

Go to Cursor Settings > MCP > Add new MCP Server. Use command type with the command npx -y vpsnet-mcp. Or add manually to .cursor/mcp.json:

{
  "mcpServers": {
    "vpsnet": {
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here"
      }
    }
  }
}

Open Roo Code MCP settings and choose Edit Global MCP (currently mcp_settings.json), or Edit Project MCP for .roo/mcp.json:

{
  "mcpServers": {
    "vpsnet": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here"
      },
      "disabled": false
    }
  }
}

For the hosted customer OAuth connection, run MCP: Add Server and enter https://mcp.vpsnet.com/mcp, or merge this native VS Code entry into .vscode/mcp.json, preserving other servers:

{
  "servers": {
    "vpsnet": {
      "type": "http",
      "url": "https://mcp.vpsnet.com/mcp"
    }
  }
}

Complete the browser sign-in and consent flow when requested. Copilot's portable workspace .mcp.json and user ~/.copilot/mcp-config.json use a top-level mcpServers object instead. These formats are distinct from the Claude Code extension's configuration.

For the separate local stdio package with your own VPSnet API key, install using the VS Code CLI:

code --add-mcp '{"name":"vpsnet","command":"npx","args":["-y","vpsnet-mcp"],"env":{"VPSNET_API_KEY":"your_api_key_here"}}'

For manual native VS Code configuration, place that local server's command, args and private env under servers.vpsnet, rather than copying the generic mcpServers wrapper. VS Code's MCP: Reset Cached Tools refreshes a stale tool catalog. See official MCP configuration.

This is for GitHub Copilot agent mode in VS Code. For the Claude Code extension, see the Claude Code for VS Code Extension section.

Current official Windsurf documentation redirects to Devin Desktop. Choose the agent you are using: legacy Cascade and the current Devin Local agent have different MCP setup paths.

For Devin Local, add and authenticate the hosted connector with the Devin CLI:

devin mcp add vpsnet https://mcp.vpsnet.com/mcp
devin mcp login vpsnet --scopes services:read

This requests a read baseline. Request the documented scopes required for other tasks through a new authorization flow before approving them. If authorization is lost, use the Desktop Authenticate action, or devin mcp logout vpsnet followed by the login command. Current CLI versions use dedicated .devin/mcp_config.json, .devin/mcp_config.local.json or user ~/.config/devin/mcp_config.json files.

For legacy Cascade, open the panel's Actions → Open MCP config file and merge a server under mcpServers with serverUrl: "https://mcp.vpsnet.com/mcp". Complete its OAuth flow. Cascade has a 100-tool total limit, so inspect the enabled tools. The local stdio example above is a separate API-key connection.

Follow the official Devin Local MCP guide or legacy Cascade guide for your surface. Client authentication and VPSnet compatibility still need verification on the actual client version.

Windows Users

• Use PowerShell or CMD (not Git Bash) for claude mcp add commands
• Config file location: C:\Users\<YourUsername>\.claude.json
• Install Node.js: winget install OpenJS.NodeJS.LTS or download from nodejs.org
• After installing Node.js, restart your terminal and VS Code
• Environment variables in Claude Code extension must be in the env object within .claude.json, NOT system environment variables

Environment variables

Requests go out from the machine that runs this server, not from your browser. A deployment that restricts access by source address can answer a blocked request with an HTML 403 page from its web server; the tool result then says so (non_api_response: true, http_status: 403) instead of passing the page on. Every error result carries http_status; a 429 also carries retry_after.

Authentication, scopes and paid operations

Every request is sent with the X-API-KEY header (VPSNET_API_KEY).

• Use a management key. Its access level is full (reads and changes) or read (GET only). An AI-scoped key is issued only for VPSnet AI assistant inference and is refused on every account route, so no tool here works with one; the error result carries auth_problem with the reason and the fix.
• Granular scopes only narrow a key. A key with an empty scope list keeps everything its access level allows; listing scopes (for example dns:read, services:manage) restricts it. X:manage includes X:read. Networking is the exception: networking:read / networking:manage / networking:order are never implied by full or read and must be granted explicitly.
• Paid operations are a separate gate. A tool marked Paid or Quote in the tables below needs a full-access key, paid_operations_enabled, the named paid scope (vps:order, vds:order, ds:order, fc:order, domains:order, domains:renew, domains:transfer, certificates:order, applications:restore, services:restore, fn:invoke, networking:order), configured daily and monthly spend caps, and a stable idempotencyKey (reuse the same key to replay an uncertain attempt, never a new one). Orders run quote, then confirm with the returned quoteToken; disclose the exact EUR total to the user before confirming. Use list_api_keys to see your key's scopes, paid scopes, caps and rate limit.
• Rate limits. Requests are rate-limited per key (rate_limit in list_api_keys, requests per minute). On HTTP 429 back off and retry after retry_after seconds instead of retrying immediately.
• API keys can never create, change or revoke API keys, and never receive admin access.

Tools

The tables below are generated: edit scripts/tool-scopes.json (or the tool registration) and run npm run docs:tools; npm test fails when they drift.

Scope is the granular API-key scope the tool needs (none = any management key; a + b = both; a or b = either, depending on the object). Paid: Paid: x spends account balance and needs the paid scope x plus the gates above; Quote: x creates a price quote without charging but is gated the same way; Paid alone charges the balance with a full-access key and no separate paid scope; Needs paid scope: x is a read that exposes balance or price data; Billed while kept means free for an initial window, then metered; free is everything else.

Account

Services

Managed Applications

Service Actions

Service Settings

Documentation truncated — see the full README on GitHub.