The panel has a Model Context Protocol (MCP) server, so AI agents such as Claude Code, Claude Desktop or Cursor can list, power and manage servers through it. It uses the panel's ordinary API keys; there is no separate MCP credential. Every key starts with MCP off and allows no tools until its holder ticks them.
How it works#
- Endpoint:
https://panel.example.com/api/mcp, Streamable HTTP. EachPOSTcarries one JSON-RPC message and gets one JSON answer. There is no session:GETandDELETEanswer 405. - Authentication: the API key in
Authorization: Bearer vmk_…, checked exactly as for the API: unknown, revoked or expired keys, allowed addresses, suspended accounts and maintenance mode are all refused in the same way. A request with anOriginheader other than the panel's own is refused. - Each tool is one API operation. A tool call goes through the same checks as an API request: the key's scope, the administrator's staff role, the rate limits,
Idempotency-Key, and the same refusals. Each call is its own row in the API log, beside the row of the MCP request. Audit entries say"via": "mcp". - Rate limits: a tool call counts against its operation's bucket (general, plus expensive or passwords where the operation has one). Every other MCP message counts once in the key's general bucket.
- Errors: when the API refuses a call (404, 422, a missing scope), the tool result has
isError: trueand the problem details as its text, so the agent can correct itself.
Supported protocol versions: 2026-07-28, and the initialize-based versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. Methods: server/discover, initialize, ping, tools/list and tools/call.
Turning it on#
The MCP server is on for the panel by default, but no key can use it until tools are allowed for that key.
To switch it off for the whole panel: go to System › Settings, open the API tab and untick AI agents may connect to the MCP server. While it is off every MCP request is refused, and keys keep the tools they had.
To allow tools for a key:
- Create a key, or pick an existing one, under Settings › API keys (user menu). Give it the scopes the tools need, and allowed addresses for the machine the agent runs on.
- Click MCP tools on the key's row. The panel asks for your password again.
- In each group, tick the tools to allow, or use Allow all it can use. A tool the key cannot use shows why, for example "Needs the scope servers:power.", and its box is disabled.
- For destructive tools, tick the extra confirmation (I understand that an AI agent with this key can delete servers, backups and snapshots and reinstall servers).
- For password tools, also switch on Let this key's tools return passwords. The key needs the scope
servers:secretstoo. - Click Save tools.
The API keys list then shows how many tools each key allows, or "MCP: off". There is no API for changing a key's MCP tools: a leaked key cannot widen itself.
Connecting a client#
The Connect section of the MCP tools page shows the address with Copy address and the exact command for Claude Code:
claude mcp add --transport http vmstack https://panel.example.com/api/mcp \
--header "Authorization: Bearer YOUR_API_KEY"
YOUR_API_KEY is the whole key (vmk_…), as shown once when it was created.
Clients that take a JSON configuration (Claude Desktop through mcp-remote, Cursor, VS Code and others) are given the same URL and header. Claude.ai custom connectors need OAuth, which the MCP server does not offer yet.
To check the connection, run /mcp in Claude Code: it lists the tools the key allows and can use. Then ask for something read-only, such as listing your servers, and check the key's requests under Settings › API keys.
Tools#
62 tools in five groups. tools/list only shows the tools the key allows and can use with its scopes and staff role. Tools for nodes, accounts and the audit log are listed for every key but only work for levels that are offered their scope.
| Group | What it covers | Tools |
|---|---|---|
| Read only | Lists and shows; changes nothing | get_account, search, list_servers, get_server, get_server_activity, get_server_guest_facts, get_server_system_log, list_server_addresses, list_server_tasks, list_tasks, get_task, list_server_snapshots, list_server_backups, get_backup, get_server_backup_status, get_server_firewall, list_firewall_templates, list_server_disks, get_server_usage, get_server_traffic, list_traffic, list_plans, list_locations, list_images, list_isos, list_applications, list_ssh_keys, list_private_networks, list_nodes, get_node, list_users, get_user, list_audit_events |
| Power | Start, shut down, reboot and power off servers | start_server, shutdown_server, reboot_server, power_off_server |
| Changes | Nothing is lost | create_server, rename_server, reset_server_password, start_rescue, end_rescue, take_snapshot, create_backup, add_firewall_rule, update_server_firewall, apply_firewall_template, set_rdns, cancel_task, suspend_server, unsuspend_server, suspend_user, unsuspend_user |
| Destructive | Data is lost | reinstall_server, delete_server, restore_backup, delete_backup, revert_snapshot, delete_snapshot, delete_firewall_rule |
| Passwords | Returns secrets | get_root_password, get_server_application |
Arguments#
A tool's arguments come from its API operation:
- path parameters, named after the resource: the
{id}of/servers/{id}isserver_id; - query parameters without brackets:
filter[status]becomesfilter_status; - the fields of the request body;
idempotency_keywhere the operation takes anIdempotency-Keyheader.
Unknown or missing required arguments are refused before any request is made. Long operations (create, reinstall) return a task; the agent follows it with get_task.
Destructive and password tools#
- Destructive tools say
DESTRUCTIVEat the start of their description and require the argumentconfirm: true. Without it, nothing is sent and the agent is told to ask the user first. MCP clients normally show such a call to you for approval. get_root_password,get_server_application, andreturn_passwordon create and reinstall, need the key's passwords allowance as well asservers:secrets. Without the allowance the two tools are hidden andreturn_passwordis not accepted. Passwords that reach an agent are part of its conversation, so allow this only when you need it.
Recommendations#
- Use a separate key for each agent, with allowed addresses and only the scopes and tools it needs. Start with Read only and Power.
- Keep destructive tools off unless you need them, and never allow them on a key that an unattended agent uses.
- To see what an agent did, filter the API log by the key, or the audit log for entries with
via: mcp.
Not supported yet#
- Server-sent events and progress notifications for long calls; tasks are polled with
get_task. - Output schemas for tools.
- OAuth, which claude.ai custom connectors require.