Servers and orders

Order dedicated machines, follow progress and manage power and replacement.

Order dedicated machines, follow progress and manage power and replacement.

These are action names. In default compact mode, call the indicated group tool with {"action":"<action-name>","params":{...}}; the arguments below go inside params. In ?mode=all, call the action name directly with those arguments. browse_github and read_docs are direct tools in both modes. Expand each schema for nested fields, enum values and validation constraints. Successful results are JSON in both text content and structuredContent; failures use isError and structuredContent.error.

Use name as the server display label and address as its stable identifier. A caller-defined name takes precedence. Rented marketplace machines otherwise use hardware, Kinesis region and an address suffix, for example H100 80GB in US West #a1b2. Their hostname, csp, region, zone and instanceType are null; use kcRegion for the Kinesis region.

list_servers

List the organization's servers, those it rents, and pending orders. A shared grid's servers count as usable

Group: servers · Behavior: Read

Compact tool: servers · Action: list_servers

MCP annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation	REST	Required scopes
servers.list	GET /servers	pools:read

Arguments

Argument	Type	Required	Description
limit	integer	No	Items per page, 1 to 200 (default 50)
cursor	string	No	nextCursor from the previous page; omit for the first page
org	string	No	Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Items per page, 1 to 200 (default 50)"
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "nextCursor from the previous page; omit for the first page"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "additionalProperties": false
}

Result

• servers (array<object>): One page of servers, by address

• nextCursor (string or null): Pass as cursor to fetch the next page; null on the last page

• pending (array<object>): Provisioning orders that have not produced a server yet; complete on every page

Response schema: servers.list

{
  "type": "object",
  "properties": {
    "servers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "Server (node) address"
          },
          "name": {
            "description": "Display name: the caller's own name for the server when set; else, for a server rented from the marketplace, its hardware and Kinesis region; else the hostname",
            "type": [
              "string",
              "null"
            ]
          },
          "hostname": {
            "description": "Null for servers rented from the marketplace",
            "type": [
              "string",
              "null"
            ]
          },
          "csp": {
            "description": "Cloud provider; null for servers rented from the marketplace",
            "type": [
              "string",
              "null"
            ]
          },
          "region": {
            "description": "Provider region; null for servers rented from the marketplace",
            "type": [
              "string",
              "null"
            ]
          },
          "zone": {
            "description": "Provider zone; null for servers rented from the marketplace",
            "type": [
              "string",
              "null"
            ]
          },
          "instanceType": {
            "description": "Provider instance type; null for servers rented from the marketplace",
            "type": [
              "string",
              "null"
            ]
          },
          "kcRegion": {
            "description": "Kinesis region the server serves, e.g. us-west",
            "type": [
              "string",
              "null"
            ]
          },
          "owned": {
            "type": "boolean",
            "description": "The organization owns this server (false for servers seen through a shared grid)"
          },
          "ownerName": {
            "description": "The organization that owns it; null for rented servers",
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": "string"
          },
          "hibernation": {
            "type": "string",
            "description": "active, hibernated, hibernating or waking"
          },
          "lastPulseAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          },
          "specs": {
            "type": "object",
            "properties": {
              "cpuThreads": {
                "type": "number"
              },
              "ramBytes": {
                "type": "number"
              },
              "storageBytes": {
                "type": "number"
              },
              "gpus": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "model": {
                      "type": "string"
                    },
                    "count": {
                      "type": "number"
                    },
                    "vramBytes": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "model",
                    "count",
                    "vramBytes"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "required": [
              "cpuThreads",
              "ramBytes",
              "storageBytes",
              "gpus"
            ],
            "additionalProperties": false
          },
          "utilization": {
            "type": "object",
            "properties": {
              "cpu": {
                "type": "number"
              },
              "ram": {
                "type": "number"
              },
              "storage": {
                "type": "number"
              },
              "gpu": {
                "type": "number"
              },
              "vram": {
                "type": "number"
              }
            },
            "required": [
              "cpu",
              "ram",
              "storage",
              "gpu",
              "vram"
            ],
            "additionalProperties": false,
            "description": "Percentages from the last pulse"
          },
          "runningApps": {
            "type": "integer"
          },
          "lease": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "gridId": {
                    "type": "string"
                  },
                  "availableUntil": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "description": "ISO 8601 timestamp (UTC)"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "priceCentsPerHour": {
                    "type": "number"
                  }
                },
                "required": [
                  "id",
                  "gridId",
                  "availableUntil",
                  "priceCentsPerHour"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "Spot lease, for servers rented from the marketplace"
          },
          "provisionStatus": {
            "description": "Provisioning order status while the server is being created",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "address",
          "name",
          "hostname",
          "csp",
          "region",
          "zone",
          "instanceType",
          "kcRegion",
          "owned",
          "ownerName",
          "state",
          "hibernation",
          "lastPulseAt",
          "specs",
          "utilization",
          "runningApps",
          "lease",
          "provisionStatus",
          "createdAt"
        ],
        "additionalProperties": false
      },
      "description": "One page of servers, by address"
    },
    "nextCursor": {
      "description": "Pass as cursor to fetch the next page; null on the last page",
      "type": [
        "string",
        "null"
      ]
    },
    "pending": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "orderId": {
            "type": "string",
            "description": "Provisioning order id"
          },
          "address": {
            "description": "Server address once the machine has registered; null while it is still being created",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "failure": {
            "description": "Failure category when the order is failing",
            "type": [
              "string",
              "null"
            ]
          },
          "csp": {
            "type": [
              "string",
              "null"
            ]
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "instanceType": {
            "type": [
              "string",
              "null"
            ]
          },
          "gridIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Grids the server joins once it registers"
          },
          "attempts": {
            "type": "object",
            "properties": {
              "made": {
                "type": "integer"
              },
              "max": {
                "type": "integer"
              }
            },
            "required": [
              "made",
              "max"
            ],
            "additionalProperties": false
          },
          "createdAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "orderId",
          "address",
          "status",
          "failure",
          "csp",
          "region",
          "instanceType",
          "gridIds",
          "attempts",
          "createdAt"
        ],
        "additionalProperties": false
      },
      "description": "Provisioning orders that have not produced a server yet; complete on every page"
    }
  },
  "required": [
    "servers",
    "nextCursor",
    "pending"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

get_server

Get one server: specs, utilization, apps, grids and provisioning order. Its own organization also sees its public address

Group: servers · Behavior: Read

Compact tool: servers · Action: get_server

MCP annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation	REST	Required scopes
servers.get	GET /servers/{address}	pools:read

Arguments

Argument	Type	Required	Description
address	string	Yes	Server address
org	string	No	Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Server address"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "required": [
    "address"
  ],
  "additionalProperties": false
}

Result

• address (string): Server (node) address

• name (string or null): Display name: the caller's own name for the server when set; else, for a server rented from the marketplace, its hardware and Kinesis region; else the hostname

• hostname (string or null): Null for servers rented from the marketplace

• csp (string or null): Cloud provider; null for servers rented from the marketplace

• region (string or null): Provider region; null for servers rented from the marketplace

• zone (string or null): Provider zone; null for servers rented from the marketplace

• instanceType (string or null): Provider instance type; null for servers rented from the marketplace

• kcRegion (string or null): Kinesis region the server serves, e.g. us-west

• owned (boolean): The organization owns this server (false for servers seen through a shared grid)

• ownerName (string or null): The organization that owns it; null for rented servers

• state (string): See the complete response schema below.

• hibernation (string): active, hibernated, hibernating or waking

• lastPulseAt (string or null): See the complete response schema below.

• specs (object): See the complete response schema below.

• utilization (object): Percentages from the last pulse

• runningApps (integer): See the complete response schema below.

• lease (object or null): Spot lease, for servers rented from the marketplace

• provisionStatus (string or null): Provisioning order status while the server is being created

• createdAt (string or null): See the complete response schema below.

• ipAddress (string or null): Public address; null unless the server belongs to the selected organization

• version (string or null): Agent version the server runs

• countryCode (string or null): See the complete response schema below.

• autoWakeup (boolean): The platform wakes the server when an app needs it

• gridIds (array<string>): Grids the server belongs to, among those the caller can see

• apps (array<object>): Apps placed on the server and their container state there

• order (object or null): The provisioning order behind a Kinesis-provisioned server; null for an attached machine

Response schema: servers.get

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Server (node) address"
    },
    "name": {
      "description": "Display name: the caller's own name for the server when set; else, for a server rented from the marketplace, its hardware and Kinesis region; else the hostname",
      "type": [
        "string",
        "null"
      ]
    },
    "hostname": {
      "description": "Null for servers rented from the marketplace",
      "type": [
        "string",
        "null"
      ]
    },
    "csp": {
      "description": "Cloud provider; null for servers rented from the marketplace",
      "type": [
        "string",
        "null"
      ]
    },
    "region": {
      "description": "Provider region; null for servers rented from the marketplace",
      "type": [
        "string",
        "null"
      ]
    },
    "zone": {
      "description": "Provider zone; null for servers rented from the marketplace",
      "type": [
        "string",
        "null"
      ]
    },
    "instanceType": {
      "description": "Provider instance type; null for servers rented from the marketplace",
      "type": [
        "string",
        "null"
      ]
    },
    "kcRegion": {
      "description": "Kinesis region the server serves, e.g. us-west",
      "type": [
        "string",
        "null"
      ]
    },
    "owned": {
      "type": "boolean",
      "description": "The organization owns this server (false for servers seen through a shared grid)"
    },
    "ownerName": {
      "description": "The organization that owns it; null for rented servers",
      "type": [
        "string",
        "null"
      ]
    },
    "state": {
      "type": "string"
    },
    "hibernation": {
      "type": "string",
      "description": "active, hibernated, hibernating or waking"
    },
    "lastPulseAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (UTC)"
        },
        {
          "type": "null"
        }
      ]
    },
    "specs": {
      "type": "object",
      "properties": {
        "cpuThreads": {
          "type": "number"
        },
        "ramBytes": {
          "type": "number"
        },
        "storageBytes": {
          "type": "number"
        },
        "gpus": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "model": {
                "type": "string"
              },
              "count": {
                "type": "number"
              },
              "vramBytes": {
                "type": "number"
              }
            },
            "required": [
              "model",
              "count",
              "vramBytes"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "cpuThreads",
        "ramBytes",
        "storageBytes",
        "gpus"
      ],
      "additionalProperties": false
    },
    "utilization": {
      "type": "object",
      "properties": {
        "cpu": {
          "type": "number"
        },
        "ram": {
          "type": "number"
        },
        "storage": {
          "type": "number"
        },
        "gpu": {
          "type": "number"
        },
        "vram": {
          "type": "number"
        }
      },
      "required": [
        "cpu",
        "ram",
        "storage",
        "gpu",
        "vram"
      ],
      "additionalProperties": false,
      "description": "Percentages from the last pulse"
    },
    "runningApps": {
      "type": "integer"
    },
    "lease": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "gridId": {
              "type": "string"
            },
            "availableUntil": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time",
                  "description": "ISO 8601 timestamp (UTC)"
                },
                {
                  "type": "null"
                }
              ]
            },
            "priceCentsPerHour": {
              "type": "number"
            }
          },
          "required": [
            "id",
            "gridId",
            "availableUntil",
            "priceCentsPerHour"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Spot lease, for servers rented from the marketplace"
    },
    "provisionStatus": {
      "description": "Provisioning order status while the server is being created",
      "type": [
        "string",
        "null"
      ]
    },
    "createdAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (UTC)"
        },
        {
          "type": "null"
        }
      ]
    },
    "ipAddress": {
      "description": "Public address; null unless the server belongs to the selected organization",
      "type": [
        "string",
        "null"
      ]
    },
    "version": {
      "description": "Agent version the server runs",
      "type": [
        "string",
        "null"
      ]
    },
    "countryCode": {
      "type": [
        "string",
        "null"
      ]
    },
    "autoWakeup": {
      "type": "boolean",
      "description": "The platform wakes the server when an app needs it"
    },
    "gridIds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Grids the server belongs to, among those the caller can see"
    },
    "apps": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "guid": {
            "type": "string",
            "description": "Runtime identifier of the app (list_apps shows it as guid)"
          },
          "image": {
            "type": [
              "string",
              "null"
            ]
          },
          "state": {
            "type": "string",
            "description": "Container state on this server"
          },
          "targetState": {
            "type": "string",
            "enum": [
              "running",
              "stopped",
              "unknown"
            ]
          },
          "reportedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "guid",
          "image",
          "state",
          "targetState",
          "reportedAt"
        ],
        "additionalProperties": false
      },
      "description": "Apps placed on the server and their container state there"
    },
    "order": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "Provisioning order id"
            },
            "status": {
              "type": "string"
            },
            "failure": {
              "type": [
                "string",
                "null"
              ]
            },
            "attempts": {
              "type": "object",
              "properties": {
                "made": {
                  "type": "integer"
                },
                "max": {
                  "type": "integer"
                }
              },
              "required": [
                "made",
                "max"
              ],
              "additionalProperties": false
            },
            "awaitingStockSince": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time",
                  "description": "ISO 8601 timestamp (UTC)"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Set while a wake waits for provider stock"
            }
          },
          "required": [
            "id",
            "status",
            "failure",
            "attempts",
            "awaitingStockSince"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "The provisioning order behind a Kinesis-provisioned server; null for an attached machine"
    }
  },
  "required": [
    "address",
    "name",
    "hostname",
    "csp",
    "region",
    "zone",
    "instanceType",
    "kcRegion",
    "owned",
    "ownerName",
    "state",
    "hibernation",
    "lastPulseAt",
    "specs",
    "utilization",
    "runningApps",
    "lease",
    "provisionStatus",
    "createdAt",
    "ipAddress",
    "version",
    "countryCode",
    "autoWakeup",
    "gridIds",
    "apps",
    "order"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

get_server_logs

Read the newest lines of a server's own logs. Agent, runtime health, installation and GPU setup, for one of the organization's servers. Narrow the window with since and until; lines come back oldest to newest.

Group: servers · Behavior: Read

Compact tool: servers · Action: get_server_logs

MCP annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation	REST	Required scopes
servers.logs	GET /servers/{address}/logs	monitoring:read

Arguments

Argument	Type	Required	Description
address	string	Yes	Server address
since	string	No	Earliest line to include; omit for no lower bound
until	string	No	Latest line to include; omit for now
limit	integer	No	Newest lines to return within the window, 500 by default
org	string	No	Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Server address"
    },
    "since": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      "description": "Earliest line to include; omit for no lower bound"
    },
    "until": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      "description": "Latest line to include; omit for now"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5000,
      "description": "Newest lines to return within the window, 500 by default"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "required": [
    "address"
  ],
  "additionalProperties": false
}

Result

• logs (array<object>): Oldest to newest; the last line is the most recent

• truncated (boolean): The window holds more lines than limit; the oldest were dropped (pass until to read further back)

Response schema: servers.logs

{
  "type": "object",
  "properties": {
    "logs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp (UTC)"
          },
          "source": {
            "type": "string",
            "description": "Component that wrote the line, e.g. the agent, the runtime, GPU setup"
          },
          "level": {
            "type": "string",
            "enum": [
              "trace",
              "info",
              "warning",
              "error",
              "unknown"
            ]
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "at",
          "source",
          "level",
          "text"
        ],
        "additionalProperties": false
      },
      "description": "Oldest to newest; the last line is the most recent"
    },
    "truncated": {
      "type": "boolean",
      "description": "The window holds more lines than limit; the oldest were dropped (pass until to read further back)"
    }
  },
  "required": [
    "logs",
    "truncated"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

provision_servers

Order dedicated servers from a cloud provider. Billing starts once they come up. Checks the quota and the balance first. Set dryRun to get the cost estimate without ordering; use browse_catalog for the region and instance type ids. Returns an order; poll get_provision_order until done.

Group: servers · Behavior: Write

Compact tool: servers_write · Action: provision_servers

MCP annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false

Permissions and REST equivalents

Operation	REST	Required scopes
servers.provision	POST /servers/provision	pools:write, compute:spend

Arguments

Argument	Type	Required	Description
csp	"kinesis" / "aws" / "azure"	Yes	Cloud provider
region	string	Yes	Provider region id (see catalog.regions)
zone	string	No	Availability zone; omit to let the provider choose
instanceType	string	Yes	Instance type id (see catalog.instanceTypes)
count	integer	No	Servers to order, 1 to 10 (default 1)
storageSizeGb	integer	No	Disk per server in GB, 50 to 10000; required unless useEphemeralSsd is set
useEphemeralSsd	boolean	No	Use the bundled local SSD instead of a network volume (supported non-hibernatable Kinesis compute configurations only)
gridIds	array<string>	No	Grids the servers join once they register
dryRun	boolean	No	Run every check and return the estimate without ordering
idempotencyKey	string	No	Unique string without whitespace; send the same one with the same arguments when retrying after a timeout, and the original result comes back instead of acting twice
org	string	No	Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "csp": {
      "type": "string",
      "enum": [
        "kinesis",
        "aws",
        "azure"
      ],
      "description": "Cloud provider"
    },
    "region": {
      "type": "string",
      "minLength": 1,
      "description": "Provider region id (see catalog.regions)"
    },
    "zone": {
      "type": "string",
      "minLength": 1,
      "description": "Availability zone; omit to let the provider choose"
    },
    "instanceType": {
      "type": "string",
      "minLength": 1,
      "description": "Instance type id (see catalog.instanceTypes)"
    },
    "count": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Servers to order, 1 to 10 (default 1)"
    },
    "storageSizeGb": {
      "type": "integer",
      "minimum": 50,
      "maximum": 10000,
      "description": "Disk per server in GB, 50 to 10000; required unless useEphemeralSsd is set"
    },
    "useEphemeralSsd": {
      "type": "boolean",
      "description": "Use the bundled local SSD instead of a network volume (supported non-hibernatable Kinesis compute configurations only)"
    },
    "gridIds": {
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Grids the servers join once they register"
    },
    "dryRun": {
      "type": "boolean",
      "description": "Run every check and return the estimate without ordering"
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^\\S+$",
      "description": "Unique string without whitespace; send the same one with the same arguments when retrying after a timeout, and the original result comes back instead of acting twice"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "required": [
    "csp",
    "region",
    "instanceType"
  ],
  "additionalProperties": false
}

Result

• dryRun (boolean): See the complete response schema below.

• csp (string): See the complete response schema below.

• region (string): See the complete response schema below.

• instanceType (string): See the complete response schema below.

• count (integer): See the complete response schema below.

• estimate (object): See the complete response schema below.

• orders (array<object>): Empty for a dry run

Response schema: servers.provision

{
  "type": "object",
  "properties": {
    "dryRun": {
      "type": "boolean"
    },
    "csp": {
      "type": "string"
    },
    "region": {
      "type": "string"
    },
    "instanceType": {
      "type": "string"
    },
    "count": {
      "type": "integer"
    },
    "estimate": {
      "type": "object",
      "properties": {
        "instanceCount": {
          "type": "integer"
        },
        "totalHourlyCostCents": {
          "type": "number",
          "description": "Hourly cost of the whole order"
        },
        "totalRequiredCents": {
          "type": "number",
          "description": "Balance needed to cover the minimum runtime"
        },
        "minimumHours": {
          "type": "number",
          "description": "Hours of runtime the balance must cover before an order is accepted"
        },
        "balanceCents": {
          "type": "number"
        },
        "overLimitCents": {
          "type": "number"
        },
        "availableRunwayCents": {
          "type": "number",
          "description": "Balance plus the over-limit allowance"
        },
        "topUpNeededCents": {
          "type": "number",
          "description": "0 when the balance suffices"
        }
      },
      "required": [
        "instanceCount",
        "totalHourlyCostCents",
        "totalRequiredCents",
        "minimumHours",
        "balanceCents",
        "overLimitCents",
        "availableRunwayCents",
        "topUpNeededCents"
      ],
      "additionalProperties": false
    },
    "orders": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "orderId": {
            "type": "string",
            "description": "Provisioning order id"
          },
          "status": {
            "type": "string"
          },
          "count": {
            "type": "integer",
            "description": "Servers in the order"
          },
          "csp": {
            "type": [
              "string",
              "null"
            ]
          },
          "failure": {
            "description": "Failure category when the order is failing",
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          },
          "updatedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          },
          "dismissed": {
            "type": "boolean",
            "description": "Hidden from the pending list (servers.orders.dismiss)"
          }
        },
        "required": [
          "orderId",
          "status",
          "count",
          "csp",
          "failure",
          "createdAt",
          "updatedAt",
          "dismissed"
        ],
        "additionalProperties": false
      },
      "description": "Empty for a dry run"
    }
  },
  "required": [
    "dryRun",
    "csp",
    "region",
    "instanceType",
    "count",
    "estimate",
    "orders"
  ],
  "additionalProperties": false
}

Operation-specific errors: 402 insufficient_balance, 403 provision_quota, 400 no_provider_for_region, 400 ephemeral_ssd_unavailable, 400 org_required, 403 key_project_restricted.

deprovision_servers

Destroy dedicated servers. They leave every grid first. Irreversible.

Group: servers · Behavior: Write

Compact tool: servers_write · Action: deprovision_servers

MCP annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false

Requires confirm: true for this irreversible action.

Permissions and REST equivalents

Operation	REST	Required scopes
servers.deprovision	POST /servers/deprovision	pools:write

Arguments

Argument	Type	Required	Description
addresses	array<string>	Yes	Server addresses, at most 50
confirm	true	Yes	Must be true: this action cannot be undone
org	string	No	Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "addresses": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^0x[0-9a-fA-F]{40}$"
      },
      "description": "Server addresses, at most 50"
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: this action cannot be undone"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "required": [
    "addresses",
    "confirm"
  ],
  "additionalProperties": false
}

Result

• results (array<object>): One entry per requested server

Response schema: servers.deprovision

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string"
          },
          "ok": {
            "type": "boolean"
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "address",
          "ok",
          "error"
        ],
        "additionalProperties": false
      },
      "description": "One entry per requested server"
    }
  },
  "required": [
    "results"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

power_servers

Change the power state of the organization’s servers (admins). hibernate stops the machine and its compute billing but keeps its disk; wake starts a hibernated machine again (fails with out_of_stock when the provider has no capacity; retry later); reboot restarts a running machine.

Group: servers · Behavior: Write

Compact tool: servers_write · Action: power_servers

MCP annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false

Permissions and REST equivalents

Operation	REST	Required scopes
servers.hibernate	POST /servers/hibernate	pools:write
servers.wake	POST /servers/wake	pools:write, compute:spend
servers.reboot	POST /servers/reboot	pools:write

Arguments

Argument	Type	Required	Description
action	"hibernate" / "wake" / "reboot"	Yes	Power action to apply
addresses	array<string>	Yes	Server addresses, at most 50
org	string	No	Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "hibernate",
        "wake",
        "reboot"
      ],
      "description": "Power action to apply"
    },
    "addresses": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^0x[0-9a-fA-F]{40}$"
      },
      "description": "Server addresses, at most 50"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "required": [
    "action",
    "addresses"
  ],
  "additionalProperties": false
}

Result

servers.hibernate

• results (array<object>): One entry per requested server; ok means the request was accepted, the state change is asynchronous

Response schema: servers.hibernate

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string"
          },
          "ok": {
            "type": "boolean"
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "reason": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "out_of_stock",
                  "not_hibernatable",
                  "not_active",
                  "unknown"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Why the request was refused or failed: out_of_stock means retry later; not_hibernatable and not_active are screened before the backend is asked"
          }
        },
        "required": [
          "address",
          "ok",
          "error",
          "reason"
        ],
        "additionalProperties": false
      },
      "description": "One entry per requested server; ok means the request was accepted, the state change is asynchronous"
    }
  },
  "required": [
    "results"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted. servers.wake

• results (array<object>): One entry per requested server; ok means the request was accepted, the state change is asynchronous

Response schema: servers.wake

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string"
          },
          "ok": {
            "type": "boolean"
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "reason": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "out_of_stock",
                  "not_hibernatable",
                  "not_active",
                  "unknown"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Why the request was refused or failed: out_of_stock means retry later; not_hibernatable and not_active are screened before the backend is asked"
          }
        },
        "required": [
          "address",
          "ok",
          "error",
          "reason"
        ],
        "additionalProperties": false
      },
      "description": "One entry per requested server; ok means the request was accepted, the state change is asynchronous"
    }
  },
  "required": [
    "results"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted. servers.reboot

• results (array<object>): One entry per requested server

Response schema: servers.reboot

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string"
          },
          "ok": {
            "type": "boolean"
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "address",
          "ok",
          "error"
        ],
        "additionalProperties": false
      },
      "description": "One entry per requested server"
    }
  },
  "required": [
    "results"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

replace_server

Provision an identical server and retire this one once the new one is up. The retired server's disk is not kept. Poll servers.orders.get with the returned order id to follow the replacement.

Group: servers · Behavior: Write

Compact tool: servers_write · Action: replace_server

MCP annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false

Requires confirm: true for this irreversible action.

Permissions and REST equivalents

Operation	REST	Required scopes
servers.replace	POST /servers/{address}/replace	pools:write, compute:spend

Arguments

Argument	Type	Required	Description
address	string	Yes	Address of the server to replace
confirm	true	Yes	Must be true: this action cannot be undone
idempotencyKey	string	No	Unique string without whitespace; send the same one with the same arguments when retrying after a timeout, and the original result comes back instead of acting twice
org	string	No	Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Address of the server to replace"
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: this action cannot be undone"
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^\\S+$",
      "description": "Unique string without whitespace; send the same one with the same arguments when retrying after a timeout, and the original result comes back instead of acting twice"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "required": [
    "address",
    "confirm"
  ],
  "additionalProperties": false
}

Result

• order (object or null): The resulting order, when the backend returned one

Response schema: servers.replace

{
  "type": "object",
  "properties": {
    "order": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "orderId": {
              "type": "string",
              "description": "Provisioning order id"
            },
            "status": {
              "type": "string"
            },
            "count": {
              "type": "integer",
              "description": "Servers in the order"
            },
            "csp": {
              "type": [
                "string",
                "null"
              ]
            },
            "failure": {
              "description": "Failure category when the order is failing",
              "type": [
                "string",
                "null"
              ]
            },
            "createdAt": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time",
                  "description": "ISO 8601 timestamp (UTC)"
                },
                {
                  "type": "null"
                }
              ]
            },
            "updatedAt": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time",
                  "description": "ISO 8601 timestamp (UTC)"
                },
                {
                  "type": "null"
                }
              ]
            },
            "dismissed": {
              "type": "boolean",
              "description": "Hidden from the pending list (servers.orders.dismiss)"
            }
          },
          "required": [
            "orderId",
            "status",
            "count",
            "csp",
            "failure",
            "createdAt",
            "updatedAt",
            "dismissed"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "The resulting order, when the backend returned one"
    }
  },
  "required": [
    "order"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

get_provision_order

Get a provisioning order the caller placed and the machines it has produced. Completed, replacement and dismissed orders are readable too. Poll this after servers.provision or servers.replace until done.

Group: servers · Behavior: Read

Compact tool: servers · Action: get_provision_order

MCP annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation	REST	Required scopes
servers.orders.get	GET /servers/orders/{orderId}	pools:read

Arguments

Argument	Type	Required	Description
orderId	string	Yes	Provisioning order id
org	string	No	Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "minLength": 1,
      "description": "Provisioning order id"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "required": [
    "orderId"
  ],
  "additionalProperties": false
}

Result

• order (object): See the complete response schema below.

• instances (array<object>): One entry per machine in the order; address is set once the machine has registered

• done (boolean): The order reached a terminal state: complete, failed or cancelled

Response schema: servers.orders.get

{
  "type": "object",
  "properties": {
    "order": {
      "type": "object",
      "properties": {
        "orderId": {
          "type": "string",
          "description": "Provisioning order id"
        },
        "status": {
          "type": "string"
        },
        "count": {
          "type": "integer",
          "description": "Servers in the order"
        },
        "csp": {
          "type": [
            "string",
            "null"
          ]
        },
        "failure": {
          "description": "Failure category when the order is failing",
          "type": [
            "string",
            "null"
          ]
        },
        "createdAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "description": "ISO 8601 timestamp (UTC)"
            },
            {
              "type": "null"
            }
          ]
        },
        "updatedAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "description": "ISO 8601 timestamp (UTC)"
            },
            {
              "type": "null"
            }
          ]
        },
        "dismissed": {
          "type": "boolean",
          "description": "Hidden from the pending list (servers.orders.dismiss)"
        }
      },
      "required": [
        "orderId",
        "status",
        "count",
        "csp",
        "failure",
        "createdAt",
        "updatedAt",
        "dismissed"
      ],
      "additionalProperties": false
    },
    "instances": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "orderId": {
            "type": "string",
            "description": "Provisioning order id"
          },
          "address": {
            "description": "Server address once the machine has registered; null while it is still being created",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "failure": {
            "description": "Failure category when the order is failing",
            "type": [
              "string",
              "null"
            ]
          },
          "csp": {
            "type": [
              "string",
              "null"
            ]
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "instanceType": {
            "type": [
              "string",
              "null"
            ]
          },
          "gridIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Grids the server joins once it registers"
          },
          "attempts": {
            "type": "object",
            "properties": {
              "made": {
                "type": "integer"
              },
              "max": {
                "type": "integer"
              }
            },
            "required": [
              "made",
              "max"
            ],
            "additionalProperties": false
          },
          "createdAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "orderId",
          "address",
          "status",
          "failure",
          "csp",
          "region",
          "instanceType",
          "gridIds",
          "attempts",
          "createdAt"
        ],
        "additionalProperties": false
      },
      "description": "One entry per machine in the order; address is set once the machine has registered"
    },
    "done": {
      "type": "boolean",
      "description": "The order reached a terminal state: complete, failed or cancelled"
    }
  },
  "required": [
    "order",
    "instances",
    "done"
  ],
  "additionalProperties": false
}

Operation-specific errors: 400 org_required, 403 key_project_restricted.

manage_provision_order

Retry a failed provisioning order, or dismiss one. retry re-runs a failed order (see get_provision_order, or list_servers under pending); dismiss cancels an in-flight order or hides a finished one from the pending list.

Group: servers · Behavior: Write

Compact tool: servers_write · Action: manage_provision_order

MCP annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: false

Permissions and REST equivalents

Operation	REST	Required scopes
servers.orders.retry	POST /servers/orders/{orderId}/retry	pools:write, compute:spend
servers.orders.dismiss	POST /servers/orders/{orderId}/dismiss	pools:write

Arguments

Argument	Type	Required	Description
action	"retry" / "dismiss"	Yes	What to do with the order
orderId	string	Yes	Provisioning order id
org	string	No	Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "retry",
        "dismiss"
      ],
      "description": "What to do with the order"
    },
    "orderId": {
      "type": "string",
      "minLength": 1,
      "description": "Provisioning order id"
    },
    "org": {
      "description": "Slug of the organization to act in (see orgs.list); needed when the caller reaches more than one",
      "type": "string",
      "minLength": 3,
      "maxLength": 39
    }
  },
  "required": [
    "action",
    "orderId"
  ],
  "additionalProperties": false
}

Result

servers.orders.retry

• order (object or null): The resulting order, when the backend returned one

Response schema: servers.orders.retry

{
  "type": "object",
  "properties": {
    "order": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "orderId": {
              "type": "string",
              "description": "Provisioning order id"
            },
            "status": {
              "type": "string"
            },
            "count": {
              "type": "integer",
              "description": "Servers in the order"
            },
            "csp": {
              "type": [
                "string",
                "null"
              ]
            },
            "failure": {
              "description": "Failure category when the order is failing",
              "type": [
                "string",
                "null"
              ]
            },
            "createdAt": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time",
                  "description": "ISO 8601 timestamp (UTC)"
                },
                {
                  "type": "null"
                }
              ]
            },
            "updatedAt": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "date-time",
                  "description": "ISO 8601 timestamp (UTC)"
                },
                {
                  "type": "null"
                }
              ]
            },
            "dismissed": {
              "type": "boolean",
              "description": "Hidden from the pending list (servers.orders.dismiss)"
            }
          },
          "required": [
            "orderId",
            "status",
            "count",
            "csp",
            "failure",
            "createdAt",
            "updatedAt",
            "dismissed"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "The resulting order, when the backend returned one"
    }
  },
  "required": [
    "order"
  ],
  "additionalProperties": false
}

Operation-specific errors: 409 provision_order_failed, 400 org_required, 403 key_project_restricted. servers.orders.dismiss

• orderId (string): See the complete response schema below.

• dismissed (true): See the complete response schema below.

Response schema: servers.orders.dismiss

{
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string"
    },
    "dismissed": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "orderId",
    "dismissed"
  ],
  "additionalProperties": false
}

Operation-specific errors: 409 provision_order_failed, 400 org_required, 403 key_project_restricted.