Skip to main content
Glama

Cycle MCP

by io.cycle.mcp.na
OverviewDiscussionsAdmin

Run a Command on a Virtual Machine

run_vm_command
Destructive

Run a shell command on a running virtual machine over its serial-over-SSH console, and return the console output. Use this for one-time in-guest setup — e.g. partitioning and formatting an attached data volume, then mounting it, or configuring networking.

The VM must be RUNNING (start it with cycle_control_virtual_machine first). This connects to the guest's SERIAL CONSOLE through the Cycle gateway — it does not use the VM's network — and logs in with the guest's own credentials: username defaults to 'root', and the password defaults to the VM's generated root password when that is still retrievable (~10 minutes after creation). After that window you MUST pass 'password' (and 'username' if not root); this tool never guesses or stores credentials. If nobody has the guest password any more, reconfigure_virtual_machine can set a new one. Because a serial console is a real tty, the guest echoes input, so the returned output includes some command echo — read it as a console transcript, not clean stdout.

This runs an arbitrary command as root inside the guest — it is powerful and mutating. Always call with preview:true first: it echoes the target and command and makes NO connection, so the user can confirm intent. Confirm with the user, then call again without preview. Never run a command without explicit confirmation. Make destructive commands idempotent where possible.

Serial credentials are minted for the run and expired immediately after. For a human who wants to drive their own interactive session instead, use get_vm_console_access — it returns an ssh command they run themselves; this tool is for programmatic one-shot commands.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
commandYesShell command to run in the guest, e.g. 'mkfs.ext4 /dev/vdb && mkdir -p /mnt/data && mount /dev/vdb /mnt/data'.
contextNoWhy are you calling this tool? Briefly describe the user's goal.
previewNoWhen true, echo the target + command and make NO connection. Use it to confirm intent with the user. Always run this first.
passwordNoGuest login password. Optional while the VM's generated root password is still retrievable (~10 min after creation); required after that, or when logging in as a non-root user with a different password.
usernameNoGuest login username. Defaults to 'root'.
environmentYesEnvironment the VM lives in.
conversation_idNoConversation tracking id. Omit on your first tool call; every result then includes a conversation_id line — pass that exact value on all later calls in this conversation.
timeout_secondsNoMax seconds to wait for login plus command, 1-60 (default 45). 60 is the ceiling because a longer block dies at the MCP transport before this tool can report. A genuinely slow command (e.g. mkfs on a large volume) may outlast the wait — it keeps running in the guest, so re-run a cheap check command afterwards to confirm it finished rather than raising the timeout.
virtual_machineYesVM to run on.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive/openWorld/non-idempotent, and the description adds substantial context beyond them: the serial-console transport (not the VM network), credential minting and immediate expiry, the ~10 minute window for the auto-generated root password and the need to pass password/username after that, and the fact that the returned text is an echoed console transcript rather than clean stdout.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then safety, then credentials, then the alternative — a logical progression. It is on the long side and repeats the ~10 minute password window and the preview instruction that already appear in the schema, which is mild redundancy rather than waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fills that gap by explaining that the return value is an echoed console transcript, and it covers the prerequisites, credential lifecycle, timeout ceiling rationale (60s MCP transport limit and re-checking after a slow command), and the preview-confirm flow. An agent has everything needed to invoke it safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all nine parameters, including preview, password, timeout_seconds and conversation_id. The description largely restates the credential-window and timeout behavior already present in the schema; it adds little parameter-level meaning that isn't there, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+mechanism: run a shell command on a running VM over its serial-over-SSH console and return console output. It also names the scope (one-time in-guest setup) and implicitly separates itself from siblings like run_instance_command (containers/instances) and get_vm_console_access (interactive human sessions).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use (one-time in-guest setup such as partitioning/mounting a volume, configuring networking), prerequisites (VM must be RUNNING; start it with cycle_control_virtual_machine first), a required confirmation workflow (preview:true first, then call again), and an explicit alternative for the human-interactive case (get_vm_console_access).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Cycle MCP toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources