Cubicles
Cubicles docs

MCP server

Cubicles is a Model Context Protocol server. Add it to your AI app with an API key from the Developers page, and the AI can use your computers: start them, run commands, read and write files, and see their screens.

Server URL

https://api.cubicles.cloud/api/v1/mcp

Send Authorization: Bearer cub_…. On the Developers page the setup below comes with your new key already filled in.

Connect a client

Claude Code

Run in a terminal:
claude mcp add --transport http cubicles https://api.cubicles.cloud/api/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor

Add to ~/.cursor/mcp.json:
{
  "mcpServers": {
    "cubicles": {
      "url": "https://api.cubicles.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:
{
  "servers": {
    "cubicles": {
      "type": "http",
      "url": "https://api.cubicles.cloud/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml, with CUBICLES_API_KEY set in your shell:
[mcp_servers.cubicles]
url = "https://api.cubicles.cloud/api/v1/mcp"
bearer_token_env_var = "CUBICLES_API_KEY"

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):
{
  "mcpServers": {
    "cubicles": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.cubicles.cloud/api/v1/mcp",
        "--header",
        "Authorization:${CUBICLES_AUTH}"
      ],
      "env": {
        "CUBICLES_AUTH": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Tools

Commands run as the computer's user, with sudo, and open apps on its screen.

ToolArgumentsWhat it does
list_desktops–Your desktops with their id, name, plan, status and the actions allowed now
get_desktopdesktop_idOne desktop: status, plan, region, price, allowed actions
start_desktopdesktop_idTurns on a stopped desktop; poll get_desktop until it's running
stop_desktopdesktop_idShuts a running desktop down; its disk is kept
restart_desktopdesktop_idRestarts a running desktop
run_commanddesktop_id, command, stdin?, timeout_seconds?Runs a bash command as the desktop's user (passwordless sudo, DISPLAY=:1) and returns the exit code, stdout and stderr
read_filedesktop_id, pathA text file's content, up to 100,000 characters (a cut file says so, with its size; a binary one is refused). Relative paths start at home
write_filedesktop_id, path, contentWrites a text file (up to 512 KiB), making its folder and replacing a file already there
take_screenshotdesktop_idThe screen, as an MCP image (JPEG, at most 1920 pixels wide)
list_agents–Your agents and their status
get_agentagent_idOne agent: harness, model, desktop, chats, status
redeploy_agentagent_idSets an agent up again, e.g. after it stopped answering

The tools match the REST API: run_command is POST /desktops/{id}/exec, with the same limits.

How a model uses it

The server sends these instructions to the model when it connects:

Call list_desktops to find a desktop. If it's stopped, start_desktop, then poll get_desktop until its status is running. Then use run_command, read_file, write_file and take_screenshot on it. Commands run as the desktop's user, who has passwordless sudo; graphical apps open on its screen. New desktops are bought on cubicles.cloud.

Protocol details

  • Streamable HTTP transport at POST /mcp: one JSON-RPC 2.0 message (or a batch) per request, answered as application/json. Notifications get 202 with no body.
  • Stateless: no Mcp-Session-Id; GET and DELETE answer 405.
  • Protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05; a client asking for another gets the newest.
  • API key only (Authorization: Bearer cub_…); a browser session gets 403 api_key_required.
  • A tool that fails because of what it was asked (a stopped desktop, an unknown id) answers isError: true with the reason as text, for the model to read and correct, and structuredContent.error.code with the REST API's code (desktop_not_running, validation_failed, desktop_busy, …). An unknown tool is a JSON-RPC error.
  • Results also carry the JSON as structuredContent.
  • run_command, read_file, write_file and take_screenshot count toward 120 a minute per account.