> 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/grids.md).

# Grids

Compose and manage the grids that apps target for dedicated capacity.

Compose and manage the grids that apps target for dedicated capacity.

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

Only organization admins create and manage grids. Developers can deploy to accessible grids; viewers can inspect them. Grid quota policies are configured in the portal, not through these public actions. Quotas count apps, running containers and GPUs against the app’s creator.

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

List the grids the caller can see: the organization's, then those shared with it

**Group:** `grids` · **Behavior:** Read

**Compact tool:** `grids` · **Action:** `list_grids`

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

### Permissions and REST equivalents

| Operation    | REST         | Required scopes |
| ------------ | ------------ | --------------- |
| `grids.list` | `GET /grids` | `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

* `grids` (`array<object>`): See the complete response schema below.
* `nextCursor` (`string or null`): Pass as cursor to fetch the next page; null on the last page

<details>

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

```json
{
  "type": "object",
  "properties": {
    "grids": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Grid id"
          },
          "name": {
            "type": "string"
          },
          "org": {
            "type": "object",
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "slug",
              "name"
            ],
            "additionalProperties": false,
            "description": "The organization that owns it"
          },
          "access": {
            "type": "object",
            "properties": {
              "role": {
                "type": "string",
                "enum": [
                  "admin",
                  "developer",
                  "viewer"
                ],
                "description": "The caller's role on it"
              },
              "outside": {
                "type": "boolean",
                "description": "Shared with the caller from another organization"
              },
              "isCreator": {
                "type": "boolean",
                "description": "The caller created it"
              }
            },
            "required": [
              "role",
              "outside",
              "isCreator"
            ],
            "additionalProperties": false
          },
          "visibility": {
            "type": "string",
            "enum": [
              "private",
              "org"
            ],
            "description": "private: admins, its creator and the people added; org: everyone in the organization"
          },
          "createdBy": {
            "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 created it. Null when nobody is on record, for another organization's, and for a credential without members:read"
          },
          "nodes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Addresses of the servers in the grid"
          },
          "autoCreated": {
            "type": "boolean",
            "description": "Created by the platform rather than the user"
          },
          "priorityMode": {
            "type": "string",
            "enum": [
              "absolute",
              "weighted"
            ],
            "description": "How app priorities apply when the grid is contended"
          },
          "needsReconciliation": {
            "type": "boolean",
            "description": "Membership changes are still being applied"
          },
          "volumes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "mountPath": {
                  "type": "string"
                },
                "maxSize": {
                  "type": "number"
                },
                "tag": {
                  "type": "string"
                }
              },
              "required": [
                "mountPath",
                "maxSize",
                "tag"
              ],
              "additionalProperties": false
            }
          },
          "networks": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "cidr": {
                  "type": "string"
                },
                "tag": {
                  "type": "string"
                }
              },
              "required": [
                "cidr",
                "tag"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "id",
          "name",
          "org",
          "access",
          "visibility",
          "createdBy",
          "nodes",
          "autoCreated",
          "priorityMode",
          "needsReconciliation",
          "volumes",
          "networks"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": {
      "description": "Pass as cursor to fetch the next page; null on the last page",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "grids",
    "nextCursor"
  ],
  "additionalProperties": false
}
```

</details>

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

## `create_grid`

Create a grid in the organization (admins), optionally with servers attached

**Group:** `grids` · **Behavior:** Write

**Compact tool:** `grids_write` · **Action:** `create_grid`

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

### Permissions and REST equivalents

| Operation      | REST          | Required scopes |
| -------------- | ------------- | --------------- |
| `grids.create` | `POST /grids` | `pools:write`   |

### Arguments

| Argument         | Type                | Required | Description                                                                                                                                                           |
| ---------------- | ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | `string`            | Yes      | Grid name                                                                                                                                                             |
| `visibility`     | `"private" / "org"` | No       | Who in the organization can see and deploy to it; private by default                                                                                                  |
| `volumes`        | `array<object>`     | No       | Shared volumes available to apps on the grid; replaces the stored list                                                                                                |
| `networks`       | `array<object>`     | No       | Networks available to apps on the grid; replaces the stored list                                                                                                      |
| `nodes`          | `array<string>`     | No       | Addresses of servers to attach                                                                                                                                        |
| `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": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Grid name"
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "org"
      ],
      "description": "Who in the organization can see and deploy to it; private by default"
    },
    "volumes": {
      "maxItems": 16,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "mountPath": {
            "type": "string",
            "minLength": 1,
            "description": "Host path mounted into apps on the grid"
          },
          "maxSize": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Size cap in bytes; 0 for unlimited"
          },
          "tag": {
            "type": "string",
            "description": "Label apps use to pick the volume"
          }
        },
        "required": [
          "mountPath",
          "maxSize"
        ],
        "additionalProperties": false
      },
      "description": "Shared volumes available to apps on the grid; replaces the stored list"
    },
    "networks": {
      "maxItems": 16,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "cidr": {
            "type": "string",
            "minLength": 1,
            "description": "Network range in CIDR notation"
          },
          "tag": {
            "type": "string",
            "description": "Label apps use to pick the network"
          }
        },
        "required": [
          "cidr"
        ],
        "additionalProperties": false
      },
      "description": "Networks available to apps on the grid; replaces the stored list"
    },
    "nodes": {
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^0x[0-9a-fA-F]{40}$"
      },
      "description": "Addresses of servers to attach"
    },
    "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": [
    "name"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `id` (`string`): Grid id
* `name` (`string`): See the complete response schema below.
* `org` (`object`): The organization that owns it
* `access` (`object`): See the complete response schema below.
* `visibility` (`"private" / "org"`): private: admins, its creator and the people added; org: everyone in the organization
* `createdBy` (`object or null`): Who created it. Null when nobody is on record, for another organization's, and for a credential without members:read
* `nodes` (`array<string>`): Addresses of the servers in the grid
* `autoCreated` (`boolean`): Created by the platform rather than the user
* `priorityMode` (`"absolute" / "weighted"`): How app priorities apply when the grid is contended
* `needsReconciliation` (`boolean`): Membership changes are still being applied
* `volumes` (`array<object>`): See the complete response schema below.
* `networks` (`array<object>`): See the complete response schema below.
* `warning` (`string or null`): Set when the grid was created but a follow-up step failed

<details>

<summary>Response schema: grids.create</summary>

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Grid id"
    },
    "name": {
      "type": "string"
    },
    "org": {
      "type": "object",
      "properties": {
        "slug": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "required": [
        "slug",
        "name"
      ],
      "additionalProperties": false,
      "description": "The organization that owns it"
    },
    "access": {
      "type": "object",
      "properties": {
        "role": {
          "type": "string",
          "enum": [
            "admin",
            "developer",
            "viewer"
          ],
          "description": "The caller's role on it"
        },
        "outside": {
          "type": "boolean",
          "description": "Shared with the caller from another organization"
        },
        "isCreator": {
          "type": "boolean",
          "description": "The caller created it"
        }
      },
      "required": [
        "role",
        "outside",
        "isCreator"
      ],
      "additionalProperties": false
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "org"
      ],
      "description": "private: admins, its creator and the people added; org: everyone in the organization"
    },
    "createdBy": {
      "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 created it. Null when nobody is on record, for another organization's, and for a credential without members:read"
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Addresses of the servers in the grid"
    },
    "autoCreated": {
      "type": "boolean",
      "description": "Created by the platform rather than the user"
    },
    "priorityMode": {
      "type": "string",
      "enum": [
        "absolute",
        "weighted"
      ],
      "description": "How app priorities apply when the grid is contended"
    },
    "needsReconciliation": {
      "type": "boolean",
      "description": "Membership changes are still being applied"
    },
    "volumes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "mountPath": {
            "type": "string"
          },
          "maxSize": {
            "type": "number"
          },
          "tag": {
            "type": "string"
          }
        },
        "required": [
          "mountPath",
          "maxSize",
          "tag"
        ],
        "additionalProperties": false
      }
    },
    "networks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "cidr": {
            "type": "string"
          },
          "tag": {
            "type": "string"
          }
        },
        "required": [
          "cidr",
          "tag"
        ],
        "additionalProperties": false
      }
    },
    "warning": {
      "description": "Set when the grid was created but a follow-up step failed",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "id",
    "name",
    "org",
    "access",
    "visibility",
    "createdBy",
    "nodes",
    "autoCreated",
    "priorityMode",
    "needsReconciliation",
    "volumes",
    "networks",
    "warning"
  ],
  "additionalProperties": false
}
```

</details>

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

## `update_grid`

Change a grid's settings, visibility, membership or priority mode (admins). Membership changes are explicit lists of servers to add and to remove.

**Group:** `grids` · **Behavior:** Write

**Compact tool:** `grids_write` · **Action:** `update_grid`

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

### Permissions and REST equivalents

| Operation      | REST                    | Required scopes |
| -------------- | ----------------------- | --------------- |
| `grids.update` | `PATCH /grids/{gridId}` | `pools:write`   |

### Arguments

| Argument       | Type                      | Required | Description                                                                          |
| -------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------ |
| `name`         | `string`                  | No       | Grid name                                                                            |
| `visibility`   | `"private" / "org"`       | No       | private: admins, its creator and the people added; org: everyone in the organization |
| `volumes`      | `array<object>`           | No       | Shared volumes available to apps on the grid; replaces the stored list               |
| `networks`     | `array<object>`           | No       | Networks available to apps on the grid; replaces the stored list                     |
| `addNodes`     | `array<string>`           | No       | Servers to add to the grid                                                           |
| `removeNodes`  | `array<string>`           | No       | Servers to remove from the grid                                                      |
| `priorityMode` | `"absolute" / "weighted"` | No       | How app priorities apply when the grid is contended                                  |
| `gridId`       | `string`                  | Yes      | Grid id                                                                              |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Grid name"
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "org"
      ],
      "description": "private: admins, its creator and the people added; org: everyone in the organization"
    },
    "volumes": {
      "maxItems": 16,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "mountPath": {
            "type": "string",
            "minLength": 1,
            "description": "Host path mounted into apps on the grid"
          },
          "maxSize": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Size cap in bytes; 0 for unlimited"
          },
          "tag": {
            "type": "string",
            "description": "Label apps use to pick the volume"
          }
        },
        "required": [
          "mountPath",
          "maxSize"
        ],
        "additionalProperties": false
      },
      "description": "Shared volumes available to apps on the grid; replaces the stored list"
    },
    "networks": {
      "maxItems": 16,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "cidr": {
            "type": "string",
            "minLength": 1,
            "description": "Network range in CIDR notation"
          },
          "tag": {
            "type": "string",
            "description": "Label apps use to pick the network"
          }
        },
        "required": [
          "cidr"
        ],
        "additionalProperties": false
      },
      "description": "Networks available to apps on the grid; replaces the stored list"
    },
    "addNodes": {
      "maxItems": 500,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^0x[0-9a-fA-F]{40}$"
      },
      "description": "Servers to add to the grid"
    },
    "removeNodes": {
      "maxItems": 500,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^0x[0-9a-fA-F]{40}$"
      },
      "description": "Servers to remove from the grid"
    },
    "priorityMode": {
      "type": "string",
      "enum": [
        "absolute",
        "weighted"
      ],
      "description": "How app priorities apply when the grid is contended"
    },
    "gridId": {
      "type": "string",
      "minLength": 1,
      "description": "Grid id"
    }
  },
  "required": [
    "gridId"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `id` (`string`): Grid id
* `name` (`string`): See the complete response schema below.
* `org` (`object`): The organization that owns it
* `access` (`object`): See the complete response schema below.
* `visibility` (`"private" / "org"`): private: admins, its creator and the people added; org: everyone in the organization
* `createdBy` (`object or null`): Who created it. Null when nobody is on record, for another organization's, and for a credential without members:read
* `nodes` (`array<string>`): Addresses of the servers in the grid
* `autoCreated` (`boolean`): Created by the platform rather than the user
* `priorityMode` (`"absolute" / "weighted"`): How app priorities apply when the grid is contended
* `needsReconciliation` (`boolean`): Membership changes are still being applied
* `volumes` (`array<object>`): See the complete response schema below.
* `networks` (`array<object>`): See the complete response schema below.

<details>

<summary>Response schema: grids.update</summary>

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Grid id"
    },
    "name": {
      "type": "string"
    },
    "org": {
      "type": "object",
      "properties": {
        "slug": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "required": [
        "slug",
        "name"
      ],
      "additionalProperties": false,
      "description": "The organization that owns it"
    },
    "access": {
      "type": "object",
      "properties": {
        "role": {
          "type": "string",
          "enum": [
            "admin",
            "developer",
            "viewer"
          ],
          "description": "The caller's role on it"
        },
        "outside": {
          "type": "boolean",
          "description": "Shared with the caller from another organization"
        },
        "isCreator": {
          "type": "boolean",
          "description": "The caller created it"
        }
      },
      "required": [
        "role",
        "outside",
        "isCreator"
      ],
      "additionalProperties": false
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "org"
      ],
      "description": "private: admins, its creator and the people added; org: everyone in the organization"
    },
    "createdBy": {
      "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 created it. Null when nobody is on record, for another organization's, and for a credential without members:read"
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Addresses of the servers in the grid"
    },
    "autoCreated": {
      "type": "boolean",
      "description": "Created by the platform rather than the user"
    },
    "priorityMode": {
      "type": "string",
      "enum": [
        "absolute",
        "weighted"
      ],
      "description": "How app priorities apply when the grid is contended"
    },
    "needsReconciliation": {
      "type": "boolean",
      "description": "Membership changes are still being applied"
    },
    "volumes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "mountPath": {
            "type": "string"
          },
          "maxSize": {
            "type": "number"
          },
          "tag": {
            "type": "string"
          }
        },
        "required": [
          "mountPath",
          "maxSize",
          "tag"
        ],
        "additionalProperties": false
      }
    },
    "networks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "cidr": {
            "type": "string"
          },
          "tag": {
            "type": "string"
          }
        },
        "required": [
          "cidr",
          "tag"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "id",
    "name",
    "org",
    "access",
    "visibility",
    "createdBy",
    "nodes",
    "autoCreated",
    "priorityMode",
    "needsReconciliation",
    "volumes",
    "networks"
  ],
  "additionalProperties": false
}
```

</details>

## `set_server_priority`

Set a grid member's scheduling priority, -100 to 100. Higher wins when the grid is contended; -100 means backup only. Admins of the grid's organization.

**Group:** `grids` · **Behavior:** Write

**Compact tool:** `grids_write` · **Action:** `set_server_priority`

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

### Permissions and REST equivalents

| Operation                   | REST                                      | Required scopes |
| --------------------------- | ----------------------------------------- | --------------- |
| `grids.servers.setPriority` | `PATCH /grids/{gridId}/servers/{address}` | `pools:write`   |

### Arguments

| Argument   | Type      | Required | Description                                  |
| ---------- | --------- | -------- | -------------------------------------------- |
| `priority` | `integer` | Yes      | -100 (backup only) to 100                    |
| `gridId`   | `string`  | Yes      | Grid id                                      |
| `address`  | `string`  | Yes      | Server address; must be a member of the grid |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "priority": {
      "type": "integer",
      "minimum": -100,
      "maximum": 100,
      "description": "-100 (backup only) to 100"
    },
    "gridId": {
      "type": "string",
      "minLength": 1,
      "description": "Grid id"
    },
    "address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Server address; must be a member of the grid"
    }
  },
  "required": [
    "priority",
    "gridId",
    "address"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `gridId` (`string`): See the complete response schema below.
* `address` (`string`): See the complete response schema below.
* `priority` (`integer`): See the complete response schema below.

<details>

<summary>Response schema: grids.servers.setPriority</summary>

```json
{
  "type": "object",
  "properties": {
    "gridId": {
      "type": "string"
    },
    "address": {
      "type": "string"
    },
    "priority": {
      "type": "integer"
    }
  },
  "required": [
    "gridId",
    "address",
    "priority"
  ],
  "additionalProperties": false
}
```

</details>

## `control_grid_app`

Start or stop an app on a grid as an admin of the grid's organization. No role on the app is needed (action=start or stop); its creator is notified with the reason. Starting bills the app's organization.

**Group:** `grids` · **Behavior:** Write

**Compact tool:** `grids_write` · **Action:** `control_grid_app`

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

### Permissions and REST equivalents

| Operation          | REST                                        | Required scopes                |
| ------------------ | ------------------------------------------- | ------------------------------ |
| `grids.apps.start` | `POST /grids/{gridId}/apps/{appGuid}/start` | `pools:write`, `compute:spend` |
| `grids.apps.stop`  | `POST /grids/{gridId}/apps/{appGuid}/stop`  | `pools:write`                  |

### Arguments

| Argument  | Type               | Required | Description                                                     |
| --------- | ------------------ | -------- | --------------------------------------------------------------- |
| `action`  | `"start" / "stop"` | Yes      | What to do                                                      |
| `gridId`  | `string`           | Yes      | Grid id                                                         |
| `appGuid` | `string`           | Yes      | Runtime identifier of the app (guid on list\_apps, get\_server) |
| `reason`  | `string`           | No       | Shown to the app's creator in their notification                |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "start",
        "stop"
      ],
      "description": "What to do"
    },
    "gridId": {
      "type": "string",
      "minLength": 1,
      "description": "Grid id"
    },
    "appGuid": {
      "type": "string",
      "minLength": 1,
      "description": "Runtime identifier of the app (guid on list_apps, get_server)"
    },
    "reason": {
      "type": "string",
      "maxLength": 300,
      "description": "Shown to the app's creator in their notification"
    }
  },
  "required": [
    "action",
    "gridId",
    "appGuid"
  ],
  "additionalProperties": false
}
```

</details>

### Result

**`grids.apps.start`**

* `gridId` (`string`): See the complete response schema below.
* `appGuid` (`string`): See the complete response schema below.
* `appId` (`string or null`): The app's id when it is known to the portal
* `appName` (`string or null`): See the complete response schema below.

<details>

<summary>Response schema: grids.apps.start</summary>

```json
{
  "type": "object",
  "properties": {
    "gridId": {
      "type": "string"
    },
    "appGuid": {
      "type": "string"
    },
    "appId": {
      "description": "The app's id when it is known to the portal",
      "type": [
        "string",
        "null"
      ]
    },
    "appName": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "gridId",
    "appGuid",
    "appId",
    "appName"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `403 forbidden`, `409 app_not_on_grid`. **`grids.apps.stop`**

* `gridId` (`string`): See the complete response schema below.
* `appGuid` (`string`): See the complete response schema below.
* `appId` (`string or null`): The app's id when it is known to the portal
* `appName` (`string or null`): See the complete response schema below.

<details>

<summary>Response schema: grids.apps.stop</summary>

```json
{
  "type": "object",
  "properties": {
    "gridId": {
      "type": "string"
    },
    "appGuid": {
      "type": "string"
    },
    "appId": {
      "description": "The app's id when it is known to the portal",
      "type": [
        "string",
        "null"
      ]
    },
    "appName": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "gridId",
    "appGuid",
    "appId",
    "appName"
  ],
  "additionalProperties": false
}
```

</details>

Operation-specific errors: `403 forbidden`, `409 app_not_on_grid`.

## `delete_grid`

Delete a grid (admins). Its servers are kept; sharing grants and invitations are retired.

**Group:** `grids` · **Behavior:** Write

**Compact tool:** `grids_write` · **Action:** `delete_grid`

**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 |
| -------------- | ------------------------ | --------------- |
| `grids.delete` | `DELETE /grids/{gridId}` | `pools:admin`   |

### Arguments

| Argument  | Type     | Required | Description                                |
| --------- | -------- | -------- | ------------------------------------------ |
| `gridId`  | `string` | Yes      | Grid id                                    |
| `confirm` | `true`   | Yes      | Must be true: this action cannot be undone |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "gridId": {
      "type": "string",
      "minLength": 1,
      "description": "Grid id"
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: this action cannot be undone"
    }
  },
  "required": [
    "gridId",
    "confirm"
  ],
  "additionalProperties": false
}
```

</details>

### Result

* `id` (`string`): Id of the deleted grid
* `deleted` (`true`): See the complete response schema below.

<details>

<summary>Response schema: grids.delete</summary>

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of the deleted grid"
    },
    "deleted": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "id",
    "deleted"
  ],
  "additionalProperties": false
}
```

</details>


---

# 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/grids.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.