> For the complete documentation index, see [llms.txt](https://docs.kinesis.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinesis.network/mcp/tools/servers.md).

# 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. `addedBy` identifies who added it, or is null without `members:read`, for another organization’s server or when nobody is recorded. 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. Server logs are raw machine output and may contain sensitive data.

The [OpenAI profile](/mcp/openai-profile.md) calls individual actions, omits `get_byod_token`, and restricts credential inputs and environment outputs. The input schemas below describe the standard catalog; profile-specific schemas are included where they differ.

## `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 |

<details>

<summary>Complete input schema</summary>

```json
{
  "$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
}
```

</details>

### 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

<details>

<summary>Response schema: servers.list</summary>

```json
{
  "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"
            ]
          },
          "addedBy": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "string",
                    "description": "User id, as members.list and the sharing calls use it"
                  },
                  "name": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "email": {
                    "type": "string"
                  }
                },
                "required": [
                  "userId",
                  "name",
                  "email"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "Who added it to the organization. Null when nobody is on record, for another organization's server, and for a credential without members:read"
          },
          "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",
          "addedBy",
          "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
}
```

</details>

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 |

<details>

<summary>Complete input schema</summary>

```json
{
  "$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
}
```

</details>

### 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
* `addedBy` (`object or null`): Who added it to the organization. Null when nobody is on record, for another organization's server, and for a credential without members:read
* `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

<details>

<summary>Response schema: servers.get</summary>

```json
{
  "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"
      ]
    },
    "addedBy": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "userId": {
              "type": "string",
              "description": "User id, as members.list and the sharing calls use it"
            },
            "name": {
              "type": [
                "string",
                "null"
              ]
            },
            "email": {
              "type": "string"
            }
          },
          "required": [
            "userId",
            "name",
            "email"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Who added it to the organization. Null when nobody is on record, for another organization's server, and for a credential without members:read"
    },
    "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",
    "addedBy",
    "state",
    "hibernation",
    "lastPulseAt",
    "specs",
    "utilization",
    "runningApps",
    "lease",
    "provisionStatus",
    "createdAt",
    "ipAddress",
    "version",
    "countryCode",
    "autoWakeup",
    "gridIds",
    "apps",
    "order"
  ],
  "additionalProperties": false
}
```

</details>

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. They are the machine's logs as written and may include sensitive data.

**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 |

<details>

<summary>Complete input schema</summary>

```json
{
  "$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
}
```

</details>

### 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)

<details>

<summary>Response schema: servers.logs</summary>

```json
{
  "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
}
```

</details>

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 instance's bundled local SSD instead of a network volume (Kinesis compute's large GPU instance types that can't hibernate 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                                                                      |

<details>

<summary>Complete input schema</summary>

```json
{
  "$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 instance's bundled local SSD instead of a network volume (Kinesis compute's large GPU instance types that can't hibernate 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
}
```

</details>

### 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

<details>

<summary>Response schema: servers.provision</summary>

```json
{
  "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
}
```

</details>

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 |

<details>

<summary>Complete input schema</summary>

```json
{
  "$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
}
```

</details>

### Result

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

<details>

<summary>Response schema: servers.deprovision</summary>

```json
{
  "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
}
```

</details>

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 |

<details>

<summary>Complete input schema</summary>

```json
{
  "$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
}
```

</details>

### Result

**`servers.hibernate`**

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

<details>

<summary>Response schema: servers.hibernate</summary>

```json
{
  "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
}
```

</details>

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

<details>

<summary>Response schema: servers.wake</summary>

```json
{
  "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
}
```

</details>

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

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

<details>

<summary>Response schema: servers.reboot</summary>

```json
{
  "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
}
```

</details>

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                                                                      |

<details>

<summary>Complete input schema</summary>

```json
{
  "$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
}
```

</details>

### Result

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

<details>

<summary>Response schema: servers.replace</summary>

```json
{
  "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
}
```

</details>

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 |

<details>

<summary>Complete input schema</summary>

```json
{
  "$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
}
```

</details>

### 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

<details>

<summary>Response schema: servers.orders.get</summary>

```json
{
  "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
}
```

</details>

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 |

<details>

<summary>Complete input schema</summary>

```json
{
  "$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
}
```

</details>

### Result

**`servers.orders.retry`**

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

<details>

<summary>Response schema: servers.orders.retry</summary>

```json
{
  "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
}
```

</details>

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.

<details>

<summary>Response schema: servers.orders.dismiss</summary>

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

</details>

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kinesis.network/mcp/tools/servers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.