vpsnet-mcp 2.6.0 → 2.7.0

package/README.md

@@ -4,7 +4,7 @@
 
 ## 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
+- **<!-- tool-count -->371<!-- /tool-count --> tools** (local package; the hosted connector offers a subset) covering VPSNet service management, networking (private networks, server firewall, port forwarding, public addresses, load balancers, VPN), 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)
@@ -20,7 +20,7 @@
 
 ## 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 profile also includes scoped DNS, domain and certificate management, public SSH keys, backup browsing and, while VPSnet offers it, server rescue. 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](docs/REMOTE_MCP.md) for connection setup,
@@ -307,7 +307,7 @@ This MCP server manages your VPS infrastructure through the VPSnet.com API, incl
 
 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](https://github.com/bacarrdy/mcp-server-ssh) for direct server connectivity via MCP tools.
+For environments without native SSH access, pair this with [mcp-server-ssh](https://github.com/bacarrdy/mcp-ssh-server) for direct server connectivity via MCP tools.
 
 **Combined config:**
 
@@ -628,8 +628,13 @@ Every request is sent with the `X-API-KEY` header (`VPSNET_API_KEY`).
 - **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.
+  exception: `networking:read` / `networking:manage` / `networking:order`,
+  `files:read` / `files:manage` (service file manager) and the App Cloud permissions
+  `projects:*` / `projectdb:*` are never implied by `full` or `read` and must be added
+  to the key explicitly. A key created
+  without a permission list (for example an older `full` key) reaches no network
+  function (private networks, the server firewall, port forwarding, public addresses,
+  load balancers, VPN) until `networking:read` or `networking:manage` is added to it.
 - **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`,
@@ -639,9 +644,11 @@ Every request is sent with the `X-API-KEY` header (`VPSNET_API_KEY`).
   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.
+- **Rate limits.** Each key has one request budget: 300 requests per 60 seconds by
+  default, and some DNS and domain operations have lower limits. On HTTP `429` wait
+  the `retry_after` seconds of the result (the API also sends `Retry-After`;
+  `X-RateLimit-Limit` / `-Remaining` show the budget) instead of retrying immediately. (The `rate_limit` value shown by
+  `list_api_keys` is stored with the key but is not what the limiter applies.)
 - API keys can never create, change or revoke API keys, and never receive admin
   access.
 
@@ -743,12 +750,14 @@ everything else.
 | `get_rdns` | Get current rDNS records | `services:read` | free |
 | `change_rdns` | Change reverse DNS (PTR) record | `services:manage` | free |
 | `clear_rdns` | Clear a PTR override and restore the automatic value | `services:manage` | free |
-| `flush_iptables` | Flush iptables rules (useful when locked out) | `services:manage` | free |
+| `flush_iptables` | Flush the iptables rules inside the server (useful when locked out by them); the server's public firewall is separate | `services:manage` | free |
 | `get_title` | Get the current service display title | `services:read` | free |
 | `change_title` | Change service display title | `services:manage` | free |
 | `toggle_ipv6` | Enable or disable IPv6 | `services:manage` | free |
 | `toggle_extra_settings` | Toggle ppp, fuse, tuntap, or nfs | `services:manage` | free |
 | `deploy_ssh_key` | Deploy an SSH key to a VPS; remote OAuth also requires `vm:exec` | `services:manage` | free |
+| `list_service_ssh_keys` | List which account SSH keys are on a Cloud VPS or Firecracker VPS; local package only | `services:read` | free |
+| `remove_service_ssh_key` | Remove one account SSH key from a server's root authorized_keys; local package only | `services:manage` | free |
 
 ### OS Reinstall
 | Tool | Description | Scope | Paid |
@@ -990,7 +999,7 @@ short-lived quote token.
 ### Service Rescue
 | Tool | Description | Scope | Paid |
 |------|-------------|-------|------|
-| `get_service_rescue` | Get rescue capability and current durable rescue session | `services:read` | free |
+| `get_service_rescue` | Get rescue capability and current durable rescue session; rescue is offered only while VPSnet has it switched on | `services:read` | free |
 | `enter_service_rescue` | Restart an eligible service into an advertised rescue image | `services:rescue` | free |
 | `exit_service_rescue` | Restore the exact pre-rescue boot configuration and state | `services:rescue` | free |
 
@@ -1090,10 +1099,11 @@ requested or decrypted by these tools. Router recipes retain a literal PSK
 placeholder; fill it only in the customer's external configuration workflow. Never automatically
 repeat a pickup after an uncertain response.
 
-For personal devices use WireGuard; IPsec IKEv2 is a site-to-site option only.
-Read the selected gateway's `capabilities.site_ipsec` and `ipsec_profiles`
-before selecting the protocol, vendor or cipher mode. A listed tool does not
-prove an older gateway image supports IPsec. Read router recipes with
+Devices support WireGuard or the operating system's built-in IKEv2 client when
+`capabilities.device_ikev2` is available. Connected locations support WireGuard
+or IPsec IKEv2; read `capabilities.site_ipsec` and `ipsec_profiles` before choosing
+site protocol, vendor or cipher mode. A listed tool does not prove an older
+gateway image supports that protocol. Read router recipes with
 `get_network_vpn_peer_recipe`; don't use a different vendor profile than the
 one used to create the peer unless the returned API guidance supports it.
 For IPsec, connected means an established SA and the handshake timestamp is a
@@ -1105,8 +1115,48 @@ that broader authorization explicitly. Selected-server access uses
 `grant_scope=servers`; replacing grants without a scope also selects servers,
 so inspect and preserve the intended scope when editing an existing device.
 
-This release exposes no customer network rename, existing-port fixed-IP edit,
-or appliance restart/rebuild tools. Fixed DHCP
+Site health webhooks use `list_network_vpn_site_health_webhooks` with
+`networking:read` and `create_network_vpn_site_health_webhook` or
+`delete_network_vpn_site_health_webhook` with `networking:manage`. The list
+shows only the public destination host. Creation needs a caller-generated
+X25519 public reveal key and returns the signing secret only in a sealed
+envelope for external decryption. The subscription and removal are immediate
+resources, with no operation ID or idempotency key. After an uncertain create,
+list the site's subscriptions before deciding whether to create another.
+
+NAT port forwarding publishes TCP or UDP ports of a private network's NAT public address on
+servers of that network. Read `get_network_port_forwards` first (rules, the router generation, per-rule
+exposure and eligible targets); `set_network_port_forwards` replaces the complete rule set at that
+generation, and an empty list withdraws every rule. A target is a Firecracker server of the network: one
+without a public IPv4 of its own, or the private interface of one that has its own public IPv4 (its replies
+go back through the network; the target's `reply_route` says whether that is in place). Cloud VPS servers
+are not targets. Security groups still decide what a server accepts.
+Poll the rules resource until `applied_generation` equals `generation`.
+
+The firewall of a server's own public interface (VPS and Cloud VPS, IPv4 and IPv6 incoming allow
+rules) is read with `get_service_public_firewall` and replaced as a whole with
+`set_service_public_firewall` at the read `generation`; `apply_service_public_firewall` sends the
+saved rules to the node again. Keep the management port (SSH, or RDP on Windows) open for the user's
+own address and ask the user for that address: `client_address` in the answer is only the address
+the API saw for the request. Over the hosted connector, network changes act only on servers selected for the connection (`service_not_selected` otherwise).
+
+`set_public_address_outgoing_source` makes an additional address attached to a VPS's public interface
+the source of the server's new outgoing IPv4 connections (or switches back to the server's own IP);
+`recheck_public_address_outgoing_source` asks a server again after an address left it.
+Reverse DNS of an additional address, a floating binding, a VPN's or a public load balancer's
+address uses `get_public_ip_rdns`, `set_public_ip_rdns` and `reset_public_ip_rdns` with a `target`
+field; a server's own primary address keeps `get_rdns` / `change_rdns`.
+`rebuild_network_load_balancer` rebuilds a public load balancer's proxies one at a time.
+
+An owned public address can also go directly onto the public interface of a server that has its own
+public IPv4 (`attach_public_address_to_server_interface`), only while `get_networking_capabilities`
+reports `public_address_server_public` as true; the tool reads that first and refuses without a change
+otherwise. Pick the server from `list_public_address_server_targets`, then follow the attachment on
+`get_network_public_address` (`target.kind=server_public`,
+`carrier.node_state`, `carrier.guest_state`, `carrier.instruction`). When the server agent is off the
+instruction is what the customer runs inside the server; `check_network_public_address_reach` asks again.
+
+This release exposes no customer network rename or existing-port fixed-IP edit. 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
@@ -1133,6 +1183,9 @@ feature gate.
 | `set_private_network_names` | Replace the complete internal DNS zone label and alias list | `networking:manage` | free |
 | `list_private_network_ports` | Read owned network ports, their fixed DHCP addresses, generations and attachment states | `networking:read` | free |
 | `list_service_private_ports` | Read private ports and order attachment recovery state for one owned service order number. | `networking:read` | free |
+| `get_service_public_firewall` | Read the firewall of a server's public interface (VPS or Cloud VPS): rules, generation and state | `networking:read` | free |
+| `set_service_public_firewall` | Switch the server's public firewall on or off and replace all its incoming rules  at the read generation | `networking:manage` | free |
+| `apply_service_public_firewall` | Send the saved firewall rules to the server's node again | `networking:manage` | free |
 | `list_network_attachment_candidates` | Read attachable services and each attachment_mode | `networking:read` | free |
 | `attach_private_network_port` | Attach an owned service; omit ipv4 for automatic allocation or pass a fixed usable address | `networking:manage` | free |
 | `detach_private_network_port` | Detach the owned server port | `networking:manage` | free |
@@ -1140,6 +1193,8 @@ feature gate.
 | `get_network_vpn_summary` | Read the network's VPN summary, including truthful absence; connected locations are managed on the gateway | `networking:read` | free |
 | `get_network_routed_egress` | Read this network's NAT/internet access, public address and qualification state. | `networking:read` | free |
 | `set_network_routed_egress` | Request the currently supported NAT transition for an owned network; the backend may refuse mode changes | `networking:manage` | free |
+| `get_network_port_forwards` | Read the NAT port forwarding rules of an owned private network: applied rules (protocol, external_port on the network's NAT public address, the target server's private_port_id and its internal_port), the router generation to send to set_network_port_forwards (not the network generation), state (empty, pending, active, failed), per-rule exposure (open_to_internet is true when the server's security groups admit that port from every IPv4 address), targets with eligible and unavailable_reason_code, capability (available, limit, protocols), last_change (a refused change with its nat_port_forward_refused_* reason_code) and suspended (rules kept while the network has no NAT address; they are on no router). | `networking:read` | free |
+| `set_network_port_forwards` | Replace the COMPLETE NAT port forwarding rule set of an owned network (rules: [] withdraws all of them) at the router generation read from get_network_port_forwards. | `networking:manage` | free |
 | `get_security_group_capabilities` | Read security-group availability and whether the network default policy can be changed. | `networking:read` | free |
 | `list_network_security_groups` | List groups in the owned project | `networking:read` | free |
 | `create_network_security_group` | Create a named allow-rule set | `networking:manage` | free |
@@ -1163,6 +1218,7 @@ feature gate.
 | `remove_network_load_balancer_member` | Remove a member from rotation using the load balancer generation. | `networking:manage` | free |
 | `add_network_load_balancer_listener` | Add a listener and optional initial members using currently offered protocol capabilities | `networking:manage` | free |
 | `remove_network_load_balancer_listener` | Remove a listener and its members; deleting the last listener is refused. | `networking:manage` | free |
+| `rebuild_network_load_balancer` | Rebuild every proxy of a public load balancer, one at a time, keeping its address and listeners | `networking:manage` | free |
 | `list_network_vpn_gateways` | List owned VPN gateways, their device peers and safe status | `networking:read` | free |
 | `get_network_vpn_gateway` | Read one owned VPN gateway, protocol-specific peer status, IPsec capabilities/profiles, device grant scopes and site options | `networking:read` | free |
 | `delete_network_vpn_gateway` | Request teardown of an owned VPN gateway; all devices lose connectivity | `networking:manage` | free |
@@ -1172,13 +1228,16 @@ feature gate.
 | `create_network_vpn_peer` | Add a device, or a connected location (site-to-site office router), with an externally generated one-time PUBLIC reveal key | `networking:manage` | free |
 | `take_network_vpn_peer_config` | Consume the device's sealed configuration ONCE | `networking:manage` | free |
 | `revoke_network_vpn_peer` | Revoke one device using the VPN GATEWAY generation | `networking:manage` | free |
-| `set_network_vpn_peer_grants` | Replace the device's complete reachable-server list when standalone VPN is available | `networking:manage` | free |
+| `set_network_vpn_peer_grants` | Replace a device or site's complete individual-server or network-wide access choice | `networking:manage` | free |
 | `get_network_vpn_egress_options` | Read supported VPN Internet exits and qualification | `networking:read` | free |
 | `set_network_vpn_peer_egress` | Set a device's private-only, inherited NAT, or advertised chosen exit policy | `networking:manage` | free |
 | `get_network_vpn_peer_recipe` | Read public IPsec router instructions with a PSK placeholder; no secret retrieval | `networking:read` | free |
 | `get_network_vpn_peer_history` | Read a device's or connected location's traffic and handshake history (24 h raw, 7 d, 30 d, 13 months) | `networking:read` | free |
 | `set_network_vpn_site_options` | Switch hub-and-spoke between the locations connected to a VPN | `networking:manage` | free |
 | `set_network_vpn_site_alert` | Switch the office-down e-mail of one connected location | `networking:manage` | free |
+| `list_network_vpn_site_health_webhooks` | List a site's signed health subscriptions and last delivery outcomes; URLs show public hosts only | `networking:read` | free |
+| `create_network_vpn_site_health_webhook` | Create a signed site health subscription with an external X25519 reveal public key; returns sealed signing material | `networking:manage` | free |
+| `delete_network_vpn_site_health_webhook` | Remove a site's subscription and cancel pending deliveries | `networking:manage` | free |
 | `set_network_site_route_mode` | Choose DHCP routes or an internal router for a network's routes to connected locations | `networking:manage` | free |
 | `list_network_products` | Read current paid products, live tier names, prices and purchase capability; public proxy load balancer 3/5-node offerings must come from this catalog. | `networking:read` | free |
 | `list_network_product_periods` | Read owned product periods, renewal availability and lifecycle facts. | `networking:read` | free |
@@ -1198,6 +1257,14 @@ feature gate.
 | `quote_network_public_address` | Quote a new paid public address for common checkout; no charge | `networking:manage` | Quote: `networking:order` |
 | `attach_public_address_to_network` | Attach or move an already-paid address to an owned network's NAT | `networking:manage` | free |
 | `attach_public_address_to_server` | Attach or move an owned paid public address to an eligible zero-public-IP server's private port | `networking:manage` | free |
+| `list_public_address_server_targets` | Search and page the account's servers as targets for attach_public_address_to_server_interface. | `networking:read` | free |
+| `attach_public_address_to_server_interface` | Attach an owned paid public address directly to the public interface of a server that has its own public IPv4 (service_id from list_public_address_server_targets with eligible true). | `networking:manage` | free |
+| `check_network_public_address_reach` | Ask again whether an owned public address attached to a server's public interface is reachable from the internet, and ask the server's own step again (for example after the server agent was started). | `networking:manage` | free |
+| `set_public_address_outgoing_source` | Use an additional address on a VPS's public interface for the server's new outgoing IPv4 connections, or switch back | `networking:manage` | free |
+| `recheck_public_address_outgoing_source` | Ask a server again to put its outgoing source back on its own IP | `networking:manage` | free |
+| `get_public_ip_rdns` | Read the reverse DNS of an additional, floating, VPN or load-balancer address (`target`) | `networking:read` | free |
+| `set_public_ip_rdns` | Set the reverse DNS hostname of such an address at its revision | `networking:manage` | free |
+| `reset_public_ip_rdns` | Remove the custom reverse DNS of such an address | `networking:manage` | free |
 | `detach_network_public_address` | Detach an owned public address from its current target; it stays owned for the paid period | `networking:manage` | free |
 | `quote_public_address_renewal` | Quote the address's next month without charging; use the returned quote and this key for confirmation. | `networking:manage` | Quote: `networking:order` |
 | `renew_network_public_address` | Pay the approved address renewal from balance with its exact quote ID/token and original key. | `networking:manage` | Paid: `networking:order` |
@@ -1205,9 +1272,32 @@ feature gate.
 | `get_network_public_binding` | Read one existing owned public binding's generation, state and assigned address | `networking:read` | free |
 | `bind_network_public_ip` | Bind an already reserved floating public binding to an owned private port when supported | `networking:manage` | free |
 | `move_network_public_ip` | Move a prepared floating public binding to another owned private port; confirm interruption to the old target. | `networking:manage` | free |
-| `configure_network_public_forwarding` | Configure an existing reserved forwarding binding's TCP/UDP listeners | `networking:manage` | free |
 | `delete_network_public_binding` | Request deletion of an existing binding using its generation | `networking:manage` | free |
 
+### VPN gateways and sites (more)
+| Tool | Description | Scope | Paid |
+|------|-------------|-------|------|
+| `restart_network_vpn_gateway` | Restart the owned VPN VM in place. | `networking:manage` | free |
+| `rebuild_network_vpn_gateway` | Rebuild the owned VPN VM with its existing address and devices. | `networking:manage` | free |
+| `set_network_vpn_internet_exit` | Choose none, the VPN's own IPv4, or its attached network NAT as Internet exit. | `networking:manage` | free |
+| `take_network_vpn_site_line_config` | Consume the second IPsec line's sealed key exactly once with line=2. | `networking:manage` | free |
+| `rotate_network_vpn_ipsec_key` | Rotate an IPsec site's pre-shared key. | `networking:manage` | free |
+| `save_network_vpn_router_setup` | Save nonsecret backend-catalogue router version and local interface/zone fields for an IPsec site, optionally line 2. | `networking:manage` | free |
+| `set_network_vpn_site_bgp` | Enable or change BGP over an eligible IPsec site using the gateway generation. | `networking:manage` | free |
+| `add_network_vpn_site_line` | Add line 2 to an IPsec site using the gateway generation and an external X25519 public reveal key. | `networking:manage` | free |
+| `set_network_vpn_site_main_line` | Choose line 1 or 2 as the main IPsec line using the gateway generation; optional DPD applies to both. | `networking:manage` | free |
+| `remove_network_vpn_site_second_line` | Remove line 2 using the gateway generation. | `networking:manage` | free |
+| `start_network_vpn_tunnel_test` | Start a backend tunnel test for a site or supported WireGuard peer; optional line selects 1 or 2. | `networking:manage` | free |
+| `get_network_vpn_tunnel_test` | Read one owned tunnel test by its returned ID; while running, poll no faster than the backend's one-second guidance. | `networking:read` | free |
+| `set_network_vpn_site_reach` | Set this site's load-balancer/floating-IP reach choice, or null to follow its VPN default. | `networking:manage` | free |
+
+| `rename_network_vpn_gateway` | Rename an owned VPN's customer label. | `networking:manage` | free |
+| `update_network_vpn_gateway_image` | Apply the backend-qualified reviewed VPN image in place. | `networking:manage` | free |
+| `check_network_vpn_public_access` | Preview the complete VPN public-source lists without applying them. | `networking:read` | free |
+| `set_network_vpn_public_access` | Replace the complete WireGuard/IPsec public-source lists at the VPN gateway generation. | `networking:manage` | free |
+| `set_network_vpn_ipsec_tuning` | Replace an IPsec site's advanced tunnel choices using the gateway generation. | `networking:manage` | free |
+| `quote_network_vpn_traffic_pack` | Quote a traffic pack for this owned VPN using an offered tier from get_network_vpn_gateway traffic. | `networking:manage` | Quote: `networking:order` |
+
 <!-- tool-reference:end -->
 
 ## Worked examples
@@ -1285,12 +1375,19 @@ at the location given by `zone.verification.next_step`, then call
 
 ## Getting an API key
 
-1. Log in at [vpsnet.com](https://www.vpsnet.com)
-2. Go to **Account** > **API Keys**
-3. Click **Create API Key**
-4. Give it a name and copy the key
+1. Log in at [vpsnet.com](https://www.vpsnet.com) and open **Account** > **API Keys**:
+   <https://www.vpsnet.com/en/management/account/api-keys>
+2. Click **Create API Key**
+3. Give it a name, choose the access level and, for network tools, add `networking:read`
+   or `networking:manage` (they are never included by default)
+4. Copy the key
+
+The key is shown only once — store it securely. The full API description is
+<https://www.vpsnet.com/openapi-v1.yml>.
 
-The key is shown only once — store it securely.
+To use ChatGPT, Claude, Gemini or Grok without an API key, connect the hosted
+connector instead; connections are created and managed in **Account** > **AI connections**:
+<https://www.vpsnet.com/en/management/account/ai-connections>.
 
 ## Troubleshooting
 
@@ -1343,18 +1440,18 @@ Malformed or oversized URL identifiers are rejected before an API request.
 |---|---|---|
 | `aiScopedApiKeyCannotManageAccount` (403) | The key is an **AI-scoped key**. Those are issued only for VPSnet AI assistant inference and are deliberately refused on the entire account API. Granting scopes cannot change this — the restriction is on the key type. | Create a separate key with scope `full` (or `read` for GET-only use) and use that here. Keep the AI-scoped key for inference. |
 | `apiKeyRejected` (401) | The key failed authentication outright. The API returns one identical 401 for every cause, so it is one of: unknown, revoked, expired, malformed, or your source IP is not on the key's IP allowlist. | Check the key is active and copied whole, and that any IP allowlist includes the address this server calls from. |
-| `readOnlyApiKeyCannotWrite` (401) | A read-scoped key was used for a write; read keys are limited to GET. | Use a full-scope key, or stay on read-only tools. |
-| `apiKeyScopeMissing` (403) | The key authenticated but lacks the granular scope named in `requiredScope`. | Add that scope in Account > API Keys. |
+| `readOnlyApiKeyCannotWrite` (403) | A read-scoped key was used for a write; read keys are limited to GET. | Use a full-scope key, or stay on read-only tools. |
+| `apiKeyScopeMissing` (403) | The key authenticated but lacks the granular scope named in `requiredScope`. | Add that scope in Account > API Keys (https://www.vpsnet.com/en/management/account/api-keys). |
 | `apiKeyForbidden` (403) | The endpoint refuses API keys entirely. API keys never grant admin access. | Use the panel with a signed-in session. |
 
 - 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)
+- Check that the key hasn't expired (Account > API Keys: https://www.vpsnet.com/en/management/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
+- Key deployment is asynchronous: follow the returned noty UUID with `wait_for_event` until it reports completed before attempting SSH
 
 ### `fetch is not defined` or unexpected errors
 

package/build/application-contract.js

@@ -1,3 +1,4 @@
+import { unboundedInteger } from './tool-schema.js';
 import { z } from "zod";
 export const applicationLogTailLinesSchema = z
     .number()
@@ -32,7 +33,7 @@ export const applicationActionSchema = z
     .describe("Supported lifecycle action. Update and rollback apply the exact backend-advertised immutable release. Selective data restore is a separate revision-bound operation.");
 export const applicationActionIdSchema = z
     .string()
-    .uuid()
+    .guid()
     .describe("Exact action UUID from the current installation latest_action.id");
 export const applicationExpectedVersionSchema = z
     .string()
@@ -82,7 +83,7 @@ const externalHttpsUrlSchema = z.string().max(500).refine((value) => {
  * app-additional-addresses-design-1005 section 2.3.
  */
 export const applicationAdditionalAddressSchema = z.object({
-    zone_id: z.number().int().min(1),
+    zone_id: unboundedInteger().min(1),
     name: z
         .string()
         .max(190)
@@ -97,7 +98,7 @@ export const applicationSingleAccessSchema = z.discriminatedUnion("mode", [
     z.object({ mode: z.literal("external_https"), url: externalHttpsUrlSchema }).strict(),
     z.object({
         mode: z.literal("managed_https"),
-        zone_id: z.number().int().positive(),
+        zone_id: unboundedInteger().positive(),
         subdomain: z
             .string()
             .max(190)
@@ -192,11 +193,11 @@ export function applicationResourceThresholdRequestBody(input) {
 }
 export const applicationDataRestorePointIdSchema = z
     .string()
-    .uuid()
+    .guid()
     .describe("Opaque eligible backup-point UUID returned by list_application_restore_points");
 export const applicationDataRestoreIdSchema = z
     .string()
-    .uuid()
+    .guid()
     .describe("Opaque selective restore UUID returned by restore_application_data");
 export const applicationDataRestoreQuoteTokenSchema = z
     .string()

package/build/auth-failure.js

@@ -17,7 +17,7 @@ function message(data) {
     const raw = record(data).message;
     return typeof raw === "string" ? raw : "";
 }
-const MANAGEMENT_KEY_FIX = "Create a management API key in the VPSnet panel under Account > API Keys "
+const MANAGEMENT_KEY_FIX = "Create a management API key in the VPSnet panel under Account > API Keys (https://www.vpsnet.com/en/management/account/api-keys) "
     + "(scope 'full', or 'read' if you only need GET reads) and set it as "
     + "VPSNET_API_KEY. A key is 'vpsnet_' followed by 43 characters.";
 /**
@@ -74,8 +74,8 @@ export function explainAuthFailure(status, data) {
                 ? `The API key authenticated successfully but is missing the '${required}' scope.`
                 : "The API key authenticated successfully but is missing a scope this endpoint requires.",
             fix: required
-                ? `Add the '${required}' scope to the key in Account > API Keys, or use a key that already has it.`
-                : "Grant the endpoint's scope to the key in Account > API Keys.",
+                ? `Add the '${required}' scope to the key in Account > API Keys (https://www.vpsnet.com/en/management/account/api-keys), or use a key that already has it.`
+                : "Grant the endpoint's scope to the key in Account > API Keys (https://www.vpsnet.com/en/management/account/api-keys).",
         };
     }
     if (payload.apiKeyForbidden === true) {
@@ -105,7 +105,7 @@ export function explainAuthFailure(status, data) {
                 + "not exist, was revoked, has expired, is malformed, or your source "
                 + "IP is not on the key's IP allowlist. Note this is NOT the "
                 + "AI-scoped-key case, which returns 403 with its own message.",
-            fix: "Check the key in Account > API Keys: confirm it is active, unexpired, "
+            fix: "Check the key in Account > API Keys (https://www.vpsnet.com/en/management/account/api-keys): confirm it is active, unexpired, "
                 + "copied whole, and that any IP allowlist on it includes the address "
                 + "this server calls from. " + MANAGEMENT_KEY_FIX,
         };
@@ -113,7 +113,7 @@ export function explainAuthFailure(status, data) {
     return {
         code: "apiKeyForbiddenUnclassified",
         reason: "The account API refused this request for the authenticated key.",
-        fix: "Check the key's scopes and access settings in Account > API Keys.",
+        fix: "Check the key's scopes and access settings in Account > API Keys (https://www.vpsnet.com/en/management/account/api-keys).",
     };
 }
 /**

package/build/custom-project-contract.js

@@ -1,11 +1,11 @@
 import { z } from "zod";
 export const customProjectIdSchema = z
     .string()
-    .uuid()
+    .guid()
     .describe("Customer-owned recipe project UUID returned by list_application_recipes");
 export const composeAdoptionIdSchema = z
     .string()
-    .uuid()
+    .guid()
     .describe("Opaque Compose adoption UUID returned by the prepare operation");
 export const composeProjectLabelSchema = z
     .string()
@@ -45,7 +45,7 @@ export const customProjectSecretNamesSchema = z
     .default([])
     .describe("Secret variable names only; definitions and exports never contain values");
 export const customProjectRegistryCredentialIdsSchema = z
-    .array(z.string().uuid())
+    .array(z.string().guid())
     .max(8)
     .refine((ids) => new Set(ids).size === ids.length, {
     message: "Registry credential IDs must be unique",

package/build/file-restore-contract.js

@@ -22,7 +22,7 @@ export const fileBrowsePointIdSchema = z
     .describe("Backup point ID returned by list_restore_file_points");
 export const fileBrowseIdSchema = z
     .string()
-    .uuid()
+    .guid()
     .describe("Browse UUID returned by browse_restore_files");
 export const fileBrowseDirectoryEntryIdSchema = z
     .string()