The Wazza OS MCP

MCP (the Model Context Protocol) is the standard way an AI agent gets tools. Wazza OS gives the agent of every Chat its own tools through its MCP server, whatever the agent and the model: that is how an agent opens apps, works in them, handles files and starts other agents. You have nothing to set up. Agents that run outside Wazza OS get the same reach through wazza-os mcp.

How it works#

An MCP server lists tools: each with a name, what it does and its arguments. The agent's model reads the list, picks the tools a task needs and calls them; each answer comes back to the model. In Wazza OS, every Chat, whether its agent is Hermes, Prime Agent, Claude Code, Codex or Antigravity, is connected to Wazza OS's server (named wazzastu in agents' tool lists) when it starts. Each call shows in the Chat as a step you can open (Follow the agent's work).

The tools a Chat gets#

The rules the tools follow#

• Your view never changes. A tab an agent opens opens in the background, with a badge; the tab you are looking at is never closed or moved.
• Inside the VM, agents do not ask. Commands, installs and steps in apps run at once (Where Wazza OS asks you).
• Some things only you can do. Starting Computer Control, Let this Chat edit my files, turning on Local services, importing your Chrome profile and loosening the file-copy rules need your own click: an agent asking for them is refused, and tells you.
• Each Chat works in its VM. A Chat acts on the tabs of its own VM (it opens an app in another VM only when asked to); only the Computer Control Chat can look at your computer's screen.

Connect an agent from outside Wazza OS#

Agents that run outside Wazza OS, on your computer or on a server (Claude Code, Codex, Cursor, VS Code, Gemini CLI and others), connect to wazza-os mcp: an MCP server that comes with Wazza OS. Its tools are the commands of the command line (vm, app, explorer: its file copies are in Move files, drive, chat_transcript, timeouts…), plus ui for the window's actions (open an app, send to a Chat…), check and version. Each call runs the same wazza --gui … command your terminal would, with your rights.

1. Add the server to your agent, once. Wazza OS can be closed while you do: it is only a line in your agent's settings. For Claude Code:

   $ claude mcp add --scope user wazza-os -- wazza-os mcp

   For another agent, wazza-os mcp --print-config CLIENT prints what to add (table below). Wazza OS never edits your agents' settings itself.

2. Start Wazza OS before you ask (on a server: Wazza OS on a server).

3. Ask your agent, for example: In Wazza OS, open Files in the background, ask its Chat what is in my Documents folder, and tell me.

Good to know#

• The tools need Wazza OS running. With it closed, status and the other tools answer that the Wazza OS app is not running for this user; check (what this computer lacks) and version work anyway.
• Who starts Wazza OS. In the published build (0.2.0, build 44c5d0ea07c1) no tool starts it: the agent asks you to, and you start it from your app menu, with wazzaos in a terminal, or on a server with wazza --virtual-screen=always. From the next release, the start tool starts it.
• Pictures of Wazza OS and input into it. In the published build, screenshot and native_input work only with Wazza OS's own screen on a server (the virtual screen). From the next release they also work on a desktop, on Wazza OS's own window only: while an agent holds the input, a mark on the window says so.
• Apps open in the background. The agent opens an app inside Wazza OS with ui open_app: it gets a tab of its own in the background, and your screen stays as it is.

Hermes and Prime Agent#

The two agents of Wazza OS's own Chats can also run on their own, outside Wazza OS. These lines work with the published build (0.2.0, build 44c5d0ea07c1; tested with the Hermes and Prime Agent versions Wazza OS ships: 40 tools, a status call answered). --print-config hermes and --print-config prime, which print exactly these lines, come in the next release.

Prime Agent: one command, which writes the server into ~/.prime/agent/settings.json:

$ prime-agent mcp add wazza-os --env XDG_RUNTIME_DIR=XDG_RUNTIME_DIR --env DISPLAY=DISPLAY --env WAYLAND_DISPLAY=WAYLAND_DISPLAY -- wazza-os mcp

Prime Agent gives a server only HOME, PATH and TMPDIR. The --env parts pass on XDG_RUNTIME_DIR, without which wazza-os mcp cannot find the running Wazza OS (every call would say it is not running), and your display, for the next release's start tool. A variable your session does not have is passed on empty, which does no harm.

Hermes: add this to ~/.hermes/config.yaml, under mcp_servers:

mcp_servers:
  wazza-os:
    command: wazza-os
    args: ["mcp"]
    enabled: true
    timeout: 600
    env:
      DISPLAY: ${DISPLAY}
      WAYLAND_DISPLAY: ${WAYLAND_DISPLAY}

timeout: 600 lets one call run up to 10 minutes (Hermes stops a call after 5 by default, and a Drive step can take longer). Hermes gives a server only a few environment variables (XDG_RUNTIME_DIR among them, which wazza-os mcp needs): env passes your display on, so that the next release's start tool can open Wazza OS's window on your desktop. To let the next release's provider_keys read an API key from the environment (add_from_env), list that variable under env too.

What the agent does#

1. status: is Wazza OS running? If not, every tool answers that the Wazza OS app is not running for this user, and the agent asks you to start it.

2. vm (list, start): the VMs.

3. ui open_app: the app opens in a background tab; your screen stays as it is. vm_tabs_read gives its tab.

4. ui chat_send to that tab's Chat (a Chat never shown starts in the background), then chat_transcript reads its answer.

5. drive look and act, for work in the app itself.

What stays yours#

• Computer Control starts only with your own click; the tools are refused it.
• Deleting or resetting a VM, removing data and similar commands need the command line's own confirmations (the yes argument, or the typed words REMOVE ALL DATA), and are marked as destructive, so agents ask you before calling them.
• The pro and wazza_tools tools spend Wazza Pro credits: they run only with confirm_spend, and only when you asked for that run.
• Passwords and keys travel only as the command's standard input, never in a command line.
• Nothing runs while it is idle: the server lives only while your agent runs it.

Every tool with what it does, its arguments and an example: Every Wazza OS MCP tool (the same text as wazza-os mcp --print-docs). An agent without MCP runs the same commands in its shell (The command line).