Skip to main content

Tools and Operations Reference

A complete reference for all tools exposed by the Hyperstack API MCP Server, grouped by domain.

This document provides the complete reference for all supported tools exposed by the Hyperstack API MCP Server. Tools are grouped by domain and include concise descriptions aligned with their underlying infrastructure operations.

The MCP Server translates these tools into authenticated Hyperstack API operations and returns structured, human-readable responses within your MCP-compatible client.

Important: Live Infrastructure Changes & Data Loss Risk

This MCP server can create, modify, and delete real Hyperstack resources, which may incur charges on your account. Always review actions before confirming them. NexGen Cloud is not liable for any unintended resource usage, costs, or data loss resulting from the use of this tool. Use it at your own risk.

Available Tools​

Each tool listed below represents a discrete infrastructure operation that can be executed within Hyperstack through the MCP Server. When invoked through natural language, the MCP Server maps the request to the appropriate authenticated Hyperstack API call and returns a structured response to the client.

Billing & Usage​

These tools provide access to account-level billing data, usage analytics, credits, and payment history.

  • get_billing_status – Retrieve the current billing account status.
  • get_billing_usage – Get billing usage with optional filtering by environment or deleted resources.
  • get_previous_day_cost – Retrieve the cost breakdown for the previous day.
  • get_credit_balance – Get the current credit balance for the account.
  • get_payment_history – Retrieve historical payment transactions.

Clusters (Kubernetes)​

These tools manage the lifecycle and operational state of Kubernetes clusters deployed on Hyperstack.

  • create_cluster – Create a new Kubernetes cluster with specified configuration.
  • list_clusters – List all clusters with optional filtering and pagination.
  • get_cluster – Retrieve details for a specific cluster by ID.
  • delete_cluster – Delete an existing cluster (requires confirmation).
  • get_cluster_events – Retrieve events associated with a specific cluster.
  • list_cluster_versions – List all available Kubernetes cluster versions.

Virtual Machines (VMs)​

These tools control the full lifecycle, networking, storage, and operational state of Virtual Machines.

  • create_vm – Create a new virtual machine instance.
  • list_vms – List all VMs with optional filtering and pagination.
  • get_vm – Retrieve detailed information about a specific VM.
  • start_vm – Start a stopped virtual machine.
  • stop_vm – Stop a running virtual machine.
  • delete_vm – Permanently delete a VM and all associated resources.
  • hard_reboot_vm – Perform a hard reboot (forcible restart).
  • hibernate_vm – Hibernate a VM, saving its current state.
  • restore_vm – Restore a hibernated VM.
  • attach_volume_to_vm – Attach one or more storage volumes to a VM.
  • detach_volume_from_vm – Detach one or more storage volumes from a VM.
  • attach_floating_ip_to_vm – Attach a floating IP address to a VM.
  • detach_floating_ip_from_vm – Detach a floating IP address from a VM.
  • add_firewall_rule – Add a firewall rule to control network traffic.
  • remove_firewall_rule – Remove a firewall rule from a VM.
  • get_vm_events – Retrieve events or logs related to a VM.

Storage Volumes​

These tools manage standalone storage volumes and their configuration within a Hyperstack environment.

  • create_volume – Create a new storage volume.
  • list_volumes – List all volumes with optional filtering and pagination.
  • get_volume – Retrieve detailed information about a specific volume.
  • update_volume – Update a volume's configuration (for example, environment assignment).
  • delete_volume – Permanently delete a volume.
  • list_volume_types – Retrieve a list of available volume types.
  • update_volume_attachment – Update volume attachment properties (for example, protection settings).

Infrastructure​

These tools provide access to platform-level metadata, resource catalogs, and environment information.

  • list_flavors – List available VM flavors (instance types) for a specific region.
  • list_environments – List all available environments with optional search and pagination.
  • get_environment – Retrieve detailed information about a specific environment.
  • check_stocks – Check GPU stock availability across all regions.

Basic Usage Examples​

The following examples demonstrate common single-step operations using natural language prompts.

Retrieve Account Information​

These prompts query account-level billing data using get_billing_status and get_credit_balance.

What is my current billing status?

Returns the current billing state of your Hyperstack account, including whether the account is active or requires attention.

How much credit do I have remaining?

Returns the available credit balance associated with the authenticated account.

List Resources​

These prompts retrieve resource inventories using list operations such as list_clusters, list_vms, and list_volumes.

List all clusters

Returns a paginated list of all Kubernetes clusters within the authenticated environment.

Show me all running virtual machines

Returns all Virtual Machines currently in a running state.

List all volumes

Returns all storage volumes associated with the account, including their status and environment.

Create Resources​

These prompts provision new infrastructure resources using creation operations such as create_vm, create_cluster, and create_volume.

Create a virtual machine named demo-vm with n3-A100x1 in CANADA-1

Provisions a new Virtual Machine with the specified flavor and region.

Create a Kubernetes cluster with 2 nodes using n3-A100x1

Deploys a new Kubernetes cluster with the defined node configuration.

Create a 500GB volume in CANADA-1

Creates a new 500GB storage volume in the specified region.

Advanced Usage Workflows​

Advanced workflows involve coordinated, multi-step orchestration across multiple MCP tools, where the output of one operation informs or enables the next.

Provision and Configure a VM​

Create a virtual machine named app-server in CANADA-1 with n3-A100x1
Attach volume vol-123 to VM app-server
Attach floating IP 1.2.3.4 to VM app-server
Add a firewall rule to allow port 443 on VM app-server

This workflow chains together create_vm, attach_volume_to_vm, attach_floating_ip_to_vm, and add_firewall_rule to deliver a production-ready Virtual Machine. It first provisions compute resources in the specified region and flavor, then attaches persistent storage, assigns a publicly routable IP address, and configures network access rules.

Kubernetes Lifecycle Management​

List all cluster versions
Create a Kubernetes cluster with 3 nodes using version 1.36.1
Show events for cluster abc123

This workflow combines list_cluster_versions, create_cluster, and get_cluster_events to manage cluster lifecycle operations. It begins by identifying supported Kubernetes versions, provisions a new cluster with the selected version and node configuration, and then retrieves cluster events to validate provisioning status and diagnose any initialization issues.

Environment-Scoped Billing Analysis​

Show billing usage for the production environment this month
What did I spend yesterday?

This workflow uses get_billing_usage and get_previous_day_cost to perform targeted cost analysis. It filters usage data by environment to isolate production spend and then retrieves the previous day's cost breakdown for short-term financial visibility.

Usage Guidelines​

The following guidelines apply when executing MCP tools for infrastructure management:

  • Confirmation for destructive operations – Always require explicit confirmation before executing destructive actions such as deleting resources, performing hard reboots, or permanently removing volumes.
  • Verify resource identifiers – Do not assume resource IDs or names from previous requests. Always confirm the correct identifier before executing an operation.
  • Pagination awareness – Some list operations return paginated results. Multiple tool calls may be required to retrieve the complete dataset.
  • Required parameters – Ensure all required parameters are gathered and validated before invoking a tool to avoid incomplete or failed operations.
  • Authentication scope – All tools operate within the scope and permissions of the authenticated Hyperstack API key.
  • Response formatting – Tool responses are returned in structured, human-readable format by the MCP client.

Back to top

On this page