Hostodo MCP Server

Connect AI clients like Claude Desktop, Cursor, and other MCP-compatible tools directly to your Hostodo VPS infrastructure. Manage VMs, run commands, transfer files, and more — all from your AI assistant.

# 1. Create a token in OdoPanel Settings > Developer Access

# 2. Add to your MCP client config:
https://api.hostodo.com/mcp
Authorization: Bearer <your-token>

# 3. Ask your AI client to list your VMs
"List my Hostodo VMs"

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants interact with external tools and data sources. Hostodo's MCP server exposes your VPS infrastructure as tools that AI clients can call — no SSH credentials to paste, no API wrappers to build.

Every MCP tool call is authenticated against your Hostodo account with scoped tokens, checked for VM ownership, audited, and rate-limited. You stay in control of what your AI assistant can and cannot do.

How It Works

The Hostodo MCP server runs inside OdoPanel's Django backend as an authenticated ASGI endpoint. Here's the flow:

1. Create a developer token in OdoPanel Settings → Developer Access with the scopes you need.
2. Configure your MCP client (Claude Desktop, Cursor, etc.) with the endpoint URL and bearer token.
3. The MCP client discovers available tools automatically after authenticating.
4. Ask your AI assistant to manage VMs, run commands, or transfer files.
5. Every call is authorized against your token scopes, VM ownership, account state, exec opt-in, and global kill switches before anything happens.

Three-Layer Security

For command execution, three independent gates must all pass:

• Token scope — the token must include vms:exec
• Per-VM opt-in — the VM must have MCP exec enabled
• Global kill switch — MCP exec must not be globally disabled by staff

Create a Developer Token

To connect an MCP client, you need a developer token with the right scopes.

1. Log in to OdoPanel.
2. Go to Settings → Developer Access.
3. Click Create Token.
4. Enter a name (e.g., claude-desktop or cursor).
5. Select the scopes you need:
   • vms:read — list and inspect VMs
   • vms:power — start, stop, reboot, reset, reinstall, rename
   • vms:exec — run commands, transfer files, manage async commands
   • account:read — read account metadata
6. Copy the token immediately. It is shown only once and never stored in plaintext.

Claude Desktop Setup

Add the Hostodo MCP server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Copy{
  "mcpServers": {
    "hostodo": {
      "url": "https://api.hostodo.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Restart Claude Desktop. Your Hostodo VMs will appear as available tools.

Cursor Setup

In Cursor, go to Settings → MCP and add a new MCP server:

Copy{
  "mcpServers": {
    "hostodo": {
      "url": "https://api.hostodo.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Hermes Agent

If you use Hermes Agent (Nous Research's CLI agent), add the Hostodo MCP server with:

Copyhermes mcp add hostodo --url https://api.hostodo.com/mcp --auth header

Hermes will prompt you for the bearer token on first use. Verify it's connected:

Copyhermes mcp list

Then in any Hermes session, your Hostodo VM tools are available:

Claude Code (CLI)

If you use Claude Code (Anthropic's CLI coding agent), you can add the Hostodo MCP server with a single command:

Copyclaude mcp add --transport http --header "Authorization: Bearer <your-token>" hostodo https://api.hostodo.com/mcp

Verify it's connected:

Copyclaude mcp list

Then in any Claude Code session, your Hostodo VM tools are available:

Generic MCP HTTP Client

The Hostodo MCP server uses the Streamable HTTP transport at https://api.hostodo.com/mcp. Any MCP-compatible client that supports bearer token authentication can connect.

Required headers:

Send a JSON-RPC initialize request to discover available tools:

Copycurl -X POST https://api.hostodo.com/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Listing VMs

Ask your AI client to list your VMs. The hostodo_list_vms tool returns only VMs you own.

Required scope: vms:read

Output includes id, hostname, status, location, plan, primary_ipv4, primary_ipv6, mcp_exec_enabled, power_state, and power_controls_supported.

VM Details

The hostodo_get_vm tool returns detailed metadata for a single VM after ownership verification. Accepts VM ID, exact hostname, or unique prefix.

Required scope: vms:read

Power Control

The hostodo_power_vm tool supports start, shutdown, reboot, stop, and reset.

Required scope: vms:power

Running Commands on a VM

The hostodo_exec_vm_command tool runs a command as root inside the VM via the QEMU guest agent. This is a synchronous, bounded execution — use it for quick commands (under 60 seconds).

Required scope: vms:exec

Required VM setting: MCP exec must be enabled on the target VM.

Output includes exit code, stdout, stderr (capped at 64 KiB each), truncation flags, timeout flag, and duration.

Enabling MCP Exec on a VM

Command execution is disabled by default on every VM. To enable it, use the hostodo_set_vm_exec_enabled tool or toggle it from the OdoPanel VM detail page.

Required scope: vms:exec

Enabling requires an exact confirmation phrase containing the VM's instance ID:

Copy# Enable
{ "vm_id": "ins::abc123", "enabled": true, "confirmation": "ENABLE MCP EXEC ins::abc123" }

# Disable
{ "vm_id": "ins::abc123", "enabled": false, "confirmation": "DISABLE MCP EXEC ins::abc123" }

Reinstalling a VM

The hostodo_reinstall_vm tool reimages a VM from a template. This is destructive and requires a confirmation phrase.

Required scope: vms:power

Renaming a VM

The hostodo_rename_vm tool changes a VM's hostname. Requires a confirmation phrase containing the VM ID.

Required scope: vms:power

Transferring Files to a VM

The Hostodo MCP server supports object-storage-backed file transfer. Instead of streaming file bytes through the MCP protocol, the server creates short-lived presigned S3 upload URLs. The client uploads directly to storage, then asks the server to install the file on the VM.

This works with private repos, CI artifacts, config files, and scripts — no source code is exposed to the MCP server.

Required scope: vms:exec (file install is treated as root VM modification)

Step 1: Create an upload slot

Compute the file size and SHA-256 locally, then call hostodo_create_artifact_upload:

Copy# Compute metadata locally
FILE=./nginx.conf
SIZE=$(wc -c < "$FILE" | tr -d ' ')
SHA=$(shasum -a 256 "$FILE" | awk '{print $1}')

Purpose limits:

Step 2: Upload to the presigned URL

Copycurl -X PUT \
  -H "Content-Type: application/octet-stream" \
  --upload-file ./nginx.conf \
  "$UPLOAD_URL"

Installing a File on a VM

After uploading, call hostodo_install_artifact to install the file on the VM. The server generates a short-lived download URL, the VM downloads it, verifies SHA-256, creates parent directories, sets owner/mode, and atomically moves it into place.

Required scope: vms:exec

After install, run any follow-up commands separately using hostodo_exec_vm_command or async command tools.

Async Command Runs

For long-running commands (builds, package installs, migrations, log watching), use the async command tools instead of hostodo_exec_vm_command. These start a command in the background and return a command_id for polling.

Required scope: vms:exec

The AI client will:

1. Call hostodo_start_vm_command to launch the command
2. Call hostodo_get_vm_command_output periodically to check status and tail output
3. Optionally call hostodo_read_vm_command_logs for incremental log reads by byte offset
4. Call hostodo_cancel_vm_command if you need to stop it

Polling Command Output

hostodo_get_vm_command_output returns the current status, exit code (if finished), duration, and bounded stdout/stderr tails. This is the ergonomic polling tool for agents.

Statuses: queued, running, succeeded, failed, timed_out, cancelled, unknown

Reading Logs Incrementally

hostodo_read_vm_command_logs reads stdout/stderr chunks by byte offset. Each response includes next_stdout_offset and next_stderr_offset for the next read. This avoids re-receiving the same tail output on every poll.

Cancelling a Command

hostodo_cancel_vm_command kills a running command and marks it as cancelled.

Token Scopes

Developer tokens have selectable scopes. Only grant what your AI client needs.

Tokens expire after 90 days of inactivity. Revoking a token takes effect immediately — the next MCP request using it will fail authentication.

Audit Logs

Every MCP tool call that touches your resources writes an immutable audit event. You can view your audit history in OdoPanel under Settings → Developer Access → Activity.

Audit events include:

• Tool name, timestamp, session name
• VM targeted and action taken
• Command string (for exec calls)
• Exit code, duration, result status
• Bounded stdout/stderr previews (capped, not full output)
• Source IP and user agent

Staff can search all MCP audit events from the admin MCP dashboard by user, customer, VM, session, tool, result, IP, or date range.

Kill Switch

Staff can activate two independent global kill switches during incidents:

• MCP global kill switch — disables all MCP tools (read, power, exec)
• MCP exec kill switch — disables only exec/artifact/async-command tools, leaves read-only tools working

Kill switch state is read per-request and takes effect immediately. No restart or deployment required.

Staff can also disable MCP exec on individual VMs or revoke any developer session at any time.

All Available Tools

Error Codes

MCP tools return structured errors with stable error codes. Common ones: