Skip to content

HOSTKEY MCP Server

In this article

HOSTKEY MCP Server is a bridge between AI clients (Cursor, VS Code, Claude Code, Codex, and other MCP-compatible environments) and your HOSTKEY account on the international portal. Technically, it is an MCP server that runs locally via stdio (or connects remotely) and provides models with over 130 typed tools plus a universal call_api_raw for access to any InvAPI method. The server works with the .com portal and the invapi.hostkey.com endpoint.

Three scenarios where the MCP server saves significant time:

  • Real-time diagnostics: The server is down, and you are unsure if it is a power or network issue. Instead of using the control panel, ask the assistant; it will call get_power_status, get_server_sensors, get_network_status, and provide a summary.
  • Routine operations: Rebooting, reinstalling the OS, updating DNS—all via chat.
  • Resource ordering: Selecting a preset, checking availability, performing a dry-run with cost calculation—and only then placing a real order.

Note

For the international portal .com, there is a separate MCP hostkey-mcp-server.

Architecture

MCP (Model Context Protocol) is a standard that describes how an AI model can call external tools. In the case of the HOSTKEY MCP Server:

  1. You configure an MCP client (Cursor, VS Code, etc.), specifying the server launch command and your API key.
  2. The client launches the server locally (or connects to a remote endpoint).
  3. When you ask the assistant to do something with servers, the model selects the appropriate tool from the 132 available.
  4. The server calls the corresponding InvAPI method, receives the response, and returns it to the model.
  5. The model formulates the answer to you.

Attention

All write operations require explicit confirmation. By default, confirm=true is not passed, and the server will not change anything.

The server provides three built-in prompts—pre-set scenarios that guide the model on the right path. However, even without them, you can simply type commands in natural language: "show my servers," "order a VPS in NL."

How to connect the MCP server to environments

Cursor

In .cursor/mcp.json:

{
  "mcpServers": {
    "hostkey-mcp-server": {
      "command": "npx",
      "args": ["-y", "hostkey-mcp-server"],
      "env": {
        "HOSTKEY_API_KEY": "your-key"
      }
    }
  }
}

Or click the Install in Cursor button in the package README, enter your key, and confirm.

VS Code

In .vscode/mcp.json:

{
  "servers": {
    "hostkey-mcp-server": {
      "command": "npx",
      "args": ["-y", "hostkey-mcp-server"],
      "env": {
        "HOSTKEY_API_KEY": "your-key"
      }
    }
  }
}

OpenCode

In .config/opencode/opencode.jsonc

{
  "mcp": {
    "hostkey": {
      "type": "local",
      "command": ["npx", "-y", "hostkey-mcp-server"],
      "environment": {
        "HOSTKEY_API_KEY": "your-key"
      },
      "enabled": true
    }
  }
}

Mimo Code

In .config/mimocode/mimocode.jsonc

{
  "$schema": "https://mimo.xiaomi.com/mimocode/config.json",
  "mcp": {
    "hostkey": {
      "type": "local",
      "command": ["npx", "-y", "hostkey-mcp-server"],
      "environment": {
        "HOSTKEY_API_KEY": "your-key"
      },
      "enabled": true
    }
  },
  "provider": {
    // ... your existing provider
  }
}

OpenCode Remote Mode

In .config/opencode/opencode.jsonc

{
  "mcp": {
    "hostkey": {
      "type": "remote",
      "url": "https://mcp.hostkey.com/mcp",
      "headers": {
        "Authorization": "Bearer your-key"
      },
      "enabled": true
    }
  }
}

Mimo Code Remote Mode

In .config/mimocode/mimocode.jsonc

{
  "$schema": "https://mimo.xiaomi.com/mimocode/config.json",
  "mcp": {
    "hostkey": {
      "type": "remote",
      "url": "https://mcp.hostkey.com/mcp",
      "headers": {
        "Authorization": "Bearer your-key"
      },
      "enabled": true
    }
  }
}

Remote Mode (for cloud agents)

If local Node/npx is unavailable:

{
  "mcpServers": {
    "hostkey": {
      "url": "https://mcp.hostkey.com/mcp",
      "headers": {
        "Authorization": "Bearer your-key"
      }
    }
  }
}

End-to-End Scenarios

Scenario 1: "Server is not responding, fix it"

You write to the assistant: "Server 12345 is not pinging, check what's wrong with it."

The model (using troubleshoot_server_prompt or independently):

  1. get_server (12345) — retrieves the card, hostname, and IP.
  2. get_power_status (12345) — sees that the power is okay.
  3. get_network_status (12345) — checks the port status and sees that the port is disabled.
  4. Reports: "The server is running, but the network port is disabled. Enable it?" — suggests port_on.
  5. After confirmation — port_on with confirm=true, then checks connectivity.

Scenario 2: "Order a VPS in the Netherlands for PostgreSQL"

You write: "I need a VPS in NL, I'm going to install PostgreSQL."

The model (using order_server_prompt):

  1. list_presets (NL) → shows 3 options with prices.
  2. You select one.
  3. list_os → shows Ubuntu 22.04, Debian 12, etc.
  4. You select one.
  5. list_traffic_plans → you select the traffic plan.
  6. Gathers root password, hostname, and billing period.
  7. order_server with dry_run=true → shows a summary: "VPS vm.small, Ubuntu 22.04, NL, 10 TB traffic, €XX/month. Confirm?"
  8. You confirm.
  9. order_server with dry_run=false, confirm=true → returns a callback key.
  10. Model: "Order created, deployment takes 10–30 minutes. I will check the status via check_task."

Scenario 3: "Reinstall OS on server 67890 to Ubuntu 24.04"

You enter the command.

The model (using reinstall_server_prompt):

  1. get_server (67890) → shows the hostname.
  2. Warns: "All data on the disks will be deleted. Confirm?"
  3. You confirm.
  4. list_os (67890) → you select Ubuntu 24.04.
  5. Gathers a new root password.
  6. reinstall_server with confirm=true and the current hostname (additional protection).
  7. If HOSTKEY_ALLOW_DESTRUCTIVE=1 is not set — explains how to enable it.
  8. Saves the callback and tracks progress via check_task.

Scenario 4: "Add a DNS record for www.example.com"

You write: "Set up an A record for www.example.com → 10.56.121.5 in the example.com zone."

The model:

  1. list_dns_domains → checks if the example.com zone exists.
  2. If not — add_dns_domain (name: example.com, confirm=true).
  3. add_dns_record (zone: example.com, name: www, type: A, content: 10.56.121.5, confirm=true, ttl=3600).
  4. Confirms success.

For SRV records, the model will additionally fill in proto, priority, weight, port, and target. In case of an SOA error — mname/rname.

Prompts: Ready-to-use Scenarios

Prompts are pre-set instructions that guide the model along a verified path. They eliminate the need to remember the order of calls and parameters.

order_server_prompt

Purpose: To guide the user through the server ordering process step by step.

How it works: The prompt instructs the model to:

  1. Clarify the location (if not specified).
  2. Call list_presets, suggest 2–3 options with prices via get_preset_pricing, and wait for a selection.
  3. Call list_os for the selected preset and suggest options.
  4. Optionally call list_software for marketplace applications.
  5. Call list_traffic_plans to select traffic.
  6. Collect the root password (min. 8 characters, uppercase, digit, special character, no @/#) or SSH key, hostname, and billing period.
  7. Mandatory: Execute order_server with dry_run=true and show a summary with the total cost.
  8. Only after explicit user consent — dry_run=false + confirm=true.
  9. Save the callback key, inform about the deployment time (10–30 minutes), and suggest check_task.

Arguments: location (optional), purpose (optional).

reinstall_server_prompt

Purpose: OS reinstallation with safety checks.

How it works:

  1. Determine the server ID (via get_servers if not specified).
  2. Call get_server and get_power_status to show the current state.
  3. Explicitly warn: Reinstallation will delete ALL data on the disks.
  4. list_os for the server, select os_id. Optionally list_software.
  5. Collect a new root password or SSH key, and deploy_notify.
  6. reinstall_server with confirm=true and the current hostname. If the tool responds that destructive operations are disabled, explain how to set HOSTKEY_ALLOW_DESTRUCTIVE=1.
  7. Save the callback key and track via check_task until result="OK". Do not start a second reinstallation while the current one is in progress.
  8. Remind the user: the root password is new; an email notification might not be sent with this method.

Arguments: server_id (optional).

troubleshoot_server_prompt

Purpose: Problem diagnostics.

How it works:

  1. Determine the server ID (via get_servers, can filter by IP or tags).
  2. Gather the full picture: get_server (card), get_power_status, and for bare-metal — get_server_sensors.
  3. Analysis:
  4. Server is powered off → suggest power_on (with confirm=true, only with consent).
  5. Sensor anomalies (overheating, PSU failure) → recommend Support / Remote Hands.
  6. Formulate a summary: status, likely cause, and recommended actions. Destructive actions (power_off, reboot, reinstall) are only performed after explicit consent.

Arguments: server_id (optional).

Tools

All tools are grouped by functional areas. Below are the key groups with examples of specific calls.

Servers and Status

  • get_servers — a list of your servers with filtering by IP, hostname, location, and tags. This is the starting point for most scenarios.
  • get_server — detailed server card: configuration, OS, IP addresses, interfaces, IPMI. Returns everything needed to understand the status.
  • get_power_status — power status. If the server is off, the next step is power_on (with confirmation).
  • get_server_sensors — for bare-metal servers: temperatures, voltages, fan status. Critical for diagnosing overheating or PSU failure.
  • search_servers_by_tag — search by custom tags. If you tag servers as "production", "staging", or "gpu", this is a fast way to filter the ones you need.

Catalog and Resource Selection

  • list_presets — a list of available instant servers (VM/BM/GPU/vGPU) with prices in the specified location. Does not require a token — you can browse the catalog before ordering.
  • search_presets — search for available servers matching a specific preset by name (e.g., vm.pico). Requires authorization.
  • get_preset_pricing — prices for presets in different currencies. Required for an accurate dry-run order.
  • list_os — a list of operating systems available for installation. Without an instance_id, it returns all OS options for all presets.
  • list_software — marketplace applications available for auto-installation (panels, databases, tools).
  • list_traffic_plans — traffic plans for a preset in a specific location.

Power and Management

  • power_on / power_off — turning the server on or off. Requires confirm=true.
  • reboot_server — rebooting. For servers in standby, IPMI may be required.
  • power_cycle — a hard power cycle (turn off and turn on). Useful when a standard reboot does not work.

Server Ordering

  • order_server — the key ordering tool. Works in two modes:
  • dry_run=true (default): checks preset and OS availability, returns a summary with an estimated cost. No money is charged.
  • dry_run=false + confirm=true: a real order. Charges the balance or issues an invoice.

Parameters: preset, os_id, location_name (NL/US/FI/DE/IS/TR/UK/ES/IT/PL/CH), root_pass (min. 8 characters, uppercase, digit, special character, no @ or #), traffic_plan, deploy_period (monthly/quarterly/semi-annually/annually), and optionally soft_id, ssh_key, hostname, promocode, deploy_notify.

Deployment takes 10–30 minutes. Status is checked via check_task using the callback key from the response.

OS Reinstallation and PXE

  • reinstall_server — a destructive operation: all data on the disks will be deleted. Requires HOSTKEY_ALLOW_DESTRUCTIVE=1 in the environment, confirm=true, and re-entering the server's current hostname. This is an extra layer of protection against accidental execution.

PXE reinstallation sequence (for servers without remote management):

  1. create_reinstall_task — creates a master key and returns a reinstall_key.
  2. create_pxe_config — creates the PXE configuration.
  3. set_boot_device (pxe) — sets the boot device to network.
  4. OS installation occurs automatically.
  5. set_boot_device (disk) — sets the boot device back to the disk.
  6. clear_pxe_config — mandatory after completion, otherwise a sudden reinstallation might occur during the next reboot.

The tool is also available as a standard reinstall_server for typical cases.

Network and DNS

  • get_network_status — status of network interfaces: port, switch, VLAN, speed, MAC, and connection status.
  • get_port_graphs — port usage graphs for day/month/year.
  • port_on / port_off — enabling/disabling a network port. Disabling means loss of connectivity on this interface.
  • block_ip / unblock_ip — blocking an IP at the HOSTKEY network level. Useful for abuse reports.
  • get_ptr_record / update_ptr_record — managing reverse DNS. Multiple records are passed using %0A as a delimiter.

DNS Tools (require pdns/edit permissions):

  • add_dns_domain — create a DNS zone and add a domain. Parameters: name (e.g., example.com), confirm=true.
  • add_dns_record — add or change a record. Supports A, AAAA, CNAME, MX, TXT, SRV. For SRV records, proto, priority, weight, port, and target must be filled. The mname/rname fields are marked as mandatory for SOA checks — fill them in case of an error.
  • list_dns_domains — a list of all DNS zones in the account.
  • add_dns_subdomain — add a subdomain linked to a server.

Snapshots, ISO, S3

  • create_snapshot — create a VM snapshot. This is an asynchronous operation; check status via check_task.
  • remove_snapshot — delete a snapshot.
  • ISO Tools: list_iso_images, get_uploaded_isos, add_iso (add/update an image), mount_iso (mount, asynchronous, returns a callback), unmount_iso.
  • S3: management of buckets and objects (detailed documentation in tools/list).

IPMI and Console

  • get_ipmi — IPMI interface IP address and model.
  • add_ipmi_user — create a temporary IPMI user for web access.
  • reset_ipmi — restart the IPMI module. Use this if IPMI is not responding.
  • get_console / start_novnc — access to the server's VNC/HTML5 console.

Remote Hands

Tools for submitting tickets to the on-site shift—used when physical intervention is required:

  • request_rh_power_on — manually turn on the server.
  • request_rh_power_off — manually turn off the server.
  • request_rh_reboot — reboot the server.
  • request_rh_pxe_boot — boot via PXE (required for reinstallation without remote management).
  • request_rh_kvm — connect IP KVM.
  • request_rh_check — check the server and boot into the OS.

Billing and API Keys

  • get_account_info — information about the current API token and account: available calls, account type, server IDs. This is the first tool to use to verify your connection.
  • list_api_keys, create_api_key, update_api_key, delete_api_key — key management. When creating a key, the value is shown only once — make sure to save it.

Utilities

  • check_task — check the status of a long-running operation using a callback key. Returns the execution stage and result="OK" upon success.
  • call_api_raw — direct call to any InvAPI method when a typed tool is not available. Always requires confirm=true; for destructive/paid actions, HOSTKEY_ALLOW_DESTRUCTIVE=1 is also required.

MCP Security

The HOSTKEY MCP server implements multi-level protection against accidental destructive actions:

  • Level 1: confirm=true. All write calls require the explicit passing of confirm=true. Without it, the server changes nothing. According to instructions, the model must obtain user consent before passing confirm=true.
  • Level 2: dry_run for orders. order_server works in verification mode by default—it only shows availability and cost without charging money.
  • Level 3: HOSTKEY_ALLOW_DESTRUCTIVE=1. For OS reinstallation, PXE, and service cancellation, this environment variable must be explicitly set. Without it, the server will refuse the request.
  • Level 4: hostname re-entry for reinstallation. reinstall_server requires not only confirm=true but also re-entering the server's current hostname. This protects against accidentally selecting the wrong server.
  • Level 5: secret masking. Passwords and tokens are masked in responses.

Troubleshooting

  • "Server cannot connect" — verify that your API key is valid. Call get_account_info — if it returns data, the connection is working.
  • "DNS record rejected" — ensure your API key has pdns/edit permissions.
  • "Destructive operation blocked" — set HOSTKEY_ALLOW_DESTRUCTIVE=1 in the MCP server environment (in the env configuration or in .env when building from source).
  • "Long-running operation does not complete" — use check_task with the the callback key. Typical deployment time is 10–30 minutes. Do not start a duplicate operation while one is currently running.
  • "Tool cannot find server" — verify the server ID via get_servers. The ID is numeric; do not confuse it with the hostname.

Information

Useful links:

Note

This documentation covers the main scenarios and tools. A full list of 132 tools with parameters is available via tools/list in your MCP client.

question_mark
Is there anything I can help you with?
question_mark
AI Assistant ×