VPSnet

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

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

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

1. Active [VPSnet.com](https://www.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=