MCP quick start

This page gives an MCP host, such as Claude Code or Cursor, a desktop. You need holm installed and a container runtime running.

There are two transports. Both give the same boxes and tools.

Local host (stdio)

Add the server to the host's MCP configuration:

{
  "mcpServers": {
    "holm": {
      "command": "holm",
      "args": ["mcp", "--stdio"]
    }
  }
}

With no server running, holm mcp starts its own. Traces, forks, and box expiry then stop when the host stops the process. To keep them, run holmd and point the host at it:

{
  "mcpServers": {
    "holm": {
      "command": "holm",
      "args": ["mcp", "--stdio"],
      "env": {
        "HOLM_SERVER_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

Add HOLM_SERVER_TOKEN to env when the server needs a token.

Remote host (Streamable HTTP)

Start holmd with a token. The server refuses a non-loopback address without one:

HOLM_SERVER_ADDR=0.0.0.0:8080 \
HOLM_SERVER_TOKEN="$(openssl rand -hex 32)" \
HOLM_PUBLIC_URL=https://boxes.example.com \
holmd

Configure the host:

URL:           https://boxes.example.com/mcp
Transport:     Streamable HTTP
Authorization: Bearer <HOLM_SERVER_TOKEN>

Put TLS in a reverse proxy in front of holmd, and forward WebSocket upgrades. Set HOLM_PUBLIC_URL to the public origin when the proxy hides it.

Try it

Ask the agent to do a task, for example:

Open example.com in a new box, click "More information", and tell me the title of the page that opens.

A typical task uses these tools:

1. launch_box opens a box and returns its box_id.
2. open_url opens a page.
3. snapshot lists the controls on the page, with references such as @e12.
4. click_element, fill_field, dropdown, and check act on controls by name or reference.
5. wait_for waits after an action that loads a page or fetches data.
6. remove_box removes the box.

For applications that are not web pages, the agent uses screenshot, click, type_text, and press_key. Each tool that changes the screen returns the frame it produced.

See the MCP tools reference for all tools.

Watch the desktop

Hosts that support MCP Apps show the live desktop beside the results of launch_box, open_screen, and hand_over. A person can watch, take control, give control back, and record.

In other hosts, hand_over returns a URL that a person opens in a browser. The agent cannot send input until it calls reclaim_screen.