lunanode-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@lunanode-mcplist my virtual machines"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
lunanode-mcp
MCP server for the LunaNode VPS API.
Features
43 tools covering VMs, images, volumes, floating IPs, SSH keys, and plans/regions.
Tiered safety gating: read operations are always available; write and delete operations must be explicitly enabled.
Related MCP server: timeweb-mcp-server
Configuration
Set these environment variables:
Variable | Required | Description |
| Yes | Your LunaNode API ID. |
| Yes | Your LunaNode API key (128 characters). |
| No | Enables write-tier tools. Unset = off. |
| No | Enables delete-tier tools. Unset = off. |
Read-tier tools are always enabled. Enabling writes does not imply deletes — each tier is gated independently.
Using a .env file
Instead of putting credentials in your MCP client config, you can keep them in a .env file and load it with Node's built-in --env-file flag (Node 20.6+). Copy .env.example to .env (git-ignored), fill in your values, and restrict access with chmod 600 .env. Full-line and inline # comments are supported.
{
"mcpServers": {
"lunanode": {
"command": "node",
"args": [
"--env-file=/path/to/lunanode-mcp/.env",
"/path/to/lunanode-mcp/dist/index.js"
]
}
}
}The smoke test can use the same file: npx tsx --env-file=.env scripts/smoke.ts
Client setup
Example configuration for Claude Code / Claude Desktop:
{
"mcpServers": {
"lunanode": {
"command": "npx",
"args": ["-y", "github:Burntberry/lunanode-mcp"],
"env": {
"LUNANODE_API_ID": "your-api-id",
"LUNANODE_API_KEY": "your-128-char-api-key",
"LUNANODE_ENABLE_WRITES": "true",
"LUNANODE_ENABLE_DELETES": "vm_delete,volume_delete"
}
}
}
}Tool reference
Read tools (always enabled)
Tool | Description |
| List all virtual machines on the LunaNode account. |
| Get detailed configuration and live status for a virtual machine. |
| List all IP addresses assigned to a virtual machine. |
| List images available to the account, optionally filtered by region. |
| Get metadata for a specific image. |
| List block storage volumes, optionally filtered by region. |
| Get details for a specific volume. |
| List volume snapshots in a region. |
| List all floating IPs on the account. |
| List stored SSH public keys with their IDs. |
| List available LunaNode VM plans with pricing, CPU, RAM, storage, and regional availability. |
| List all LunaNode regions where services can be deployed. |
Write tools (require LUNANODE_ENABLE_WRITES)
Tool | Description |
| Provision a new virtual machine. Requires a hostname and plan_id; boot from image_id or volume_id. |
| Perform a VM state action: start, stop, reboot, diskswap, rescue, shelve, or unshelve. |
| Reinstall a VM from an image. Destroys the VM's current disk contents. |
| Change a VM's plan (CPU/RAM/storage). |
| Change a VM's hostname label. |
| Create a disk image snapshot of a VM. |
| Generate a temporary noVNC console URL for a VM. Grants console access, so it is write-gated. |
| Attach a floating (public) IP to a VM. |
| Allocate an additional internal IP address on a VM. |
| Add a VM to an existing security group. |
| Remove a VM from a security group. |
| Add a new image by fetching it from an HTTP, HTTPS, or FTP URL. |
| Copy an image to another region. |
| Change an image's label. |
| Create a block storage volume, optionally pre-populated from an image or snapshot. |
| Attach a volume to a virtual machine. |
| Detach a volume from its virtual machine. |
| Increase the size of an unattached volume. |
| Change a volume's label. |
| Take a snapshot of a volume. |
| Convert a volume snapshot into an image, optionally in another region. |
| Provision a new unattached floating IP in a region. |
| Store an SSH public key for provisioning VMs with key-based authentication. |
Delete tools (require LUNANODE_ENABLE_DELETES)
Tool | Description |
| Permanently delete a virtual machine. |
| Remove an internal IP address from a VM. |
| Detach a floating IP from a VM. By default the IP is destroyed; set keep to retain it unattached. |
| Permanently delete an image. |
| Permanently delete a volume. |
| Permanently delete a volume snapshot. |
| Release an unattached floating IP from the account. |
| Delete a stored SSH key. |
Development
npm install
npm test
npm run build
npm run smoke # needs real LunaNode credentialsAPI keys
API keys are created in the LunaNode panel under API. See https://www.lunanode.com/api/overview for details.
Available Tools
12 toolsfloating_ip_listA
List all floating IPs on the account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. 'List' implies a read-only operation, and 'on the account' clarifies scope. However, it does not state any potential permissions, rate limits, or whether the operation is safe/read-only beyond the inherent meaning of 'list.' It is minimally adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and resource. There is no wasted wording or redundancy, making it perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with no output schema, the description is largely complete. It specifies what is listed and the scope. However, it does not describe the format or fields of the returned list, which might be useful since no output schema is provided. Still, for a simple list, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the schema has no properties, so schema coverage is effectively 100%. The baseline for zero parameters is 4, and the description adds no parameter information because none exists. This is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('list') and resource ('floating IPs'), and specifies the scope ('on the account'). This distinguishes it from sibling tools like vm_iplist, which might focus on VM IPs, and vm_list, which lists VMs. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any exclusions. While the name and description imply usage for viewing floating IPs, there is no explicit comparison with sibling tools (e.g., vm_iplist) or edge cases where another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
image_detailsA
Get metadata for a specific image.
| Name | Required | Description | Default |
|---|---|---|---|
| image_id | Yes | Image identifier |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It only states 'Get metadata' without specifying what metadata is returned, potential errors (e.g., image not found), or any read-only guarantees. This is a minimal disclosure that lacks useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It is appropriately sized for a simple tool, though the brevity leaves out behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one well-documented parameter, but the absence of an output schema and annotations means the description does not clarify the return format or edge cases. It is minimally viable but has gaps that could affect correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'image_id', which is described as 'Image identifier'. The tool description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get metadata for a specific image' uses a specific verb and resource, and the word 'specific' distinguishes it from sibling tools like image_list, which lists images. It clearly indicates this is a detail retrieval for a single image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for a specific image' implies usage when you have an image identifier and need details, versus listing all images with image_list. The context is clear, though no explicit alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
image_listA
List images available to the account, optionally filtered by region.
| Name | Required | Description | Default |
|---|---|---|---|
| region | No | Region name to filter by |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry full behavioral disclosure. It communicates that the operation is a read-only list scoped to the account, but does not elaborate on return format, pagination, or filtering behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence of 9 words, front-loaded with the action. There is no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description adequately conveys the tool's purpose and scope. It could mention what fields are returned, but that is not critical for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the sole 'region' parameter as a filter by region name. The description restates this filter but adds no further semantic detail, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists images available to the account, with an optional region filter. It uses a specific verb (List) and resource (images), distinguishing it from sibling tools like image_details which likely fetches a single image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for enumerating account images, optionally scoped to a region. It does not explicitly contrast with sibling tools like image_details or region_list, but the context is clear enough for basic use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
plan_listA
List available LunaNode VM plans with pricing, CPU, RAM, storage, and regional availability.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states the action (list) and output content, but does not explicitly disclose that it's a read-only operation or mention any potential side effects, authentication requirements, or pagination behavior. It's adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, and every word adds value. It is concise without missing key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter list tool with no output schema, the description sufficiently covers what the agent needs: the action, resource, and the content of the return (pricing, CPU, RAM, storage, regional availability). No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers everything (coverage 100%). The description adds no parameter information because none exist. Baseline for 0 params is 4, and no compensation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and clearly identifies the resource 'available LunaNode VM plans', specifying key attributes (pricing, CPU, RAM, storage, regional availability). This distinguishes it from sibling tools like region_list or vm_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when needing plan details) but provides no explicit guidance on alternatives or exclusions. It doesn't mention when not to use it or point to other tools for related queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
region_listA
List all LunaNode regions where services can be deployed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly indicates a read-only 'list' operation, but offers no additional behavioral context such as response format, pagination, or error handling. The term 'List' is sufficient to infer no side effects, but no deeper traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that is front-loaded with the key verb and resource. Every word adds value, and there is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless list tool, the description is mostly complete: it states what is listed and the criterion ('where services can be deployed'). However, without an output schema, it could be slightly more explicit about what the returned list contains (e.g., region IDs/names), but this is a minor gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema is empty. The description need not explain parameter semantics, making the baseline 4. No additional parameter information is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('List'), a specific resource ('LunaNode regions'), and a concrete scope ('where services can be deployed'). This distinguishes it from sibling tools that focus on VMs, images, volumes, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you need a list of regions for deploying services. It provides clear context and no exclusions, though it doesn't explicitly mention alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ssh_key_listA
List stored SSH public keys with their IDs.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not explicitly state that the operation is read-only, but 'List' implies a non-destructive read. It also does not disclose authentication requirements, pagination, or return format beyond mentioning IDs, though for a simple 0-param list tool this is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the action and object. It is concise, with no wasted words or filler, and earns every word's place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter list tool with no output schema, the description covers the core functionality and the returned ID field. While it could mention whether all keys are returned or the ordering, the tool's simplicity means the description is essentially complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty (100% coverage). Per the rubric, a baseline of 4 applies when there are no parameters, and the description need not explain parameter semantics. The description adds no parameter details, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with a clear resource ('SSH public keys') and scope ('stored'), and even specifies the output includes IDs. This makes the tool's function unmistakable and distinguishes it from sibling tools listing VMs, images, volumes, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving SSH public key IDs, and the resource name makes it obvious when to use it, but it does not explicitly state when to use it versus alternatives or provide any exclusions. There is no mention of, for example, 'use this instead of vm_list for SSH key operations.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
vm_infoA
Get detailed configuration and live status for a virtual machine.
| Name | Required | Description | Default |
|---|---|---|---|
| vm_id | Yes | VM identifier |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. The verb 'Get' implies a read operation, but there is no disclosure of potential errors, authentication requirements, rate limits, or the structure of the returned data. The description only states the basic action without additional behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action ('Get'). Every word contributes to understanding the tool's purpose without unnecessary fluff. It is highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the lack of an output schema, the description indicates the kind of information returned ('configuration' and 'live status'). For a simple one-parameter tool, this is largely sufficient. It could be more explicit about the exact fields, but overall it provides adequate context for an agent to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, as the vm_id parameter includes a description ('VM identifier'). The description adds nothing beyond this, but with full coverage the baseline of 3 applies. The description does not clarify the format or constraints of vm_id, but the schema already handles that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Get') and resource ('detailed configuration and live status for a virtual machine'). It clearly distinguishes from sibling list tools like vm_list and vm_iplist, which focus on listing VMs or IPs rather than detailed info for a single VM.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving info about a specific VM, but it does not explicitly provide context on when to use this tool over alternatives, nor does it mention when not to use it. There is no exclusion or mention of sibling tools, leaving usage guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
vm_iplistA
List all IP addresses assigned to a virtual machine.
| Name | Required | Description | Default |
|---|---|---|---|
| vm_id | Yes | VM identifier |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the action but does not disclose any behavioral traits such as whether it returns both public/private IPs, error handling, or that it is a read-only operation (though 'list' implies it).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that efficiently conveys the tool's purpose without unnecessary words. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter, the description adequately states what it returns, but it does not address output format or potential exclusions (e.g., floating IPs). Given the absence of output schema and annotations, some additional context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes vm_id as 'VM identifier' with 100% coverage. The description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'list' and identifies the resource 'IP addresses assigned to a virtual machine', clearly distinguishing it from sibling tools like vm_list and vm_info. It is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is clear enough to imply usage when needing a VM's IP addresses, but there is no explicit guidance about when to use this tool versus alternatives like floating_ip_list or vm_info, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
vm_listA
List all virtual machines on the LunaNode account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'list all', which implies a read-only operation, but does not disclose return format, pagination, rate limits, or any side effects. This is minimal and leaves gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that fully states the tool's purpose without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (no parameters, no output schema, no annotations), the description is minimally adequate but lacks details about the return structure or any caveats. It is sufficient for a simple list operation but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are 0 parameters, so the baseline is 4. The description adds no parameter details because there are none to describe, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a specific resource 'all virtual machines on the LunaNode account', clearly distinguishing it from sibling tools like vm_info (specific VM details) and vm_iplist (IPs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you need a list of all VMs. It provides clear context without explicitly naming alternatives, but the purpose is unambiguous enough for an agent to select appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
volume_infoA
Get details for a specific volume.
| Name | Required | Description | Default |
|---|---|---|---|
| volume_id | Yes | Volume identifier |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Get details' without specifying what details are returned, whether the operation is read-only, or how errors are handled. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence with no wasted words. It is front-loaded and appropriately sized for a simple single-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is minimally adequate. It clearly states the action, but does not elaborate on what 'details' includes. Given the low complexity, it is sufficient, though slightly more context could enhance usability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes volume_id with 100% coverage ('Volume identifier'), so the baseline is 3. The description does not add extra meaning beyond the schema, but none is needed for this simple parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('details for a specific volume'), clearly distinguishing it from sibling tools like volume_list, which would list volumes. It unambiguously states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when a single volume's details are needed, but it does not explicitly mention alternatives or when not to use it. While the context is fairly clear, it lacks explicit exclusions or references to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
volume_listA
List block storage volumes, optionally filtered by region.
| Name | Required | Description | Default |
|---|---|---|---|
| region | No | Region name to filter by |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It indicates a read-only list operation, but offers no additional details about authentication requirements, pagination, ordering, or the shape of the response. This is adequate for a simple list but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear, front-loaded sentence with no wasted words. It effectively conveys the core functionality in minimal space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description is reasonably complete. However, it does not indicate what fields are returned for each volume (e.g., IDs, sizes, names), which could be ambiguous without an output schema. The absence of any caveats or return format details leaves a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the region parameter described as 'Region name to filter by'. The description repeats this with 'optionally filtered by region', adding little beyond the schema. The optionality is communicated, but no additional nuance is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (List) and resource (block storage volumes), with an optional region filter. It effectively distinguishes itself from siblings like volume_info (which likely retrieves details for a single volume) and volume_snapshot_list (which lists snapshots rather than volumes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes the region filter, implying when to use it (e.g., to narrow results by region), but provides no explicit guidance on when to use this tool versus alternatives like volume_info or volume_snapshot_list. Usage is inferred from the tool's name and sibling context rather than explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
volume_snapshot_listB
List volume snapshots in a region.
| Name | Required | Description | Default |
|---|---|---|---|
| region | Yes | Region name |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only states the action 'List' without disclosing whether the operation is read-only, whether it requires special permissions, or what the return format is. This is a minimal behavioral disclosure, no more than the tool name implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no fluff. It is front-loaded and appropriately sized for a tool with one parameter. It could be slightly more informative, but as concise phrasing it works well.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one required parameter and no output schema, so a brief description may suffice. However, it lacks any context about return behavior, pagination, or operational notes. It is minimally viable but leaves the agent without additional context to handle edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the 'region' parameter, so the schema already defines it. The tool description adds no extra meaning beyond restating 'in a region', which is redundant. Baseline 3 applies because the schema handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'volume snapshots' and a scope qualifier 'in a region'. This distinguishes it from sibling tools like volume_list or volume_info, which address volumes but not snapshots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to list volume snapshots for a region, but it provides no explicit guidance on when to choose this over alternatives or any exclusions. The context is minimal and relies on the tool name to convey intent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
12 tool updates
v0.1.0- First observed
floating_ip_list - First observed
image_details - First observed
image_list - First observed
plan_list - First observed
region_list - First observed
ssh_key_list - First observed
vm_info - First observed
vm_iplist - First observed
vm_list - First observed
volume_info - First observed
volume_list - First observed
volume_snapshot_list
TDQS
Scored across 12 tools
Each tool targets a distinct resource and action, such as listing all VMs vs. getting details for a single VM vs. listing IPs. There is no overlap or ambiguity in what each tool returns.
All tools follow a consistent snake_case pattern of resource-based nouns with descriptive suffixes like _list, _info, and _details. Minor variations such as vm_iplist vs. volume_snapshot_list do not break the overall predictability.
12 tools is well-scoped for an infrastructure read-only API, covering VMs, images, volumes, snapshots, IPs, SSH keys, plans, and regions without unnecessary bloat.
The server is entirely read-only, providing only list and info operations. There are no create, update, delete, or action tools, which is a significant gap for a cloud management MCP server. Users can inspect resources but cannot manage them.
Maintenance
Related MCP Connectors
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Manage Rackspace Spot Kubernetes Cloudspaces, node pools, and VMs from your AI assistant.
- mcpOAuthnet.hepcloud
Manage HepCloud (Turkish cloud) servers and managed PostgreSQL from your AI assistant. OAuth 2.1.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to manage VPS servers, domains, DNS records, and SSH keys through the VPS.org API via natural language.262MIT
- AlicenseBqualityDmaintenanceEnables management of Timeweb Cloud resources including servers, databases, Kubernetes clusters, S3 storage, DNS, SSH keys, and floating IPs through natural language.976 npmMIT
- AlicenseAqualityCmaintenanceEnables safe management of Vultr VPS instances, including listing resources, previewing and creating instances with cost limits, and performing mutations like reboot and delete only after exact confirmation.15MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to manage virtual machines via natural language, including creating, editing, and VNC control.7 npmMIT