VergeOS

You run a Model Context Protocol (MCP) server to let AI assistants manage VergeOS resources—VMs, networks, tenants, and cluster health—via natural language. This server exposes both local (stdio) and remote (HTTP) interfaces so you can connect from onboard devices or from distant clients.

How to use

You connect an MCP client to either a local stdio server on the same machine as VergeOS or to a remote HTTP server deployed in a Kubernetes cluster. Once connected, you can ask your AI assistant to list VMs, power on or off machines, inspect cluster status, manage networks and tenants, view logs and alarms, and perform common snapshot and configuration tasks. Use the local option when your client can reach VergeOS directly. Use the remote option when your client is on a different machine or network but you have an accessible HTTP endpoint.

Common workflows include listing all VMs, inspecting a VM’s details, powering a VM on or off, resizing VM resources, creating or restoring snapshots, listing networks and tenants, and querying cluster health. The MCP server exposes a REST-based and an MCP-protocol interface to support both direct tool invocation from your AI assistant and traditional HTTP requests.

How to install

Prerequisites: you need Node.js and npm to run the local MCP server. You may also use a Kubernetes cluster if you choose the remote deployment path.

Option A: Local Installation (stdio) practical steps are below.

1. Install Node.js and npm on your machine if they are not already installed.

2. Clone the server repository and install dependencies.

3. Run the local MCP server with your VergeOS credentials set via environment variables or a token.

Option B: Remote Installation (Kubernetes + Local Proxy) practical steps are below.

1. Set up a Kubernetes cluster and access to it. 2) Deploy the MCP server to Kubernetes using the provided deployment script. 3) Expose the service via an Ingress and set up a DNS record for external access. 4) Install a local proxy on your workstation to bridge Windsurf or Claude to the remote MCP server.

The following concrete commands illustrate the local installation path. Run them on the machine that will host VergeOS and connect to VergeOS directly.

# 1) Install dependencies
git clone <repo-url> vergeos-mcp-server
cd vergeos-mcp-server
npm install

# 2) Create a .env file or set environment variables
# Example with password-based auth
export VERGEOS_HOST=your-vergeos-host
export VERGEOS_USER=admin
export VERGEOS_PASS=your-password

# Example with token (preferred)
# export VERGEOS_HOST=your-vergeos-host
# export VERGEOS_TOKEN=your-token-here

# 3) Run the stdio MCP server
node src/index.js

Additional configuration and deployment notes

There are two deployment modes you can choose from. Local stdio runs on the same machine as VergeOS and connects directly. Remote HTTP runs behind a proxy in Kubernetes, exposing an HTTP API that your MCP clients can reach.

Security and authentication rely on VergeOS tokens or user/password management. Prefer token-based authentication for long-running deployments and consider TLS termination at a reverse proxy.

Environment variable options used in the local setup include VERGEOS_HOST, VERGEOS_USER, VERGEOS_PASS, and optionally VERGEOS_TOKEN as an alternative authentication method.

Security considerations

Use TLS for all HTTP access and protect credentials with environment variables or orchestration secrets. Limit access to the MCP server with network policies and, where possible, rotate tokens regularly.

Troubleshooting

If you cannot reach VergeOS from the MCP server, verify network routing and DNS configuration. Check token validity if you use token-based auth, and ensure the VergeOS API endpoint is reachable.

For local proxies, verify that the proxy process can reach the HTTP MCP server endpoint and that Windsurf or Claude is configured to route through the proxy.

Notes on usage patterns

The MCP server supports both a REST API for direct HTTP calls and an MCP protocol for integration with AI assistants. Use the HTTP path to directly query VergeOS resources or rely on your MCP client to issue tool-style commands that map to VergeOS actions.

Available tools

list_vms

List all virtual machines, with optional filters for running state or name

get_vm

Get detailed information for a VM by its ID

power_on_vm

Power on a VM by ID

power_off_vm

Gracefully power off a VM with optional wait and auto-force settings

force_off_vm

Force power off a VM (hard shutdown)

reset_vm

Reset or reboot a VM

modify_vm

Change CPU cores and/or RAM for a VM, handling running VMs as needed

add_drive

Add a new disk drive to a VM

resize_drive

Expand an existing disk drive (increase only)

get_vm_nics

Get VM network interfaces

get_vm_drives

Get VM disk drives with sizes

list_networks

List all virtual networks

get_network

Get details for a specific network

network_action

Power on/off, reset, or apply rules to a network

list_tenants

List all tenants

get_tenant

Get details for a tenant

tenant_action

Power on/off or reset a tenant

list_nodes

List cluster nodes

get_node_stats

Get node statistics

get_cluster_status

Get cluster health status

get_cluster_stats

Get storage tier statistics

list_volumes

List storage volumes

get_logs

Get system logs with optional filtering by level or object type

get_alarms

Get active system alarms

list_vm_snapshots

List snapshots for a VM

create_vm_snapshot

Create a VM snapshot with optional expiration and quiesce

delete_vm_snapshot

Delete a VM snapshot

restore_vm_snapshot

Restore a VM from a snapshot