← Blog

Guide

Remote MCP Server for Cloud VMs: Let Agents Manage Machines

machine0 exposes a remote MCP server at https://app.machine0.io/mcp over Streamable HTTP. Add it to Claude Code with one command, or to Claude Desktop or claude.ai as a connector, and the agent gets tools to list, create, start, stop, suspend and destroy VMs, build images, manage SSH keys and run shell commands on a machine. Interactive clients sign in with OAuth; scripts send an x-api-key header.

## What the remote MCP server does

The Model Context Protocol gives an agent a standard way to call tools. machine0's MCP server turns the whole platform into tools: everything the CLI can do to a machine, an image or an SSH key, an agent can do by calling a tool. Because it is a remote server, there is nothing to install. The agent connects to a URL, signs in, and starts managing infrastructure.

The practical result is an agent that can provision its own compute. Ask Claude to "spin up a large VM in London, clone the repo and run the test suite", and it can create the machine, wait for it to be ready, and run the commands over SSH, all through MCP.

## Endpoint and authentication

  • Endpoint: https://app.machine0.io/mcp, using the Streamable HTTP transport.
  • Interactive clients (Claude Code, Claude Desktop, claude.ai) authenticate with OAuth. The sign-in flow opens in a browser the first time you connect.
  • Programmatic clients send an x-api-key header. Create a key in the dashboard under Account, then API Tokens. Never ship an API key to a browser.

## Setup: Claude Code

One command:

$ claude mcp add --transport http machine0 https://app.machine0.io/mcp

Claude Code opens the OAuth flow, and the machine0 tools are available in the next session.

## Setup: Claude Desktop

Add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "machine0": {
      "url": "https://app.machine0.io/mcp"
    }
  }
}

Restart Claude Desktop and sign in when it asks.

## Setup: claude.ai

Add https://app.machine0.io/mcp as a custom connector. OAuth runs automatically; there is nothing else to configure.

## The tool groups

Tools are grouped by what they act on. The names below are the real tool names.

Machines

ToolWhat it does
vm_listList your VMs and their state
vm_get, vm_get_by_nameFetch one VM by id or name
vm_createCreate a VM (size, region, image, profile, SSH key)
vm_updateChange settings such as the startup command
vm_start, vm_stop, vm_rebootLifecycle control
vm_suspendSnapshot the disk and stop compute billing
vm_destroyDelete the VM

Images: list and inspect images, plus image_build, which builds an image from a git repository containing a NixOS flake. This is how an agent turns a declarative config into a reusable image.

SSH Keys: list, create and manage keys, including ssh_key_create_managed, which creates a key machine0 holds on your behalf.

SSH Exec: ssh_exec runs a shell command on a VM and returns the output. It requires a VM that was created with a managed key, so the server has something to authenticate with.

Sizes: list the available sizes, their specs and prices, so an agent can pick the right machine for a job.

Errors come back with structured codes such as INSUFFICIENT_FUNDS and MACHINE_NOT_READY, so an agent can tell "wait and retry" apart from "stop and ask the user".

## Running commands on a VM: ssh_exec and managed keys

The pattern that makes an agent genuinely useful is create, then execute. For that the VM needs a managed SSH key:

  1. The agent calls ssh_key_create_managed (or you create one in the dashboard).
  2. It calls vm_create with that key.
  3. Once vm_get reports the machine ready, it calls ssh_exec with the commands to run.

Managed keys are also what the browser terminal in the dashboard and the metrics feature use, so a VM created this way works with all three.

## Per-profile MCP endpoints

Every profile serves its own aggregated MCP endpoint:

https://app.machine0.io/profiles/<name>/mcp

A profile bundles integrations (GitHub, Claude Code, Codex, any remote MCP server you add), prompts and environment variables. Connect a profile's endpoint instead of the base one and the agent sees the profile's MCP servers through a single connection, with the profile's prompts exposed as slash commands in Claude clients. Add a third-party server to a profile with the CLI:

$ machine0 integrations add linear --url https://mcp.linear.app/mcp --profile default
$ machine0 integrations connect linear

## Example prompts

Once connected, prompts like these work as written:

  • "List my machines and suspend any that have been running for more than a day."
  • "Create a large VM in ams3 from ubuntu-24-04-loaded with my managed key, then clone github.com/acme/api on it and run bun test."
  • "What GPU sizes are available and what do they cost per hour?"
  • "Build an image from github.com/acme/infra (it has a NixOS flake), then create a VM from it."
  • "Reboot worker-3 and tell me when it is back."

## Cost control: agents can spend money

A tool that creates VMs creates bills. Every VM an agent makes is billed per minute from the moment it runs, including while stopped. Two safeguards are built in, and one is up to you:

  • Insufficient funds stop creation. vm_create fails with INSUFFICIENT_FUNDS when the wallet cannot cover it.
  • The suspension threshold protects your data. When the balance drops to the threshold (enough to store snapshots, images and disks for 7 days, usually a few dollars), running machines are snapshotted and destroyed and the snapshots are kept. A warning email arrives about 6 hours before.
  • Turn auto top-up off on the Account page if you want a hard ceiling. Auto top-up is on by default once a card is saved; with it off, your balance is the most an agent can spend. There is no separate spend cap or budget alert feature, so this is the lever.

It is also worth telling the agent, in its instructions, to suspend or destroy what it creates when the job is done. The Machines limit is 50 at once for accounts created since July 28, 2026, so a runaway loop is bounded, but 50 idle VMs still cost money.

## FAQ

How do I add the machine0 MCP server to Claude Code?

Run claude mcp add --transport http machine0 https://app.machine0.io/mcp and complete the OAuth sign-in when prompted.

Does it work with claude.ai and Claude Desktop?

Yes. In claude.ai add https://app.machine0.io/mcp as a custom connector and OAuth runs automatically. In Claude Desktop add it under mcpServers in claude_desktop_config.json with the same URL.

Can an agent run commands on a VM through MCP?

Yes, with ssh_exec. The VM has to have been created with a managed SSH key, which the agent can create first with ssh_key_create_managed.

How do I authenticate from a script instead of a chat client?

Create an API key in the dashboard under Account, then API Tokens, and send it in an x-api-key header on requests to the MCP endpoint.

What stops an agent from spending too much?

Your wallet. With auto top-up turned off, machines stop being created once the balance runs out, and at the suspension threshold running machines are snapshotted and destroyed. There is no separate spend cap feature.

What errors can tools return?

Structured codes such as INSUFFICIENT_FUNDS when the wallet is empty and MACHINE_NOT_READY when a VM is still provisioning. Agents can read the code and retry or report accordingly.

## Sources

## Related

  • API reference: The three ways to control machine0: SDK, CLI and MCP, with auth and error codes.
  • SDKs: The TypeScript SDK, the CLI with --json output, and the remote MCP server.
  • Run Claude Code or Codex in the cloud: Step by step: a VM with Claude Code or Codex, GitHub and MCP connected, running in tmux, suspended when idle.
  • Rate limits: API, machine, wallet and MCP limits, and how to handle 429 responses.