VPSnet README

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

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

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

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

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

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

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

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

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

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'

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

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

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

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

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

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

OS Reinstall

Plan Changes (free)

Renewal & Billing

Ordering

Backups

Restore

Service files

Firecracker servers need the updated guest agent and Cloud VPS (KVM) the VDS file-manager switch; files:read / files:manage are explicit grants (an empty permission list does not include them).

SSH Keys

API Keys

API-key creation, changes, and revocation require a browser/session login. They cannot be performed by an MCP connection authenticated with an API key.

Free TLS certificates

For portable API or assistant installation, use customer_csr and retain the private key where the CSR was generated. A managed request can renew unattended, but MCP cannot export its private key. Issuance is asynchronous and quota-bound: poll get_free_certificate, follow get_free_certificate_instruction, and do not treat a queued request as issued.

Automatic SSL subscriptions

Automatic SSL is a portable paid ACME subscription. It works with a compatible client on VPSnet or another provider; it is not limited to managed applications. The private ACME server URL and EAB credentials are revealed only in the two-factor-protected customer portal. They are intentionally not an MCP tool or API-key response, so an assistant cannot copy them into model context.

Paid TLS certificates

Paid certificates are portable account products: customers may install them on Nginx, Apache, lighttpd, OpenLiteSpeed, HAProxy, Caddy, mail, API, load-balancer, or other TLS endpoints. They are separate from automatic HTTPS attached to a VPSnet-managed application. The MCP accepts only a public PKCS#10 CSR; the private key must remain under customer control and must never enter a tool argument or model context. Quote responses contain the final customer price in EUR, and ordering requires explicit approval plus the same idempotency key and short-lived quote token.

Domains

DNS

Snapshots

Service Rescue

Firecracker Functions

On-demand servers

Customer ordering is disabled while the on-demand server lifecycle is being validated. Current options disclose that automatic backups and snapshots are not included and outbound connections to mail-delivery TCP ports 25, 2525, 465, and 587 are restricted. Existing sessions remain available through list/get/delete for cleanup. Fixed-TTL and prepaid fields in the disabled compatibility schema are not a launch promise; the flexible duration and metered-billing contract must be published consistently before ordering is enabled.

Guest Agent

History

Public

SDN networking

Networking permissions must be granted explicitly: networking:read or networking:manage; the ordinary full/read defaults do not include them. Start with capabilities, then read the exact owned resource and its generation. The backend enforces tenant ownership, availability and server 2FA locks. Accepted, paid, and ready are separate states; poll the matching operation or resource. DNS changes are polled through the network's settings.dns_change.

New private/public load balancers, VPNs and public addresses use an explicit quote → common checkout → order-status flow. Quote tools always send prepare_after_payment=true: no provisioning happens before payment. Show the quote's exact EUR gross_amount, obtain approval, and pass the same idempotencyKey, quote_id and quoteToken to order_network_product. API keys additionally need full access, enabled paid operations, networking:order, and spend limits. Read get_network_payment_methods and select system=balance; non-balance checkout is refused for API keys. If confirmation is uncertain, recover by the original quote ID and key. For an SDN order with status=paid_pending, billing_state=captured and reason_code=network_product_ip_inventory_wait, payment is retained while public IP inventory is unavailable. Poll get_network_product_order with the same order ID; the backend resumes automatically when inventory returns. Do not create another order, charge again or submit a manual retry. manual_review or network_product_stock_reconciliation_required instead requires operator review; it does not authorize an automatic retry.

Ordinary VPS orders expose this wait through get_service.stateProcess.waitingReason=public_ip_inventory (also mirrored in the legacy stateProccess field). Poll the same service without reordering. stateProcess.attention=true requires operator attention. A successful payment or accepted create does not establish that the server is ready.

Public load balancer tiers alb_proxy_3/alb_proxy_5 use request kind proxy_lb; private tier nlb uses private_lb. Availability and prices come from the live product catalog. A legacy unpaid appliance-create endpoint is not an alternative to checkout.

Device configuration pickup is a one-time management action, even though its HTTP method is GET. Generate the reveal key pair outside MCP, submit only the X25519 public key, save the returned sealed ciphertext, and decrypt it outside the conversation. Neither private keys nor plaintext WireGuard configuration are requested or decrypted by these tools. Never automatically repeat a pickup after an uncertain response.

The current backend has no customer network rename, existing-port fixed-IP edit, appliance retry, or native site-to-site API in this release. Fixed DHCP addresses are selected at attach; removing/recreating an attachment requires separate approval and is not represented as an in-place edit. Legacy unpaid LB/VPN create routes, legacy stock-before-payment purchases and enabling automatic renewal via API keys are deliberately not exposed. Existing public binding management remains available; new public addresses use account ownership and common checkout. A tool being listed does not enable a backend feature gate.

Worked examples

Each example is a request to your assistant and the tools it calls.

Order a VPS (quote, then confirm)

Order the cheapest Cloud VPS with Debian and my SSH key, paid from balance.

1. get_order_plans for the product, then get_order_options for the chosen plan (OS, period, resource IDs) and list_ssh_keys for the key ID.
2. order_service with plan, os, period, resources, sshKey (or rootPassword, not both), payment: { payment: 1, successUrl: '', cancelUrl: '' } and a stable idempotencyKey. The first call returns a quote without charging. The API key needs vps:order (or vds:order, ds:order, fc:order) and spend caps.
3. Show the exact gross EUR total and billing period. After the customer's approval, repeat the unchanged order and key with the returned quoteToken, expected_total_eur and acknowledge_charge: true. Inspect the original attempt in the panel if its outcome is unknown; do not create another key to retry it.
4. Poll get_service for the returned order number; payment accepted is not server ready.

Networking (quote, then order)

Add a private load balancer to my network and pay from balance.

1. get_networking_capabilities, list_network_products and get_network_payment_methods (pick the system=balance method).
2. quote_network_product with kind (private_lb, proxy_lb or vpn_gateway), tier and an idempotencyKey; show the quote's EUR gross_amount.
3. After approval, order_network_product with the same idempotencyKey, quote_id, quoteToken, the balance payment and acknowledge_charge: true. If the result is uncertain, find_network_product_order by the original quote_id, then poll get_network_product_order. Never buy a second copy.

DNS record upsert

Point www.example.com at 203.0.113.10 with a 5 minute TTL.

1. list_dns_zones to find the zone_id, then get_dns_zone to inspect the existing records and their IDs (needs dns:read).
2. To add an A value, call upsert_dns_record with zone_id, name: "www", type: "A", content: "203.0.113.10", ttl: 300 (needs dns:write). Different content adds another record and keeps existing values. An identical name/type/content tuple updates its TTL/comment and re-enables it if disabled. To replace an existing value, use update_dns_record with its exact record_id and the desired name, type, content and TTL.
3. get_dns_zone to read the desired records back, or get_dns_zone_history to see the change.

For a waiting zone whose ownership TXT value was lost, first read get_dns_zone.zone.verification.record.value. Use reissue_dns_zone_verification only if that value is null/unrecoverable or the customer requests rotation. It supports both pending_verification and verification_expired; the previous value stops being accepted. Update the TXT at the location given by zone.verification.next_step, then call verify_dns_zone. Reissuing alone does not verify the zone or reset its status.

Order a paid certificate

Buy a one-year DV certificate for example.com; I generated the CSR myself.

1. list_certificate_catalog and get_certificate_catalog_product to choose a product and read its current EUR offer.
2. quote_certificate with product_id, offer_id, offer_generation, common_name (plus any alternative_names), the public PKCS#10 csr, the owned contact IDs and an idempotencyKey (needs certificates:order, paid operations and caps). Never send a private key.
3. After the user approves the exact total, order_certificate with the same request, the same idempotencyKey, the quote_token, the payment and acknowledge_exact_quote_and_payment: true.
4. get_certificate_validation (publish the challenge, for example through upsert_dns_record), then download_certificate once it is issued.

Getting an API key

1. Log in at vpsnet.com
2. Go to Account > API Keys
3. Click Create API Key
4. Give it a name and copy the key

The key is shown only once — store it securely.

Troubleshooting

MCP tools not appearing in Claude Code VS Code extension

1. Install Claude Code CLI: npm install -g @anthropic-ai/claude-code
2. Verify: claude --version should show a version number
3. Add server via CLI: claude mcp add vpsnet -- npx -y vpsnet-mcp
4. Completely restart VS Code (not just reload window)
5. Check ~/.claude.json for correct configuration

claude: command not found

Install the Claude Code CLI globally:

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

Verify your PATH includes npm global packages. On Windows, restart your terminal after installing.

Environment variables not working

For Claude Code extension, environment variables must be in the env object within .claude.json, NOT system environment variables:

"vpsnet": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "vpsnet-mcp"],
    "env": {
        "VPSNET_API_KEY": "your_actual_key_here"
    }
}

API key errors

This server needs a management API key. Every failure below is reported by the tools with an auth_problem object containing the cause and the fix, so read that rather than guessing from the HTTP status.

Tool failures carry isError: true while preserving the API error details and recovery guidance. Unknown mutation outcomes must be checked before another attempt. Service order numbers must be copied from list_services; ASCII letters, digits, and hyphens are supported, including multi-order suffixes. Malformed or oversized URL identifiers are rejected before an API request.

• Verify the key is correct (starts with vpsnet_ followed by 43 characters)
• Keys are shown only once at creation — if lost, create a new one
• Check that the key hasn't expired (Account > API Keys)

deploy_ssh_key succeeded but SSH still fails

• All VPSnet.com servers use root as the SSH username
• Key deployment is async — wait 15-30 seconds after deploying before attempting SSH

fetch is not defined or unexpected errors

This server requires Node.js 20+. If your default node is older (common with nvm setups), either:

• Set Node 20+ as default: nvm alias default 20
• Or use the nvm wrapper shown in the Codex section

License

MIT