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.
Choose a key
Section titled “Choose a 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.
Connect your client
Section titled “Connect your client”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
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.”
What the agent is told
Section titled “What the agent is told”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.
- 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.
- The instance and its launch attempts: the runtime and storage logs of each time the instance was started.
- AppVM workload log: the last part of what the application in an AppVM wrote.
- Metrics and capacity: CPU, memory, disk and network history, and what the host has left.
- Host images: booted/staged images and the current or last upgrade operation, read-only. The tool does not report an authoritative rollback deployment.
- Recent diagnostics: up to 200 recent error-index entries, with stable codes and request correlation. This is an index, not raw session-only logs.
- Operations: classic VM creation returns an operation to follow until terminal. AppVM creation completes synchronously and boots by default; deletion completes synchronously.
- 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.
Adjust CPU and memory
Section titled “Adjust CPU and memory”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.
Capacity warnings and outcomes
Section titled “Capacity warnings and outcomes”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.
Safety
Section titled “Safety”- 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.
Security
Section titled “Security”- 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_statuscarries 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.
If the agent cannot connect
Section titled “If the agent cannot connect”| 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. |