Skip to content

Connect an AI agent (MCP)

Updated

Every Virtainer Free host serves a built-in Model Context Protocol endpoint at http://<host>/mcp. Point your own AI agent at it and the agent can answer “why is this broken?” from the host’s own evidence, look things up in this documentation, and, if you allow it, create instances, adjust their CPU and memory, send power actions and delete them.

The agent signs in with an API key, so it can do exactly what that key can do over the REST API, and nothing more. Every action it takes goes through the same checks and lands in the same audit trail as any other request made with that key.

Create a key on Keys → API keys → Create key (see API keys). The access level you pick is the agent’s access level:

Access The agent can
Read-only Read host status, host-image status, the diagnosis, recent diagnostic events, instances, launch attempts and their logs, AppVM workload logs, metrics, capacity, images, networks, operations and the user docs. It cannot change anything.
Operate instances Everything above, plus create classic VMs and AppVMs, adjust instance CPU and memory, boot, shut down, reboot, pause, resume or press the power button, and delete instances.

Start with a read-only key. Give an agent an Operate instances key only when you want it to make changes, and consider a short lifetime and a source restriction (the IP address of the machine the agent runs on).

API keys cannot change host configuration, networks, storage, settings or host images, run factory reset, open a console or shell inside an instance, or manage API keys. CPU and memory adjustments use a resource-only route; general instance configuration, disks, PCI devices, networks, secrets and hot-add ceilings remain outside the key’s permissions. Those stay in the web interface.

After you create a key, the dialog that shows it once also shows a ready-to-paste configuration for Claude Code, Cursor and VS Code with the key filled in. The Connect an AI agent panel on the API keys page shows the same snippets with a placeholder.

Claude Code

Terminal window
claude mcp add --transport http virtainer http://<host>/mcp \
--header "Authorization: Bearer <your API key>"

Cursor (~/.cursor/mcp.json)

{
"mcpServers": {
"virtainer": {
"url": "http://<host>/mcp",
"headers": { "Authorization": "Bearer <your API key>" }
}
}
}

VS Code (.vscode/mcp.json in your workspace)

{
"servers": {
"virtainer": {
"type": "http",
"url": "http://<host>/mcp",
"headers": { "Authorization": "Bearer <your API key>" }
}
}
}

Use an MCP Streamable HTTP client supporting 2025-06-18, 2025-11-25 or 2026-07-28. The URL is exactly http://<host>/mcp (lowercase, no trailing slash), and every request carries Authorization: Bearer <your API key>. Initialization negotiates a supported revision; subsequent requests carry the negotiated MCP-Protocol-Version header. Modern per-request metadata and header requirements remain those of the negotiated revision.

Clients limited to 2025-03-26 or earlier are no longer supported. An older initialization request can negotiate a supported newer revision, but the client must then use that revision. Requests without a version header after initialization are refused. Each POST contains one message: batches are explicitly rejected. OAuth discovery is not provided; use the API-key configuration above.

Then ask the agent something, for example: “Why does the instance web-1 not start?” or “List the instances that are stopped and how much memory each one has.”

When the client connects, the host tells the agent how to troubleshoot this product: ask the host first, in this order, before reaching for a shell on the host.

  1. Diagnosis: the host’s own findings, each with a verdict, the evidence and a suggested action. This is the same list as the Diagnosis tab of Logs & Diagnostics.
  2. The instance and its launch attempts: the runtime and storage logs of each time the instance was started.
  3. AppVM workload log: the last part of what the application in an AppVM wrote.
  4. Metrics and capacity: CPU, memory, disk and network history, and what the host has left.
  5. Host images: booted/staged images and the current or last upgrade operation, read-only. The tool does not report an authoritative rollback deployment.
  6. Recent diagnostics: up to 200 recent error-index entries, with stable codes and request correlation. This is an index, not raw session-only logs.
  7. Operations: classic VM creation returns an operation to follow until terminal. AppVM creation completes synchronously and boots by default; deletion completes synchronously.
  8. These docs: the user documentation is built into the host, so it always matches the version you run.
Tool What it does Access
host_status Host name, uptime, CPU, memory, swap and disk usage, temperature, versions, agent build and executable (agent_from_image shows whether it is the image’s own binary) Read-only
host_image_status Booted/staged host images and current or last upgrade operation; no changes Read-only
list_diagnostics Up to 200 recent error-index entries and request correlation; no raw logs Read-only
get_diagnosis The host’s findings with evidence and suggested actions Read-only
list_instances, get_instance Instances, their configuration and state Read-only
list_instance_attempts, get_instance_attempt Launch attempts and their logs Read-only
get_instance_logs AppVM workload log Read-only
get_instance_metrics Metrics history; an unknown id returns empty points, not a not-found error Read-only
get_capacity Host capacity and what instances use of it Read-only
list_images, list_networks What you can create instances from and attach them to Read-only
list_operations, get_operation Background work and its outcome Read-only
search_docs, read_doc Search and read this documentation Read-only
create_vm Create a classic VM asynchronously; follow the returned operation Operate instances
create_appvm Create an AppVM synchronously; auto_boot defaults to true Operate instances
set_instance_resources Change CPU and/or memory using the current instance revision; existing stopped/live restrictions apply Operate instances
instance_power Boot, shut down, reboot, pause, resume, power button Operate instances
delete_instance Delete synchronously (HTTP 204); independent AppVM data volumes survive Operate instances

A read-only key does not see the five write tools at all.

create_vm defaults auto_boot to false and returns HTTP 202 with an operation. create_appvm returns HTTP 201 with id, mode, image_id and booted, plus optional warnings; set auto_boot: false to create without booting. AppVM workload fields are flat arguments, not nested under workload. Data volumes are objects such as {"size_gib": 10, "mountpoint": "/data"}, not console strings. Use the advertised schema for all accepted fields, limits and defaults; REST performs the authoritative business validation. Unknown top-level arguments are rejected.

Read get_instance immediately before changing resources and use its current positive revision. Call set_instance_resources with the instance id, that revision, and at least one of vcpus or memory_mb. For example, these tools/call parameters request 4 vCPUs and 4096 MB using a revision just read as 7:

{
"name": "set_instance_resources",
"arguments": { "id": "web-1", "revision": 7, "vcpus": 4, "memory_mb": 4096 }
}

A stale revision is refused. Read the instance again and review its latest configuration before retrying. The tool uses PATCH /api/instances/{id}/resources; a successful response is HTTP 200 with the updated instance fields and optional warnings. It does not boot the instance.

  • Stopped instances: adjust CPU and memory before the next start.
  • Running classic VMs: grow within the hot-add ceilings they booted with, when live hot-add was configured. See Add CPU and memory live.
  • Shrinking or changing an AppVM’s resources: stop the instance first.

Only CPU and memory are accepted. This tool cannot change hot-add ceilings, disks, PCI devices, networking, secrets or any other configuration. A read-only key cannot use it, and an Operate instances key still cannot use the general configuration endpoint.

Successful create_vm, create_appvm and resource growth can include a warnings array, each entry containing code and message; it is omitted when there are no warnings. The original operation or instance fields stay at the top level alongside it.

RESOURCE_OVERCOMMIT warns that configured CPU or memory commitments exceed the host’s physical resources. RESOURCE_CAPACITY_UNKNOWN says that capacity could not be verified. These warnings are advisory; simultaneous demand can slow or exhaust the host. Existing admission, resource bounds, revision and lifecycle checks still apply. Read the warning before starting more work or increasing allocations.

For classic creation, keep following the HTTP 202 operation with get_operation. For AppVM creation, HTTP 201 and booted describe the synchronous creation result. After a start or live growth, use get_instance, launch attempts, metrics and relevant workload logs to check the running machine and application; acceptance or an operation result alone does not establish that the workload is healthy or that a guest has brought every new resource online.

Log tools default to the last 32768 raw bytes per log; tail_bytes accepts 1024–40960. Each tool’s text has a 40 KiB budget with explicit omissions; result metadata and the JSON-RPC envelope add bytes outside that text. A log’s [N earlier bytes omitted] marker counts the bytes left out of the original log. search_docs accepts at most 1024 characters and 32 distinct normalized words; limit is 1–20 (default 8). Inner REST errors retain their HTTP status and request_id. Single-REST tool results carry _meta["virtainer/request_id"]; host_image_status carries _meta["virtainer/request_ids"], keyed by status and operation for its two reads. Local document tools and validation errors before an inner request have no inner REST id. Use the available correlation with list_diagnostics before resorting to shell access.

  • Deleting an instance and shutting it down (a hard stop, like pulling the power) both need a confirmation phrase: the instance’s id. The tool description says so, and your client’s approval prompt shows the phrase the agent is about to send. A wrong phrase is refused by the host.
  • Most MCP clients ask you before running a tool that changes something. Keep that on for an Operate instances key.
  • Every change the agent makes is recorded in the host’s audit trail under the API key that made it. Revoking the key stops the agent immediately.
  • Every MCP HTTP response includes an outer x-request-id, build identity and the same security headers as the REST API. Tool results from inner REST requests carry the corresponding id in _meta["virtainer/request_id"] (REST errors also name it in their first line); host_image_status carries both ids in _meta["virtainer/request_ids"]. Local document tools and validation failures before an inner request use outer correlation only.
  • The endpoint accepts API keys only. A browser session does not work on /mcp, and requests sent from a web page are refused.
  • Virtainer Free serves plain HTTP. Like every API request to the host, the key travels unencrypted over your local network. Use the agent from a network you trust, restrict the key to the agent’s IP address, and give it a lifetime.
What you see Why What to do
JSON-RPC -32700 / -32600 / -32602 Malformed JSON, an invalid envelope/id, or invalid parameters. A request sent without an id (only notifications/* may omit it) also gets -32600. Correct the message and use the advertised tool schema; these errors do not imply a successful write.
HTTP 400 unsupported protocol version The client uses an excluded revision or omits the negotiated version header. Upgrade/configure the client for a supported revision.
404 near /mcp or under /.well-known/ Wrong endpoint spelling/trailing slash, or OAuth discovery. Use exactly /mcp with an API-key bearer header.
401 Unauthorized The key is missing, mistyped, revoked or expired, or the request comes from an address outside the key’s source restriction. Check the header and the key’s row on the API keys page (status and “last used from”).
A tool you expect is missing The key is read-only. Create an Operate instances key if the agent should make changes.
403 Forbidden on /mcp The request carries an Origin header, as requests from a web page do. Connect from an MCP client, not from a browser page.
search_docs and read_doc are missing This host build was made without the documentation snapshot. Use this website instead; the other tools are unaffected.