MCP Server for Mac VMs: Give Claude Code a Virtual Machine of Its Own

Updated September 18, 2026. Kyvenza ships a local MCP server, so an MCP client such as Claude Code can drive real virtual machines on your Apple Silicon Mac — start them, snapshot them before touching anything, run shell commands inside the guest, and look at the screen. This guide covers turning it on, connecting a client, all fifteen tools, three worked examples, and the security model that makes handing a machine over a reasonable thing to do.

Quick answer (the 40-word version)

The Kyvenza MCP server turns your VM library into tools an AI agent can call. Turn it on in Settings → Automation, paste one URL into Claude Code, and the agent can clone a VM into a disposable sandbox, work inside it, and delete it afterwards — without ever reaching your Keychain, your SSH keys, or your real filesystem.

---

What the Kyvenza MCP server actually is

MCP — the Model Context Protocol — is the interface an AI client uses to call tools that live outside itself. Kyvenza implements the server half of that protocol as a small HTTP service inside the app. Switch it on and the app starts answering JSON-RPC on 127.0.0.1, publishing twelve tools by default and fifteen when you allow the destructive three.

What it is not is a chatbot inside a virtualization app. There is no chat window in Kyvenza, no model, no API key, and no per-token billing. The conversation stays in the client you already use, and Kyvenza is the machine that client talks to. The reasoning behind that split is written up on the Kyvenza MCP server page.

The feature shipped in Kyvenza 3.0 and is current as of 3.0.1. It is in every build — Mac App Store and direct download alike — and the 7-day trial includes it.

Why a virtual machine rather than a container or a folder sandbox

An agent that can run shell commands needs somewhere those commands cannot reach things you care about. The usual answers are a permission prompt, a container, or a restricted working directory. Each of them is a boundary your tooling promises to enforce.

A virtual machine is a boundary the operating system enforces. The guest has its own kernel, its own filesystem, and its own network stack. Nothing inside it can read ~/.ssh, unlock your Keychain, or reach a production credential that only exists on the host. If you are new to the model underneath this, What is a virtual machine is the background read.

A VM also gives you three things a container does not:

• A snapshot you can roll back to in seconds, which turns "the agent broke the machine" into a 10-second fix rather than a rebuild.
• A disposable clone that costs almost no disk, because Kyvenza clones copy-on-write — the copy appears in about a second and only consumes space as the guest writes.
• A network mode with no network in it, which no container runtime gives you as cleanly. Set a VM to isolated networking and it has no adapter at all.

Before you start

What you need	Why
Kyvenza 3.0 or later on an Apple Silicon Mac	The MCP server is new in 3.0. Both distribution channels include it, as does the trial.
At least one VM that already has an OS installed	create_vm produces an empty machine; installing an OS is interactive and cannot be driven through MCP. Create your first VM if you do not have one yet.
An MCP client that accepts an HTTP URL	Claude Code, Claude Desktop, and most other clients qualify. One URL is the whole credential.
The guest agent (Linux) or SSH details (macOS), if you want exec_shell	Listing, starting and snapshotting VMs works with nothing installed in the guest. Running commands inside one does not.

Turn the server on and connect a client

Step 1 — Switch on the server

Open Kyvenza → Settings → Automation and turn on Enable MCP Server. It is off until you do. The port field defaults to 59800 and accepts anything from 1024 to 65535; you have to stop the server before changing it.

Step 2 — Copy the address

Under Connect a Client there is an Address row holding the endpoint for this Mac:

http://127.0.0.1:59800/mcp/YOUR-TOKEN

That token is 128 bits of randomness, stored in your login Keychain, and generated per Mac. Treat the whole URL like a password — the section on the security model explains exactly what it is protecting you from.

Step 3 — Paste it into your client

For Claude Code, the settings page generates a one-line command:

claude mcp add --transport http kyvenza http://127.0.0.1:59800/mcp/YOUR-TOKEN

For clients that read a JSON configuration file, it generates the snippet too:

{
  "mcpServers": {
    "kyvenza": {
      "type": "http",
      "url": "http://127.0.0.1:59800/mcp/YOUR-TOKEN"
    }
  }
}

Kyvenza deliberately does not write these files for you. The app is sandboxed on both distribution channels, and editing a config file on your behalf risks breaking a file it does not own.

Step 4 — Verify before you trust it

Next to the snippets is a Test Connection button. It performs a real MCP handshake against your own endpoint and reports back Connected, 12 tools available — or 15 if you have allowed the destructive three. That answers "did I configure this correctly" immediately, instead of leaving you to discover it from a failed tool call twenty minutes later.

If you ever need to revoke access, Generate New Token… issues a fresh one. Every client you previously connected stops working until you give it the new address.

The fifteen tools

Twelve tools are available as soon as the server is running. Three more appear only when you allow them.

Tool and arguments	What it does
list_vms none	Every VM with its OS, status, CPU and memory
get_vm_status vm	Status, IP address, display resolution and network mode
get_vm_ip vm	The guest IP address of a running VM
start_vm vm	Start a stopped VM, taking a snapshot first
stop_vm vm, force	Stop a running VM, gracefully unless asked otherwise
restart_vm vm	Restart a running VM
suspend_vm vm	Write the guest's memory to disk and power off — Linux only
list_snapshots vm	The snapshots of a VM, marking which were automatic
take_snapshot vm, name	An offline snapshot of a stopped VM
restore_snapshot vm, snapshot	Put a stopped VM back to a snapshot, replacing the current disk
exec_shell vm, command, username, timeout	Run one command in the guest; returns exit code, stdout and stderr
screenshot vm, username	A PNG of the guest's screen
clone_vm 🔒 vm, ttlMinutes	Copy a stopped VM into a disposable sandbox
create_vm 🔒 name, os, cpuCount, memoryMB, diskSizeGB	A new, empty machine with no operating system on it
delete_vm 🔒 vm	Move a sandbox clone_vm made to the Trash

🔒 = off by default. exec_shell defaults to a 60-second timeout and accepts up to 600.

Why the destructive three stay hidden

create_vm, clone_vm and delete_vm do not merely refuse when the switch is off — they never appear in tools/list at all. A tool the model cannot see is a tool it will not try, which is a considerably stronger guarantee than declining the call afterwards.

Turn them on with Allow creating and deleting VMs in the same settings pane. Leave them off and an agent can only start, stop and snapshot the VMs you already have.

Walkthrough 1: hand an agent a disposable Linux sandbox

This is the workflow the whole feature is built around: an agent runs something you would rather not run on your Mac, in a machine that exists for twenty minutes.

Say you have a stopped Ubuntu VM called ubuntu-base with the Kyvenza guest agent installed — Kyvenza can attach the installer disc to the VM for you, or hand you the three commands to run over a shared folder. Ask your client something like:

Clone ubuntu-base into a sandbox, install this npm package inside it, run its post-install scripts, tell me every file it wrote outside the project directory, then throw the sandbox away.

The agent's tool calls come out roughly like this:

clone_vm   { "vm": "ubuntu-base", "ttlMinutes": 60 }
           → { "status": "created", "vm": "ubuntu-base-sandbox-1",
               "ephemeral": true, "expiresAt": "2026-09-18T15:04:05Z" }

start_vm   { "vm": "ubuntu-base-sandbox-1" }
           → { "status": "started",
               "autoSnapshot": "created: Before agent start 2026-09-18T14:04:05Z" }

exec_shell { "vm": "ubuntu-base-sandbox-1",
             "command": "npm install suspicious-package 2>&1 | tail -40",
             "timeout": 300 }
           → { "exitCode": 0, "stdout": "…", "stderr": "" }

exec_shell { "vm": "ubuntu-base-sandbox-1",
             "command": "find / -newer /tmp/mark -not -path '/proc/*' -type f" }

stop_vm    { "vm": "ubuntu-base-sandbox-1" }
delete_vm  { "vm": "ubuntu-base-sandbox-1" }
           → { "status": "deleted", "movedToTrash": true }

Three details worth noticing:

• The clone is near-instant and nearly free. Copy-on-write means the sandbox appears in about a second and occupies almost no disk until the guest starts writing.
• start_vm snapshotted first, and said so. The agent now knows the exact name to hand restore_snapshot if it wants to undo everything. Starting a VM yourself from the Kyvenza window does not do this — it is a safety net for automation, not a background disk filler.
• ttlMinutes is the cleanup you do not have to trust the agent to do. Sandboxes default to one day and cap at one week (10080). Kyvenza reclaims an expired sandbox on its own, and only while it is stopped, so an agent that forgets delete_vm does not leave you a library full of dead machines.

Walkthrough 2: check a build on real Windows 11 ARM

Test suites tell you the code passes. They do not tell you the installer looks right. For that, an agent needs to see a real Windows desktop — which it can, on a Windows 11 ARM VM:

start_vm   { "vm": "win11-test" }
exec_shell { "vm": "win11-test",
             "command": "powershell -c \"Start-Process .\\MyApp-Setup.exe -Wait\"" }
screenshot { "vm": "win11-test" }
           → PNG of the guest desktop

exec_shell on Windows goes over SSH on a port forwarded to loopback only, which requires running the Install-Kyvenza-Drivers installer once inside the guest — and that first run needs the VM to have internet access. The SSH username must be plain ASCII: OpenSSH refuses account names containing quotes, spaces or shell metacharacters, even though Windows itself allows them.

screenshot on Windows needs none of that. It is captured on the host side, so it works with nothing installed in the guest, no IP address, and no display window open. More on what does and does not work under Windows on Apple Silicon is on the Kyvenza Windows support page.

Walkthrough 3: a machine with the network unplugged

Set a Linux VM to isolated networking and it has no network adapter at all — get_vm_status will report it has no address. Nothing in the guest can phone anywhere. (Networking covers the shared and bridged modes you would use the rest of the time.)

The agent keeps working anyway. With the Kyvenza guest agent installed, exec_shell and screenshot travel over a virtual socket between host and guest rather than over a network, so they do not need an IP address at all. Screenshots come from the kernel framebuffer, which means they work even with no display server running.

That combination — an agent that can work in a machine, and code in that machine that cannot reach the internet — is difficult to assemble any other way. It is the same shape as the setups described in Run OpenClaw in a Linux VM and Run OpenClaw safely on a Mac, with the agent now driving the machine rather than living inside it.

The security model

Five things do the work here, and one of them is not decoration.

1. The server never leaves the loopback interface. It binds 127.0.0.1 and nothing else. No device on your network can see it; neither can anything on the internet.

2. Every Mac has its own token, and it is required. This is the one that deserves specifics, because the threat is real rather than theoretical. QEMU's user-mode networking translates anything a guest sends to 10.0.2.2 into a connection to the host's loopback interface. A running guest can therefore reach services bound to 127.0.0.1 on your Mac — including this one. So the endpoint carries a 128-bit token, in the URL path or an Authorization: Bearer header, and a request without it gets a 401 and nothing else. There is no compatibility mode that turns this off.

3. The tools that destroy things are off by default, and hidden rather than merely refused, as described above.

4. delete_vm only deletes what it made. The test is an internal disposable marker, not a name prefix or a tag, so a VM you have kept for months cannot be caught by a mistaken call. What it does delete goes to the Trash rather than being erased — a copy-on-write clone takes almost no space there, and an agent deleting the wrong thing needs to be undoable.

5. A snapshot before the agent starts anything. On by default, keeping the last 3 automatic snapshots (1, 3 or 5 are the choices), named Before agent start <timestamp>, and overridable per VM. Snapshots you took yourself are never pruned. If the snapshot fails for any reason, the VM still starts and the tool response says what happened — an agent should never hit "the interface can start this VM but MCP cannot".

You can review all of these in Settings → Automation; the Settings guide covers the rest of the pane.

What it does not do

Stating the limits plainly is cheaper than having you discover them:

• create_vm gives you an empty machine. Installing an operating system is interactive and cannot be driven through MCP. clone_vm from a prepared VM is the tool that actually matters.
• Running commands inside Windows requires the driver installer to be run once inside the guest, and that first run needs the VM to have internet access.
• Windows SSH usernames must be plain ASCII.
• Snapshots through MCP are disk-only and require the VM to be stopped. Saving the memory of a running machine stays a manual action in the app.
• suspend_vm is Linux-only. Use stop_vm for macOS and Windows guests.
• Screenshots of a macOS guest need a graphical session somebody has signed into.

Troubleshooting

Symptom	Cause	Fix
Client reports 401 or "unauthorized"	The address lost its token, or you regenerated it	Copy the Address row again from Settings → Automation and update the client
Client connects but sees only 12 tools	Destructive tools are off	Turn on Allow creating and deleting VMs, then reconnect — clients cache the tool list
clone_vm says the VM must be stopped	Cloning is offline only	stop_vm the source first
exec_shell fails on a Windows guest	Driver installer never run, or a non-ASCII username	Run Install-Kyvenza-Drivers inside Windows once, with the VM online, and use an ASCII account name
screenshot fails on a macOS guest	No signed-in graphical session	Sign in to the guest desktop, or use a Linux guest with the agent
delete_vm refuses	The VM is a regular one, not a sandbox	Delete it yourself from the Kyvenza window if that is what you meant
Port will not change	The server is running	Stop the server, change the port, start it again

More diagnostic paths are in the Diagnostics and troubleshooting guide.

Frequently asked questions

Does this cost anything per call? No. Kyvenza makes no model calls and has no API key. Whatever you pay for inference, you pay to your MCP client's provider. Kyvenza itself is a one-time $49 purchase, and the trial includes the MCP server.

Can I use a client other than Claude Code? Yes. The endpoint is Streamable HTTP MCP, and the credential is the URL itself, so any client that accepts a URL can connect. The settings page generates the generic mcpServers JSON for clients that read a config file.

Can two clients connect at once? Yes — they share the same endpoint and the same token. Bear in mind they also share the VMs: two agents starting and stopping the same machine will interfere with each other.

Is anything sent to Kyvenza's servers? No. The server is local, binds loopback, and the tools operate on VMs on your own disk.

What happens if the agent bricks the guest? Restore the snapshot start_vm took — its name is in that tool's response — or, if it was a sandbox, delete it and clone a fresh one. That is the entire reason the sandbox workflow exists.

Where to go next

• The Kyvenza MCP server page — the feature overview, in three languages.
• Managing VMs — lifecycle actions, configuration and storage, from the interface side.
• Networking — shared and bridged modes, and finding a guest's IP address.
• Settings — the rest of the Automation pane.
• Run OpenClaw in a Linux VM · Run OpenClaw in a macOS VM — putting an agent inside a guest, the complement to driving one from outside.
• Windows 11 ARM VM on Mac — the Windows guest walkthrough.
• How to make a virtual machine — if you still need the machine the agent will work in.
• Download Kyvenza — 7-day trial, MCP server included.