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 endpointhttps://api.virtarix.com/mcp/vps
  • AuthBearer PAT (same token as REST)
  • REST docs/docs (Scalar) · /openapi.yaml
  • Token issuePOST /auth/whmcs-token from 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).
OAuth connectors: Virtarix MCP is Bearer-only for now. Clients that require an OAuth authorization code flow against a separate MCP URL are not supported yet—use Access Token / Bearer configuration instead.

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):

1
Create or edit the config file

User-level: ~/.cursor/mcp.json. Project-level: .cursor/mcp.json in the repo root.

2
Register the HTTP server
mcp.json
{
  "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.

3
Confirm tools load

Open Cursor Settings → MCP and check that vps-management connects. Then ask in chat, for example: “List my VPS services.”

Example

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:

Request shape
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.
Security reminder: Virtarix support will never ask you for your access token. Generate a new one yourself if you need to rotate credentials.

For how agents should use tools safely day to day, see Using agents with Virtarix MCP.