Using agents with Virtarix MCP

How to get useful results from an AI agent against Virtarix: what to ask, which safety gates apply, and when MCP is a better fit than calling the REST API yourself.

What you can ask

Describe the outcome in plain language. The agent maps that to MCP tools:

  • Who am I authenticated as, and which services do I own?
  • List VPS services with hostnames and IP addresses.
  • Show details for service_id 9105 (password is redacted over MCP).
  • Start / stop / reboot / shutdown a VM after I confirm.
  • Open a short-lived noVNC console URL.
  • List OS templates or ISOs; reinstall or mount an ISO with confirmation.
  • Inspect or update VM config and firewall rules.
  • Manage backups, backup jobs, snapshots, power tasks, and notifications.
  • Read public SSH keys; only fetch the private key when you explicitly need it.
  • Browse the product catalogue and place an order (tokenized payment method required).

Tool groups (high level)

Group Examples
Account & orders get-me, list-catalogue, place-order
Inventory list-vps, get-service-details
Power start-vm, stop-vm, reboot-vm, shutdown-vm
OS & media list-templates, list-isos, reinstall-os, mount-iso
Config & firewall get-vm-config, update-vm-config, firewall list/create/update/move/delete
Backup & snapshot Backups, backup jobs, snapshots, rollback/restore
Access create-console-session, SSH public/private key tools

Request bodies mirror the REST API. Full field schemas live in /docs.

Safety gates

  • confirm: true — required on destructive or sensitive tools (power changes, reinstall, restore/delete, mount ISO, config/firewall writes, console, place order, private SSH key, and similar).
  • Password redaction — get-service-details does not return the VPS password over MCP (REST may still expose it).
  • Unknown arguments rejected — extra keys are not silently ignored.
  • 64 KiB argument cap — oversized tool payloads are rejected.
  • Ownership — tools only operate on services owned by the authenticated client.
Agent tip: Prefer read-only tools (list-vps, get-service-details, catalogue/firewall list) before mutating. Ask the human before setting confirm: true.

MCP vs REST

Two ways to reach the same capabilities:

Use case Prefer
Conversational one-off tasks in an IDE or chat MCP
Sandboxed agents without shell access MCP
CI pipelines, scripts, backend integrations REST (/docs)
Tight control over every request/response byte REST
Teams new to the API who want structured tools MCP

MCP tools call the same application services as the REST controllers—there is no HTTP loopback. The trade-off: tool responses can be large and land fully in the model context. REST lets you filter and shape responses in your own code.

MCP flow — order a VPS

You: Create a Johannesburg Linux S VPS with Ubuntu, hostname app1.example

Agent: list-catalogue → resolves plan → confirms with you → place-order with confirm: true

Tips to keep agent context lean

  • Pass known service_id values instead of listing everything every turn.
  • Ask for specific fields (“hostname and IP only”) so the agent summarizes instead of dumping raw JSON.
  • Batch related instructions in one message when it makes sense.
  • Document fixed plan IDs in your project notes if you order the same SKU often.

Security

  • HTTPS only; Bearer PAT on every request.
  • Treat chat logs as untrusted storage for secrets.
  • Rotate tokens via the client area auth flow if compromised.

Setup guides: Cursor & overview · Claude · ChatGPT / Codex