mcp

# mandala-computer-mcp

An [MCP](https://modelcontextprotocol.io) server for
[Mandala Computer](https://mandala.computer) — cloud desktops for AI agents.

Point Claude Code, Claude Desktop, or anything else that speaks MCP at a real
Linux desktop it can **see and drive**. Screenshots come back as images, so the
model looks at the screen and clicks what it sees.

> **Status: alpha.** The tool surface is settling; expect breaking changes
> before 1.0. Tracks the platform's `/api/v1`, which is itself still moving.

## Install

MCP requires Node 20.3 or newer. The **TypeScript CLI** login setup requires
Node 22 or newer (`mandala-computer` on npm). Sign in once, then add the MCP
server:

```sh
npm install -g mandala-computer
mandala login
claude mcp add mandala -- npx -y mandala-computer-mcp
```

On Node 20, MCP can use an existing saved profile or an environment key.
The TypeScript CLI guides you through browser approval and saves an API key in
`~/.mandala/credentials.json`. MCP only reads that file; it never issues or
approves a device, writes credentials, or starts login automatically. The
Python distribution also provides a `mandala` command; use the TypeScript
CLI for `login`.

To select a separate profile and workspace:

```sh
mandala login --profile Work --workspace Research
claude mcp add mandala -- npx -y mandala-computer-mcp --profile Work
```

`--profile` takes precedence over `MANDALA_PROFILE`, then the saved default.
Names are case-sensitive. An explicit key or nonempty `MANDALA_API_KEY` takes
precedence over every profile and avoids accessing the credential store.
Empty explicit keys fail; an empty or whitespace-only environment key is absent.
You can still use a key from **Settings → Credentials → API keys** with
`MANDALA_API_KEY`.

Saved credentials require POSIX protection: a real directory owned by you with
mode `0700`, and an owned regular file with mode `0600` and one link. Symlinks,
hardlinks, unsafe permissions, malformed files and unsupported protection are
refused before any API request. Windows file loading is unsupported; explicit
or environment keys remain available. Only your home directory's store is read.

A saved profile also binds its API base URL. `--base-url` or `MANDALA_BASE_URL`
must match that stored base after canonicalization, including the entire path
prefix and port. An explicitly empty base flag is invalid with saved credentials.
Each stdio session resolves once: restart to pick up another saved key. Revoking
the key in **Settings → Credentials → API keys** makes later calls fail; MCP
does not switch profiles, reread the file, or retry a refused action. Run login
explicitly when new credentials are needed.

A saved profile can also carry a default workspace, set with
`mandala workspaces use <workspace>` (and removed with `--clear`); the CLI keeps
it in `~/.mandala/defaults.json`, beside `credentials.json`, which it never
changes. Started from that profile, the secret tools (`list_secrets`,
`get_secret`, `create_secret`, `set_secret`, `replace_secret`,
`delete_secret`), `create_computer` and `list_computers` use it when a call
leaves out `workspace_id`, as `mandala computers create` and `computers list`
do; an explicit `workspace_id` always wins. Their descriptions say so and name
the workspace, `list_secrets`, `list_computers` and `create_computer` say when
the default chose the workspace, and startup prints it on stderr. There is no
"every workspace" value: to list elsewhere, pass another `workspace_id` (or
`'unassigned'`), or start the server from a profile with no default. MCP
only reads that file, once at startup, with the same checks as
`credentials.json`. It is not applied when the profile's key is confined to a
workspace (that key's own scope applies), when the default was saved for
another account than the profile is logged in to now, or with an explicit or
environment key. A file that cannot be read (not valid JSON, another version,
or readable by others) is noted on stderr: `list_secrets`, `get_secret` and
`list_computers` then use account-wide, but `create_secret`, `set_secret`,
`replace_secret`, `delete_secret` and `create_computer` refuse a call without
`workspace_id`, sending nothing, rather than act account-wide; pass
`workspace_id`, or fix or delete the file and restart the server. The hosted
HTTP server never reads it, and its tools are unchanged.

**Claude Code** — as a plugin, which installs the server and a skill together:

```sh
# Run mandala login first, or export MANDALA_API_KEY in this shell.
/plugin marketplace add mandalacomputer/mcp
/plugin install mandala-computer@mandala
```

The skill — [`plugin/skills/mandala-computer/SKILL.md`](plugin/skills/mandala-computer/SKILL.md)
— is the part the tools cannot say for themselves: when a cloud desktop is the
right answer at all, that it costs money until it is suspended or stopped, that
`run_agent` is usually the right level and a screenshot per click is not, and
which refusals are worth a second try. It is a description of *when and how*,
not a second client; once the server is installed it stays out of the way.
`MANDALA_MODEL_KEY`, if exported alongside, is passed through and turns on
`run_agent` when the configured filters permit it. Without it, `run_agent` runs
on the account's AI credits when they can pay (see [Agents on AI
credits](#agents-on-ai-credits)).

To use an environment key instead of a saved profile:

```sh
claude mcp add mandala -e MANDALA_API_KEY=com_… -- npx -y mandala-computer-mcp
```

**Claude Desktop** — in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mandala": {
      "command": "npx",
      "args": ["-y", "mandala-computer-mcp"]
    }
  }
}
```

**Cursor, Windsurf and the rest** take the same three fields — `command`,
`args`, `env` — in whichever file they keep their MCP servers in.

Your MCP client starts this as a subprocess. It uses the saved profile’s API
base, or `https://app.mandala.computer/api/v1` by default with an environment key.
Programmatic local hosts can call `runStdio({ profile: 'Work' })`; the exported
`StdioConfig` allows a local key or profile. `createServer` still requires an
explicit API key, and `HttpConfig` has no local credential options.

## Use

Ask for what you want. A first session usually goes:

> Create a computer from the base template, open example.com, and show me what's
> on the screen.

Under that, the model is doing roughly this:

```
create_computer(template="base")     → builds it and selects it for the session
wait_for_computer(until="guest")     → the desktop inside is answering, not just the VM
open_url(url="https://example.com")  → puts the page on the screen
screenshot()                         → an image the model can point at
click(x=640, y=400)                  → clicks what it saw
screenshot()                         → looks again
```

`create_computer(size="large")` is the fast path: the named shapes from
`list_sizes` are the ones the platform keeps pre-booted, so one of those is
usually answered in about a second where a custom `cpu`/`ram_mb`/`disk_gb`
shape boots cold. A `size` sets the template and the numbers together, so send
it alone or the explicit fields alone.

`use_computer` binds a machine to the session, so every later call can leave
`computer_id` out. Pass `computer_id` explicitly on any call to override it
without changing the binding, which is how you drive two machines at once.

Set `MANDALA_COMPUTER_ID` to bind one at startup and skip `use_computer`
entirely.

## The tools

This is the unfiltered inventory. The filters below can withhold tools from
both listing and calling; workflows in this README apply only when the needed
tools are available. The offline fixture checks exercised operation coverage;
verification against the live publication is a separate required CI gate.
Parameter and response-mode support remains a separate contract.

**Choosing a machine** — `list_templates`, `list_sizes`, `list_computers`, `get_computer`,
`use_computer`, `wait_for_computer`, `get_desktop_url`

**Lifecycle** — `create_computer`, `start_computer`, `stop_computer`,
`suspend_computer`, `restart_computer`, `update_computer`, `clone_computer`,
`delete_computer`, `move_computer_to_workspace`, `move_computer`, `list_moves`, `get_operation`,
`list_operations`, `wait_for_operation` — see [Lifecycle operations](#lifecycle-operations)

`move_computer_to_workspace` changes workspace membership and who can access a computer.
It requires an account-wide member or owner credential and explicit `computer_id` and
`workspace_id` arguments (`null` means unassigned). The selected computer and default
workspace are not used. The computer must be stopped, with no saved session, snapshots
or snapshot history copies, secret bindings, or proxy credentials. Refusals leave
those resources intact; the tool never removes them to force a move. This is separate
from `move_computer`, which relocates a computer to different hardware.

**Driving the desktop** — `screenshot`, `click`, `type_text`, `paste_text`,
`press_key`, `scroll`, `drag`, `move_mouse`, `mouse_button`, `cursor_position`,
`wait`

Every one of these that acts — all but `screenshot` and `cursor_position` —
takes `context: true` and then answers the desktop as it stands just after the
action: the windows `list_windows` would list and the one with focus, without a
second call. They are read once, straight after the action, so a window still
opening may not be listed yet; when they cannot be read the action still
happened, and the answer says why. When the focused window is Chromium the
answer also carries `page`: the page's URL and title and one line per
interactive element visible in it — what it is, what it says (and its
accessible name when that is something else), and the point to click. Firefox, the default browser, has no `page`; then `page_not_read` gives
the platform's reason beside the windows.

**Inside the guest** — `exec`, `exec_poll`, `exec_kill`, `get_execution`,
`r