Skip to main content
Use MCP when another agent host should call HoloDesktop CLI as a desktop-control tool. The host starts holo mcp over stdio. The CLI starts the desktop runtime locally and exposes one tool named holo_desktop.
MCP support is beta. The protocol 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 observe whatever is on screen until the task completes, times out, or is cancelled.

​
Before you start

Run one CLI task first to check that HoloDesktop CLI starts on this machine: 
uv run 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: 
uv run holo login
uv run 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

uv run 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
uv run 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: 
uv run holo install cursor
Install into every detected supported host: 
uv run 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. Keep both stop paths available:
  • press Esc twice quickly if the guard is installed and running;
  • run uv run holo stop from a terminal if you need a host-independent stop request.
uv run holo stop
holo install can install the guard so double-Esc works for host-launched runs. On macOS, grant Input Monitoring to the guard when prompted; a listener inside the MCP process may not receive key events because macOS attributes the permission to the launching GUI app. Normal stop is step-bounded: the CLI pauses and cancels the active run at the next safe point. If the run is stuck and does not respond, use uv run holo stop --force, then restart the host if its MCP tool call is still blocked.

​
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 uv run holo install list and confirm the host ID;
  • re-run uv 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.