Connecting to the API with MCP
Point an AI agent—Cursor, Claude, ChatGPT, or any MCP-compatible client—at the Virtarix HTTP MCP server. Authenticate with the same Bearer personal access token you use for the REST API.
Overview
Traditional MCP servers run as a local subprocess (stdio). Virtarix exposes an HTTP MCP endpoint instead: a fixed HTTPS URL that accepts tool calls over the network. Nothing to install on your machine beyond the AI client itself.
VPS control
List services, power actions, console sessions, OS reinstall, and config changes in plain language.
Orders & catalogue
Browse plans and place API orders against your account’s default tokenized payment method.
Same auth as REST
One Passport PAT. Send Authorization: Bearer … on every MCP request.
Where things live
- MCP endpoint
https://api.virtarix.com/mcp/vps - AuthBearer PAT (same token as REST)
- REST docs/docs (Scalar) · /openapi.yaml
- Token issue
POST /auth/whmcs-tokenfrom the client area flow
Before you start
- A Virtarix client account with access to the client area.
- A personal access token issued via
POST /auth/whmcs-token(see the auth section in REST docs). - An MCP client that supports remote HTTP servers and custom headers (Cursor, Claude Code, Codex, and similar).
Getting your token
Tokens are issued for a logged-in WHMCS client through the Virtarix API auth endpoint. The MCP server validates the same Passport personal access token as the REST API.
- Treat the token like a password—anyone who has it can act as that client.
- Do not commit it to git. Prefer environment variables or your client’s secret store.
- If it leaks, revoke or rotate it and issue a new one from the client area flow.
Full request/response shapes live in the Scalar API reference under authentication.
Cursor IDE setup
Add the Virtarix MCP server to your Cursor MCP config (user or project mcp.json):
User-level: ~/.cursor/mcp.json. Project-level: .cursor/mcp.json in the repo root.
{
"mcpServers": {
"vps-management": {
"url": "https://api.virtarix.com/mcp/vps",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
}
}
}
Replace YOUR_ACCESS_TOKEN with the PAT from your account. Cursor sends the header on every tool call.
Open Cursor Settings → MCP and check that vps-management connects. Then ask in chat, for example: “List my VPS services.”
You: List my VPS services
Agent: calls list-vps → returns your active services
Raw HTTP setup
Scripts and custom clients should POST to the MCP endpoint with JSON and the Bearer header on every request:
POST https://api.virtarix.com/mcp/vps
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
For Claude Desktop / Claude Code and ChatGPT / Codex, see the dedicated guides: Claude · ChatGPT / Codex.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| 401 Unauthorized | Missing or wrong token | Confirm the value and the Bearer prefix in the Authorization header. |
| 403 Forbidden | Token valid but resource not owned | Use a service_id that belongs to the authenticated client. |
| Tool rejects arguments | Unknown keys or payload too large | Send only documented fields; keep args under 64 KiB. |
| Destructive tool fails | confirm missing |
Pass confirm: true for stop, reboot, reinstall, deletes, console, place order, and similar tools. |
| Connection timeout | Wrong URL or network issue | Verify https://api.virtarix.com/mcp/vps and HTTPS connectivity. |
| Tools missing in Cursor | Invalid JSON or wrong config path | Validate mcp.json and reload MCP in Cursor settings. |
Security notes
- Always use HTTPS—never send a Bearer token over plain HTTP.
- Keep tokens out of version control; restrict file permissions on local config when possible.
- Rotate or revoke promptly if you suspect exposure.
- Chat transcripts may retain tool output—avoid asking agents to dump private SSH keys unless necessary.
For how agents should use tools safely day to day, see Using agents with Virtarix MCP.