AI agents and MCP (Tech Preview)

MacVisor has an MCP server. With it, an AI agent on your Mac can work with VMs: run commands in them, read and write their files, take snapshots and roll back, start and stop them, and see and use their screens. The agent can be Claude Code, Claude Desktop, Codex, Cursor or any other app that speaks the Model Context Protocol.

The agent reaches two kinds of VM:

• AI sandboxes, disposable VMs with a copy of one project, made for an agent to work in. See AI sandboxes.
• Your own VMs, but only the ones you open to agents, and only as far as you allow. Every VM starts closed. A closed VM is invisible to agents: they can't list it, use it or learn its name.

With --allow-create, the agent can also make new VMs from a cloud image or a template you choose, and delete those again.

Connect an agent

The server is mvz mcp serve. It runs on your Mac and talks to the agent over standard input and output, so it opens no network port. The agent starts it, and it stops when the agent quits.

Claude Code:

claude mcp add --scope user macvisor -- mvz mcp serve

# or, to let it make VMs as well:
claude mcp add --scope user macvisor -- mvz mcp serve --allow-create

--scope user makes MacVisor's tools available in every folder. Without it, Claude Code adds the server only for the folder you run the command in.

Claude Desktop, Cursor and most other apps take a JSON entry like this one in their MCP settings. Use the full path, because apps don't always search /usr/local/bin:

{
  "mcpServers": {
    "macvisor": {
      "command": "/usr/local/bin/mvz",
      "args": ["mcp", "serve"]
    }
  }
}

Codex CLI, in ~/.codex/config.toml:

[mcp_servers.macvisor]
command = "/usr/local/bin/mvz"
args = ["mcp", "serve"]

Then ask the agent what it can see, for example "Which MacVisor VMs can you use?" It answers from vm_list and sandbox_list.

Open a VM to agents

Choose how far agents may go with each VM:

Set it in the VM's Settings → AI Agents, or from Terminal:

mvz set dev --agents view
mvz set dev --agents control      # asks first; --yes doesn't
mvz set dev --agents off
mvz agents                        # every VM agents may use, and how far

The change applies at the agent's next request. You don't need to restart the VM or the agent. If you turn a VM off while an agent is using it, its next command, screenshot or click is refused.

A VM's shared folders show your Mac's files to its guest. At View, agents can read the Mac's files in them (a dev VM made with --home shares your home folder, ~/.ssh included); at Control they can change the read-write ones. VMs agents make from a template keep the template's shared folders. Settings → AI Agents and mvz set --agents say so, and vm_info lists the shares. Open only VMs without shared folders if that matters.

On a template, any level lets agents make VMs from it with vm_create, and sandboxes with sandbox_create. Agents can't run a template or change it, and a template you didn't open is never copied for them.

What agents can do

The tools also work on AI sandboxes: the agent names a sandbox with sandbox instead of vm. diff works on sandboxes only.

Commands and files reach Linux VMs made from a cloud image and macOS VMs, over SSH as MacVisor sets it up for mvz shell. On a Windows VM, agents use the screen, keyboard and pointer. Screenshots and input need a VM with a display, so not one set to Headless.

Let agents make VMs

Start the server with --allow-create to add vm_create. The agent can make a VM from:

• a Linux image in the catalogue, such as ubuntu-26.04 or debian-13, set up by cloud-init with your account and SSH keys, as mvz create does, or
• a template you opened to agents, copied as it is.

It can't copy one of your VMs, or a template you didn't open. For macOS, sandbox_create copies only a macOS template you opened to agents, or a sandbox, by its exact name or id. A name another VM or template has is refused as taken. By default the new VM starts, and vm_create returns once it answers over SSH. The first VM from an image downloads the image first.

The agent controls the VMs it makes, and it can delete them with vm_delete. They go to the Trash, where you can put them back. The VM's Settings → AI Agents page says that an agent made it. Change its level there like any other VM's.

Making VMs needs a license or the trial, as it does in the app. Agents can keep using existing VMs without one. See Pricing.

Guardrails

• Off until you open it. Each VM starts closed to agents, and no tool can open one. Only you can, in the app or with mvz set.
• Copies start closed. A clone, a linked clone, a clone from a snapshot, an imported bundle and a VM made from a template don't inherit the setting. Converting a VM to a template, or a template to a VM, closes it too, and its entry in Tasks says so.
• Snapshots don't change it. Reverting to a snapshot keeps the VM's current level, so going back to an old snapshot never opens the VM, or closes it.
• Nothing starts by itself. The tools don't start, resume or wake one of your VMs. Only vm_power does, and only at Control. (A sandbox still starts when a tool needs it.)
• Rollbacks can be undone. The agent has to name the snapshot. MacVisor takes a safety snapshot of the current state first, named "Before revert" with the date and time, and reverts nothing if that fails. A VM keeps the latest two of these; older ones are deleted at the next rollback. Your own snapshots are never deleted.
• Off limits. Agents can't delete snapshots, change a VM's hardware, network, shared folders or agent settings, export or move VMs, read the passwords MacVisor keeps for macOS and Windows accounts, or touch your license. They can delete only the VMs an agent made.
• Logged. Every tool call on a VM or sandbox goes in the activity log, refusals included.

These limits apply to what agents do through MacVisor's MCP server. An agent that can also run commands on your Mac as you can run mvz itself, like any other program. To run an agent you don't trust, give it an AI sandbox and run it there, rather than on your Mac.

Treat everything that comes back from a VM as data, not as instructions. Command output, file contents and screenshots can contain text written to steer an agent.

Activity log

MacVisor logs each tool call that names a VM or sandbox: the time, the app that made it, the tool, the VM, whether it worked or was refused, and the command line or path. It never logs the text an agent types or the contents of a file. Only MacVisor's own tools are logged. Control characters show as ?, and long names are cut short.

mvz agents log                 # the latest 50
mvz agents log --lines 500 --json

A VM's Settings → AI Agents page shows its latest entries. The log stays on your Mac, in ~/Library/Application Support/MacVisor/ai/mcp-activity.jsonl.

Sandboxes or your own VMs?

A sandbox keeps an agent's own code and commands away from your Mac. Opening a VM lets an agent on your Mac work with the VMs you already have: reproduce a bug on a clean Ubuntu VM, try a change on macOS 26 and 27, or set up a cluster of VMs for a test and remove it afterwards.

Examples

Things you can ask an agent once it's connected:

• "Start ubuntu-dev, run the test suite in ~/src/api, and tell me what fails."
• "Take a checkpoint of staging, upgrade nginx, and roll back if the health check fails."
• "Make three VMs from debian-13 with k3s, join them into one cluster, and give me the kubeconfig." (needs --allow-create)
• "Open my app in the macos26-qa VM, go through the sign-up flow and send me screenshots of every step."

Limits

• The server runs on your Mac, for agents on your Mac. It has no network endpoint.
• Commands and files need SSH as MacVisor manages it: cloud-image Linux VMs and macOS VMs. Windows VMs get the screen and input only. Appliances and Linux VMs installed from an ISO get neither commands nor files.
• A Mac runs at most two macOS VMs at a time, Apple's limit.
• Keyboard input uses the US layout.