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/mcpSend 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.
| Tool | Arguments | What it does |
|---|---|---|
list_desktops | – | Your desktops with their id, name, plan, status and the actions allowed now |
get_desktop | desktop_id | One desktop: status, plan, region, price, allowed actions |
start_desktop | desktop_id | Turns on a stopped desktop; poll get_desktop until it's running |
stop_desktop | desktop_id | Shuts a running desktop down; its disk is kept |
restart_desktop | desktop_id | Restarts a running desktop |
run_command | desktop_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_file | desktop_id, path | A 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_file | desktop_id, path, content | Writes a text file (up to 512 KiB), making its folder and replacing a file already there |
take_screenshot | desktop_id | The screen, as an MCP image (JPEG, at most 1920 pixels wide) |
list_agents | – | Your agents and their status |
get_agent | agent_id | One agent: harness, model, desktop, chats, status |
redeploy_agent | agent_id | Sets 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 asapplication/json. Notifications get202with no body. - Stateless: no
Mcp-Session-Id;GETandDELETEanswer405. - Protocol versions
2025-11-25,2025-06-18,2025-03-26and2024-11-05; a client asking for another gets the newest. - API key only (
Authorization: Bearer cub_…); a browser session gets403 api_key_required. - A tool that fails because of what it was asked (a stopped desktop, an unknown id) answers
isError: truewith the reason as text, for the model to read and correct, andstructuredContent.error.codewith 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_fileandtake_screenshotcount toward 120 a minute per account.