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-keyheader. 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/mcpClaude 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
| Tool | What it does |
|---|---|
vm_list | List your VMs and their state |
vm_get, vm_get_by_name | Fetch one VM by id or name |
vm_create | Create a VM (size, region, image, profile, SSH key) |
vm_update | Change settings such as the startup command |
vm_start, vm_stop, vm_reboot | Lifecycle control |
vm_suspend | Snapshot the disk and stop compute billing |
vm_destroy | Delete 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:
- The agent calls
ssh_key_create_managed(or you create one in the dashboard). - It calls
vm_createwith that key. - Once
vm_getreports the machine ready, it callsssh_execwith 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>/mcpA 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
largeVM inams3fromubuntu-24-04-loadedwith my managed key, then clone github.com/acme/api on it and runbun 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-3and 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_createfails withINSUFFICIENT_FUNDSwhen 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.