check_instance_status

Monitor Verda Cloud GPU instance status and retrieve SSH connection details to verify operational state and accessibility.

Instructions

Check the status of a specific instance.

Args: instance_id: The ID of the instance to check.

Returns: Instance status details including SSH connection info if running.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`instance_id`	Yes

Implementation Reference

src/verda_mcp/server.py:67-94 (handler)

Main handler function for the 'check_instance_status' MCP tool. Decorated with @mcp.tool() to register it as a tool. Takes an instance_id parameter and returns a formatted string with instance details including hostname, ID, status, type, IP address, and SSH connection info if available. Calls client.get_instance() to fetch instance data.

@mcp.tool()
async def check_instance_status(instance_id: str) -> str:
    """Check the status of a specific instance.

    Args:
        instance_id: The ID of the instance to check.

    Returns:
        Instance status details including SSH connection info if running.
    """
    client = _get_client()
    instance = await client.get_instance(instance_id)

    result = [
        f"# Instance: {instance.hostname}",
        f"- **ID**: `{instance.id}`",
        f"- **Status**: {instance.status}",
        f"- **Type**: {instance.instance_type}",
    ]

    if instance.ip_address:
        result.append(f"- **IP Address**: {instance.ip_address}")
        result.append("\n## SSH Connection")
        result.append("```bash")
        result.append(f"ssh root@{instance.ip_address}")
        result.append("```")

    return "\n".join(result)

src/verda_mcp/client.py:77-100 (schema)

Instance dataclass that defines the schema/structure for instance data returned by the tool. Contains fields: id, hostname, status, instance_type, ip_address, location, and startup_script_id. Includes a from_sdk() classmethod to convert SDK objects to this schema.

@dataclass
class Instance:
    """Simplified instance representation."""

    id: str
    hostname: str
    status: str
    instance_type: str
    ip_address: str | None
    location: str | None = None
    startup_script_id: str | None = None

    @classmethod
    def from_sdk(cls, inst: Any) -> "Instance":
        """Create from SDK Instance object."""
        return cls(
            id=inst.id,
            hostname=getattr(inst, "hostname", ""),
            status=getattr(inst, "status", "unknown"),
            instance_type=getattr(inst, "instance_type", ""),
            ip_address=getattr(inst, "ip", None),
            location=getattr(inst, "location", None),
            startup_script_id=getattr(inst, "startup_script_id", None),
        )

src/verda_mcp/client.py:310-321 (helper)

Helper method get_instance() in VerdaSDKClient that fetches instance details by ID. Called by the check_instance_status handler. Wraps the SDK's get_by_id call and converts the result to an Instance object using Instance.from_sdk().

async def get_instance(self, instance_id: str) -> Instance:
    """Get instance details.

    Args:
        instance_id: Instance ID.

    Returns:
        Instance object.
    """
    self._ensure_client()
    inst = await self._run_sync(self._instances.get_by_id, instance_id)
    return Instance.from_sdk(inst)

Verda Cloud MCP Server