Cycle MCP

List Servers

list_servers

Read-onlyIdempotent

List the physical/virtual servers making up your Cycle infrastructure, grouped by cluster (Cycle uses clusters for physical isolation). Use to see what hardware exists, which cluster it belongs to, its provider and state, and the platform's view of its host agent (online, healthy, shutting_down, last_checkin; 'live' state alone does not mean reachable or healthy). hostname and nickname are matched as case-insensitive substrings, so a partial hostname is enough to find a specific server. cluster and state are exact filters applied by the Cycle API.

Each server also reports constraints: constraints.tags is the list of tags on that server, and constraints.allow.pool is true when the server accepts containers that specify no tags. Placement is driven by these SERVER tags — a container restricts itself to a subset of servers via its own config.deploy.constraints.node.tags (see deploy_application), and a Cycle cluster does NOT narrow placement on its own. Read tags here to confirm a tag exists before referencing it in a container constraint (set them with configure_server); note that if every server has allow.pool true, an unconstrained container can land on any of them.

Each server also reports 'virtualization': true means it can host virtual machines (see deploy_virtual_machine); absent means the capability is unknown (node stats unavailable). 'features' is the host configuration (base volume GB, ssh, sftp, gateway) and 'shared_file_systems' the shared directories and mounts (NFS etc.) the server exposes by identifier — the identifiers a container may mount via shared_file_systems; both are changed with configure_server. 'os' (kernel, CycleOS build), 'uptime', 'versions' (Cycle agent and compute) and 'drivers' are as of the node's last check-in.

EVERY cluster visible to the credential is listed, including clusters that hold no servers at all (count 0, empty servers list) — a cluster exists on Cycle independently of any hardware in it, so an empty cluster here is a real cluster awaiting servers, not a missing one. This is the authoritative list of what clusters exist.

Input Schema

Name	Required	Description
`state`	No	Only return servers currently in this state.
`cluster`	No	Exact cluster identifier to scope to. Clusters are Cycle's unit of physical isolation.
`context`	No	Why are you calling this tool? Briefly describe the user's goal.
`hostname`	No	Case-insensitive substring of a server hostname. A partial hostname is enough to locate a specific server.
`nickname`	No	Case-insensitive substring of a server's nickname (custom identification name).
`workloads`	No	Also return, per server, the instances placed on it (container, environment, state, configured CPU/RAM reserve and limit) plus virtual machines and environment service instances, and Cycle's allocation totals: reserved CPU shares and RAM against what the server can allocate. Use to see what runs where or whether a server has room. Costs several extra API calls per server, so narrow with hostname, nickname, or cluster; refused when more than 25 servers match.
`conversation_id`	No	Conversation 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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 7, 2026

changedInput schema / properties / workloads / description

Previous value: -"Also return, per server, the instances placed on it (container, environment, state, configured CPU/RAM reserve and limit) and Cycle's allocation totals: reserved CPU shares and RAM against what the server can allocate. Use to see what runs where or whether a server has room. Costs two extra API calls per server, so narrow with hostname, nickname, or cluster; refused when more than 25 servers match."New value: +"Also return, per server, the instances placed on it (container, environment, state, configured CPU/RAM reserve and limit) plus virtual machines and environment service instances, and Cycle's allocation totals: reserved CPU shares and RAM against what the server can allocate. Use to see what runs where or whether a server has room. Costs several extra API calls per server, so narrow with hostname, nickname, or cluster; refused when more than 25 servers match."

Changed1 schema field changedOct 7, 2026

addedInput schema / properties / workloads

Added value: +{
+  "description": "Also return, per server, the instances placed on it (container, environment, state, configured CPU/RAM reserve and limit) and Cycle's allocation totals: reserved CPU shares and RAM against what the server can allocate. Use to see what runs where or whether a server has room. Costs two extra API calls per server, so narrow with hostname, nickname, or cluster; refused when more than 25 servers match.",
+  "type": "boolean"
+}

First observedOct 6, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already mark this as read-only, idempotent, non-destructive, and open-world, but the description adds substantial context: empty clusters are real, 'live' state does not imply reachable or healthy, tag constraints drive placement, and workloads mode incurs extra API calls and is refused above 25 servers.

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 a clear purpose, then organized into paragraphs covering clusters, constraints, virtualization/features, and empty-cluster semantics. It is dense but largely earns its length given the complexity of the tool, though some details could be tightened.

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 carries the burden of explaining returned data and does so thoroughly: cluster grouping, constraints and tags, virtualization, features, shared file systems, OS/uptime/versions/drivers, and host-agent status. It also explains the important edge case of empty clusters.

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

Parameters4/5

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

Schema coverage is 100%, so the schema already documents each parameter. The description still adds useful semantics beyond the schema, such as case-insensitive substring matching for hostname and nickname, exact API filters for cluster and state, and the cost/refusal behavior of workloads.

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 and resource: list servers making up the Cycle infrastructure, grouped by cluster. It clearly distinguishes this from configuration and deployment tools by explaining that this is the authoritative view of existing hardware and clusters.

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

Usage Guidelines4/5

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

Gives clear use cases: inspect hardware, cluster membership, provider/state, host-agent status, and confirm tags before referencing them in container constraints. It names related tools like configure_server, deploy_application, and deploy_virtual_machine, though it does not explicitly contrast every sibling list tool.

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

All Cycle MCP tools Inspect

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

Need Help?