# IT-AI MCP server and itai CLI

> Every tool in the IT-AI MCP server and every itai CLI command, which ones a read-only token can call, and setup for Claude Code and other MCP clients.

Canonical page: https://glick.run/it-ai/mcp.html

`it-ai-mcp` is an MCP server that lets Claude Code, or any MCP client, drive the devices on your IT-AI hub by name. It has **32 tools**. `itai` is a command-line client for the same hub API. Both are MIT-licensed and live in [gitayg/haive-agent](https://github.com/gitayg/haive-agent) (`crates/mcp`, `crates/cli`).

Every call goes through your hub, which checks ownership, token scope and the deny-list, and writes the audit log, before the device is contacted. The **Read-only token** column says whether a token minted with `scope=read` can call the tool. Everything else answers `403 this MCP token is read-only`.

## Connect Claude Code

Download the MCP server for your machine from the [latest release](https://github.com/gitayg/haive-agent/releases/latest) (`it-ai-mcp-macos`, `it-ai-mcp-linux`, `it-ai-mcp-linux-arm64` or `it-ai-mcp-windows.exe`), then register it with your own hub URL, token and owner:

```sh
mkdir -p ~/.it-ai
curl -fsSL -o ~/.it-ai/it-ai-mcp https://github.com/gitayg/haive-agent/releases/latest/download/it-ai-mcp-macos
chmod +x ~/.it-ai/it-ai-mcp
claude mcp add-json itai '{
  "command": "'"$HOME"'/.it-ai/it-ai-mcp",
  "env": {
    "HAIVE_HUB": "https://your-hub.example.com",
    "HIVE_MCP_TOKEN": "<your-mcp-token>",
    "HIVE_OWNER": "<your-owner-id>"
  }
}'
```

Run `/mcp` in Claude Code and approve the server once. The MCP server downloads nothing at runtime.

## Other MCP clients

`it-ai-mcp` is a standard stdio MCP server. Any client that can launch a local command can use it: point the client at the binary and set three environment variables.

| Variable | Required | What it is |
|---|---|---|
| `HAIVE_HUB` | yes | your hub's URL |
| `HIVE_MCP_TOKEN` | yes | an MCP token from your hub; mint a read-only one to start |
| `HIVE_OWNER` | when the hub serves several users | the owner id to act as |
| `HAIVE_CAFILE` | optional | a PEM file to verify a self-signed hub certificate |

The token travels as `?mtok=` in each request. `it-ai-mcp` and `itai` mask it (`mtok=***`) in every error they print or return. Keep it in the environment, not on a command line.

## Tools

### Devices and inventory

| Tool | What it does | Read-only token |
|---|---|---|
| `list_devices` | Devices you own: OS, user, CPU, memory, live load, free RAM, interfaces, cameras, microphones, last seen | yes |
| `system_report` | One report from a device: `hardware`, `av`, `encryption`, `firewall`, `processes`, `services`, `network`, `packages` | yes |
| `compliance_posture` | Disk encryption, firewall, antivirus and OS updates, with a score, a grade and pass or fail per check | yes |
| `check_updates` | Pending OS and app updates (`winget upgrade`, `softwareupdate -l`, apt upgradable) | yes |
| `cve_lookup` | Known CVEs for a product or keyword from NVD, highest severity first. A lookup, not a scan | yes |

### Screen, input and camera

| Tool | What it does | Read-only token |
|---|---|---|
| `screenshot` | Capture the device's current screen | yes |
| `camera_snapshot` | Take a photo with the device's webcam | yes |
| `click` | Click at a position on the screen | no |
| `type_text` | Type text as keystrokes | no |
| `press_key` | Press a named key (Enter, Tab, Escape, …) | no |
| `message_user` | Show a popup message to the logged-in user | no |

### Commands, scripts and jobs

| Tool | What it does | Read-only token |
|---|---|---|
| `run_command` | Run a shell command and return its output (about 65 seconds at most) | no |
| `job_start` | Start a long-running command in the background and return its id | no |
| `job_logs` | Read a job's output from a byte offset | yes |
| `job_stop` | Stop a job and its child processes | no |
| `job_list` | List a device's jobs: id, state, pid, start time, command | yes |
| `search_scripts` | Search the Tactical RMM community-scripts library | yes |
| `run_script` | Run a community script on a device | no |
| `list_plugins` | List command plugins registered on your hub | yes |
| `run_plugin` | Run a hub command plugin on a device | no |

### Files

| Tool | What it does | Read-only token |
|---|---|---|
| `download_file` | Copy a file from the device to your machine | yes |
| `upload_file` | Copy a local file of up to 100 MB to the device | no |
| `push_file` | Copy a larger file by stage-and-pull: the hub stages it and the device pulls it with a SHA-256 check | no |

### Software, power and agent lifecycle

| Tool | What it does | Read-only token |
|---|---|---|
| `install_package` | Install software with winget, brew or apt | no |
| `uninstall_package` | Remove software with winget, brew or apt | no |
| `device_action` | Reboot, shut down, sleep, log off, firewall on or off, USB storage lock or unlock (USB lock is Windows-only) | no |
| `update_agent` | Update the agent to the build your hub serves | no |
| `dissolve_agent` | Stop the agent and remove its autostart (the binary is not deleted) | no |

### Whole fleet

| Tool | What it does | Read-only token |
|---|---|---|
| `fleet_run` | Run one command on every device you own, in parallel | no |
| `fleet_report` | Run one system report on every device you own | no (the hub treats its fleet route as a write) |
| `fleet_compliance` | Compliance grade for every device you own | yes |
| `run_script_fleet` | Run a community script on every device you own | no |

A read-only token can still read a device's screen, camera and files. Treat it as sensitive.

## The itai CLI

`itai` resolves a device by its hub name, so you never type an IP address. It reads the hub URL from `HAIVE_HUB`, the token from `HIVE_MCP_TOKEN` and the owner from `HIVE_OWNER`.

| Command | What it does |
|---|---|
| `itai list` | List your devices |
| `itai exec <device> <command…>` | Run a command and print its output, exiting with its exit code |
| `itai get <device> <remote> [local]` | Download a file |
| `itai put <device> <local> [remote_dir]` | Upload a file |
| `itai job start <device> [--cwd DIR] -- <command…>` | Start a background job and print its id |
| `itai job logs <device> <id> [--offset N] [--follow]` | Print a job's output; `--follow` waits until it exits |
| `itai job stop <device> <id>` | Stop a job and its child processes |
| `itai job list <device>` | List a device's jobs |

On macOS and Linux, `scripts/setup-itai.sh` in the repo installs `itai` in one command. It refuses to install on a missing or mismatched SHA-256 checksum and reads the token only from the environment.

## Operator skill for Claude Code

The repo ships a Claude Code skill, [`skills/it-ai/SKILL.md`](https://github.com/gitayg/haive-agent/blob/main/skills/it-ai/SKILL.md). It tells the agent which tool fits which task, to report a hub refusal instead of routing around the deny-list, to confirm destructive and fleet-wide actions first, and never to echo a token. Copy `skills/it-ai` into `~/.claude/skills/` to install it.