Layerbeat

Agents and MCP

Let Claude Code, Codex, Cursor, opencode or any MCP client manage Layerbeat as tools.

layerbeat mcp serve turns the CLI into a Model Context Protocol server. Your coding agent then sees Layerbeat as tools — list servers, open a port, run a command, deploy a template — and uses them when you ask in plain words: "restart agent-01", "open port 443 on the API server", "how much disk is left?".

1. Install and give the agent a key

Install the CLI, then create an API key just for the agent, so its actions show under its own name and it can do only what you allow:

layerbeat keys create claude-code --scope vm:read --scope vm:write

You can also skip the key and let the agent use your own sign-in from layerbeat login. A key is the safer choice.

2. Add Layerbeat to your agent

Claude Code

claude mcp add layerbeat -e LAYERBEAT_API_KEY=lb_live_... -- layerbeat mcp serve

Codex

codex mcp add layerbeat --env LAYERBEAT_API_KEY=lb_live_... -- layerbeat mcp serve

Cursor — .cursor/mcp.json (project) or ~/.cursor/mcp.json (everywhere):

{
  "mcpServers": {
    "layerbeat": {
      "command": "layerbeat",
      "args": ["mcp", "serve"],
      "env": { "LAYERBEAT_API_KEY": "lb_live_..." }
    }
  }
}

opencode — opencode.json:

{
  "mcp": {
    "layerbeat": {
      "type": "local",
      "command": ["layerbeat", "mcp", "serve"],
      "environment": { "LAYERBEAT_API_KEY": "lb_live_..." }
    }
  }
}

Any other MCP client: run layerbeat mcp serve as a local (stdio) server. Leave out the key setting to use your own sign-in.

3. Ask it to work

The Canvas in the console shows the agent's changes on each server's activity, under the key's name.

What the agent can do

By default the agent can read your workspace and manage existing servers, but cannot spend or delete:

ToolsAvailable
whoami, list_regions, list_plans, list_images, quote, creditAlways
list_servers, get_server, get_operation, server_metrics, server_trafficAlways
start_server, stop_server, reboot_serverAlways
list_firewall_rules, add_firewall_rule, remove_firewall_rule, list_ssh_keysAlways
run_command (over SSH, with the server's pinned host key)Always
volume_options, list_volumes, attach_volume, detach_volumeAlways
list_templates, get_template, template_script, list_deployments, get_deployment, deploy_template, check_deployment, update_deployment, remove_deploymentAlways
create_server, renew_server, create_volume, renew_volume, top_upWith --allow-spend
delete_server, delete_volume, remove_deployment_and_dataWith --allow-delete

To let the agent buy, start it with layerbeat mcp serve --allow-spend in the configuration above. Every purchase then still needs a maximum price and an idempotency key, so an agent can't overspend or buy twice by retrying. The tools also need the key's scopes: buying needs vm:write, top-ups billing:write.

top_up returns payment instructions for a person to pay. With pay set to x402 or mpp, the agent pays it right away from this computer's wallet through pay or mppx, exactly like layerbeat topup --pay. Only agree to an amount you are happy for it to spend.

Agents without MCP

An agent that runs shell commands can use the CLI directly. Use --json and --no-input, add --yes to purchases it is allowed to make, and check exit codes; see Scripting. The MCP tools above add --yes themselves, because they already require --allow-spend, a maximum price and an idempotency key. For agents that call the HTTP API and pay with x402 or MPP, see Agent payments.

On this page

1. Install and give the agent a key2. Add Layerbeat to your agent3. Ask it to workWhat the agent can doAgents without MCP