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_id9105 (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-detailsdoes 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.
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.
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_idvalues 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