> ## Documentation Index
> Fetch the complete documentation index at: https://hub.hcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use HoloDesktop CLI as an MCP server

> Expose HoloDesktop CLI to MCP-capable hosts such as Claude Code, Cursor, Codex, Grok Build, and OpenCode.

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.

<Danger>
  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.
</Danger>

## Before you start

Run one CLI task first to check that HoloDesktop CLI starts on this machine:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
holo install list
```

This prints supported host IDs and whether each host is detected on your machine.

Supported host IDs include:

| Host ID          | Host               |
| ---------------- | ------------------ |
| `claude-code`    | Claude Code        |
| `claude-desktop` | Claude Desktop     |
| `codex`          | Codex              |
| `cursor`         | Cursor             |
| `grok-build`     | Grok Build         |
| `opencode`       | OpenCode           |
| `openclaw`       | OpenClaw           |
| `hermes`         | Hermes             |
| `copilot`        | GitHub Copilot CLI |
| `antigravity`    | Antigravity        |

## Install into one host

Install into Claude Code from the workspace where Claude Code should use HoloDesktop CLI:

```bash theme={null}
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:

```bash theme={null}
holo install cursor
```

Install into Grok Build:

```bash theme={null}
holo install grok-build
```

This registers the `holo` MCP server in `~/.grok/config.toml` through Grok Build's own CLI and installs the bundled skill under `~/.grok/skills/holo-desktop`.

Check that Grok Build loaded both integrations:

```bash theme={null}
grok mcp list
grok inspect
```

Install into every detected supported host:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```text theme={null}
holo_desktop(task: str) -> str
```

<Danger>
  `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.
</Danger>

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:

```text theme={null}
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:

```text theme={null}
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](/holo-desktop-cli/integrations/use-as-skill) to understand the guidance installed into hosts that support skill loading.