Skip to main content
The host starts holo mcp over stdio, and the CLI exposes one tool named holo_desktop that runs each task on the local desktop runtime. MCP support is beta, and host implementations are still moving, especially around cancellation and long-running desktop tool calls.
When an MCP host calls HoloDesktop CLI, it delegates control of the visible desktop. The CLI may open apps, switch focus, click, type, and read whatever is on screen until the task finishes, times out, or is cancelled.

​
Before you start

Run one CLI task first to check that HoloDesktop CLI starts on this machine: 
holo run "Open TextEdit and write a short note saying HoloDesktop CLI is installed"
For hosted mode, sign in before installing HoloDesktop CLI into a host: 
holo login
holo whoami
MCP hosts launch HoloDesktop CLI non-interactively, so they cannot complete browser login during startup. For local mode, make sure the host process can read your local model settings: 
export HAI_AGENT_RUNTIME_BASE_URL=http://localhost:8000/v1
Set HAI_AGENT_RUNTIME_MODEL too if your local server needs a model ID, for example Hcompany/Holo-3.1-35B-A3B. That export works for terminal-launched hosts such as Claude Code, Codex, OpenCode, or other MCP clients you start from the same shell. GUI apps launched from the Dock or Finder usually do not inherit shell exports. For those hosts, add the variables to the host’s MCP config if it supports an env block, or start the host from a shell that already has the variables set.

​
List supported hosts

holo install list
This prints supported host IDs and whether each host is detected on your machine. Supported host IDs include:
Host IDHost
claude-codeClaude Code
claude-desktopClaude Desktop
codexCodex
cursorCursor
opencodeOpenCode
openclawOpenClaw
hermesHermes
copilotGitHub Copilot CLI
antigravityAntigravity

​
Install into one host

Install into Claude Code from the workspace where Claude Code should use HoloDesktop CLI: 
cd /path/to/your/claude-code-workspace
holo install claude-code
Claude Code’s MCP CLI defaults to local scope. HoloDesktop CLI calls that CLI, so the MCP server is registered for the current Claude Code workspace. Claude stores the local-scoped entry in its own config, associated with that project path, rather than in a HoloDesktop CLI-managed mcp.json file. Install into Cursor: 
holo install cursor
Install into every detected supported host: 
holo install
If Claude Code is detected, HoloDesktop CLI uses Claude Code’s local scope for the current workspace. holo install either calls the host’s own MCP CLI or updates the host’s MCP config file. When possible, it writes the absolute path to the holo executable so GUI hosts do not depend on your shell PATH. For file-backed hosts such as Cursor, the installed entry looks like this: 
{
  "mcpServers": {
    "holo": {
      "type": "stdio",
      "command": "/absolute/path/to/holo",
      "args": ["mcp"]
    }
  }
}
For local mode in a GUI host, add environment variables in the shape that host supports, for example: 
{
  "mcpServers": {
    "holo": {
      "type": "stdio",
      "command": "/absolute/path/to/holo",
      "args": ["mcp"],
      "env": {
        "HAI_AGENT_RUNTIME_BASE_URL": "http://localhost:8000/v1",
        "HAI_AGENT_RUNTIME_MODEL": "Hcompany/Holo-3.1-35B-A3B"
      }
    }
  }
}
Re-running holo install preserves extra keys such as env while refreshing the command and args.

​
Stop an MCP run

For MCP, the host owns the chat UI and HoloDesktop CLI runs as a stdio tool server. Cancel the in-progress tool call from the host; HoloDesktop CLI cancels the active runtime session when it receives the MCP notifications/cancelled signal or when the host closes the stdio connection. Some hosts do not propagate cancellation reliably yet, so prefer short tasks and bound them with the runtime’s step and time budgets.

​
What the host gets

The MCP server exposes one tool: 
holo_desktop(task: str) -> str
holo_desktop is a blocking tool call, not a background job. While it is running, HoloDesktop CLI owns one desktop task and may keep observing, clicking, and typing until the task completes or reaches its safety budget.MCP defines request cancellation with a notifications/cancelled message for an in-progress request. Current HoloDesktop CLI clients use that signal, and stdio-server shutdown, to cancel the active runtime session before the tool call unwinds. Some MCP hosts do not propagate cancellation consistently yet, so stopping a chat response may not stop the desktop run right away. We are working with upstream host providers to improve this. For now, keep HoloDesktop CLI up to date and prefer short, specific tasks that can finish or time out cleanly.
Each call should contain a self-contained desktop task. The calling host should include the context HoloDesktop CLI needs: the app, workspace, account, person, and success condition. Good task: 
Open Slack in the Acme workspace and send a DM to Sarah Chen saying "on my way". Return "sent" after the message appears.
Too vague: 
Tell Sarah.

​
Confirm the host picked it up

Restart the host after installation if it was already open. Then ask the host to do a small, safe desktop task, such as opening a text editor and writing a short note. If the host cannot find HoloDesktop CLI:
  • run holo install list and confirm the host ID;
  • re-run holo install <host-id>;
  • check that hosted mode has HAI_API_KEY available, or local mode has HAI_AGENT_RUNTIME_BASE_URL available to the host process;
  • check ~/.holo/logs/ for runtime startup errors.

​
What’s next

Use HoloDesktop CLI as a skill to understand the guidance installed into hosts that support skill loading.