App lifecycle

Inspect desired and actual app state, then start, stop, restart or delete.

Inspect desired and actual app state, then start, stop, restart or delete.

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.

get_app_status

Read the live status of an app from the runtime. Aggregate state, each server's container state, where each port answers, recent errors. Poll this after start, stop or delete.

Group: apps · Behavior: Read

Compact tool: apps · Action: get_app_status

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

Permissions and REST equivalents

Operation	REST	Required scopes
apps.status	GET /projects/{projectId}/apps/{appId}/status	apps:read

Arguments

Argument	Type	Required	Description
projectId	string	Yes	Project id
appId	string	Yes	App id

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    }
  },
  "required": [
    "projectId",
    "appId"
  ],
  "additionalProperties": false
}

Result

• state ("unknown" / "running" / "stopped" / "starting" / "stopping" / "scaling" / "updating" / "downloading" / "provisioning" / "start_blocked" / "error" / "building" / "build_failed"): Aggregate state; build states win while there is no runnable image

• targetState ("running" / "stopped" / "unknown"): What the runtime was last asked for; unknown until it has been asked, as for a repository app before its first build succeeds

• nodes (array<object>): Servers the app is placed on and the container state on each

• endpoints (array<object>): Where each configured port answers; a load-balanced port gets its address a minute or two after the first start

• errors (array<object>): Recent runtime errors, newest first

• workOrders (array<object>): The runtime's latest instructions to servers, newest first; an order that never completes is the stall

• grid (object or null): Grid placement details; null for a serverless app

• pollAfterSec (integer or null): Seconds to wait before reading the status again while it is changing; null in a settled state

• id (string): App id

Response schema: apps.status

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "enum": [
        "unknown",
        "running",
        "stopped",
        "starting",
        "stopping",
        "scaling",
        "updating",
        "downloading",
        "provisioning",
        "start_blocked",
        "error",
        "building",
        "build_failed"
      ],
      "description": "Aggregate state; build states win while there is no runnable image"
    },
    "targetState": {
      "type": "string",
      "enum": [
        "running",
        "stopped",
        "unknown"
      ],
      "description": "What the runtime was last asked for; unknown until it has been asked, as for a repository app before its first build succeeds"
    },
    "nodes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "reportedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the server last reported this state; not a start time"
          }
        },
        "required": [
          "address",
          "state",
          "reportedAt"
        ],
        "additionalProperties": false
      },
      "description": "Servers the app is placed on and the container state on each"
    },
    "endpoints": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "port": {
            "type": "integer",
            "description": "Container port, as in config.ports"
          },
          "protocol": {
            "type": "string",
            "description": "Protocol of that port, as in config.ports"
          },
          "address": {
            "description": "An http(s) URL for the HTTP protocols, host:port for the others; null until the endpoint is wired",
            "type": [
              "string",
              "null"
            ]
          },
          "server": {
            "description": "Server address of a direct tcp or udp endpoint; null when load-balanced",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "port",
          "protocol",
          "address",
          "server"
        ],
        "additionalProperties": false
      },
      "description": "Where each configured port answers; a load-balanced port gets its address a minute or two after the first start"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "at": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          },
          "details": {
            "anyOf": [
              {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {}
              },
              {
                "type": "null"
              }
            ],
            "description": "Extra data the runtime attached, such as the grid or server involved"
          }
        },
        "required": [
          "type",
          "message",
          "at",
          "details"
        ],
        "additionalProperties": false
      },
      "description": "Recent runtime errors, newest first"
    },
    "workOrders": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "What the runtime asked the server to do"
          },
          "server": {
            "type": "string",
            "description": "Server address"
          },
          "status": {
            "type": "string"
          },
          "createdAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          },
          "startedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          },
          "completedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "type",
          "server",
          "status",
          "createdAt",
          "startedAt",
          "completedAt"
        ],
        "additionalProperties": false
      },
      "description": "The runtime's latest instructions to servers, newest first; an order that never completes is the stall"
    },
    "grid": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "fill": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "target": {
                      "type": "integer",
                      "description": "Members the grid is composed to have"
                    },
                    "online": {
                      "type": "integer",
                      "description": "Members the app runs on"
                    },
                    "pending": {
                      "type": "integer"
                    },
                    "converging": {
                      "type": "boolean",
                      "description": "The grid is still acquiring members or placing the app"
                    }
                  },
                  "required": [
                    "target",
                    "online",
                    "pending",
                    "converging"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "null"
                }
              ],
              "description": "How far the grid has filled for this app"
            },
            "idleReclaim": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "gridId": {
                    "type": "string"
                  },
                  "warnedAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "description": "ISO 8601 timestamp (UTC)"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "evictAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "description": "ISO 8601 timestamp (UTC)"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "When the app becomes evictable; null when the grid only warns"
                  },
                  "evictedAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "description": "ISO 8601 timestamp (UTC)"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "cooldownEndsAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "description": "ISO 8601 timestamp (UTC)"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "When the grid takes the app again after an eviction"
                  },
                  "evidence": {
                    "type": "string",
                    "description": "Why the grid considers the app idle"
                  }
                },
                "required": [
                  "gridId",
                  "warnedAt",
                  "evictAt",
                  "evictedAt",
                  "cooldownEndsAt",
                  "evidence"
                ],
                "additionalProperties": false
              },
              "description": "Grids whose idle policy has warned or evicted the app"
            },
            "queue": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "gridId": {
                    "type": "string"
                  },
                  "position": {
                    "type": "integer",
                    "description": "1-based place in the grid's fair-share queue"
                  },
                  "queueLength": {
                    "type": "integer"
                  },
                  "enqueuedAt": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "date-time",
                        "description": "ISO 8601 timestamp (UTC)"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "held": {
                    "type": "boolean",
                    "description": "The scheduler keeps the app off the grid until its turn comes"
                  }
                },
                "required": [
                  "gridId",
                  "position",
                  "queueLength",
                  "enqueuedAt",
                  "held"
                ],
                "additionalProperties": false
              },
              "description": "Full grids the app is queued on"
            }
          },
          "required": [
            "fill",
            "idleReclaim",
            "queue"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "Grid placement details; null for a serverless app"
    },
    "pollAfterSec": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Seconds to wait before reading the status again while it is changing; null in a settled state"
    },
    "id": {
      "type": "string",
      "description": "App id"
    }
  },
  "required": [
    "state",
    "targetState",
    "nodes",
    "endpoints",
    "errors",
    "workOrders",
    "grid",
    "pollAfterSec",
    "id"
  ],
  "additionalProperties": false
}

start_app

Ask the runtime to start an app. Returns once the request is accepted; poll the status to follow it.

Group: apps · Behavior: Write

Compact tool: apps_write · Action: start_app

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

Permissions and REST equivalents

Operation	REST	Required scopes
apps.start	POST /projects/{projectId}/apps/{appId}/start	apps:write, compute:spend

Arguments

Argument	Type	Required	Description
projectId	string	Yes	Project id
appId	string	Yes	App id

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    }
  },
  "required": [
    "projectId",
    "appId"
  ],
  "additionalProperties": false
}

Result

• id (string): App id

• targetState ("running" / "stopped"): State the runtime is now converging on

Response schema: apps.start

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "App id"
    },
    "targetState": {
      "type": "string",
      "enum": [
        "running",
        "stopped"
      ],
      "description": "State the runtime is now converging on"
    }
  },
  "required": [
    "id",
    "targetState"
  ],
  "additionalProperties": false
}

Operation-specific errors: 402 balance_over_limit, 429 grid_quota_exceeded, 403 serverless_disabled.

stop_app

Ask the runtime to stop an app. Returns once the request is accepted; poll the status to follow it.

Group: apps · Behavior: Write

Compact tool: apps_write · Action: stop_app

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

Permissions and REST equivalents

Operation	REST	Required scopes
apps.stop	POST /projects/{projectId}/apps/{appId}/stop	apps:write

Arguments

Argument	Type	Required	Description
projectId	string	Yes	Project id
appId	string	Yes	App id

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    }
  },
  "required": [
    "projectId",
    "appId"
  ],
  "additionalProperties": false
}

Result

• id (string): App id

• targetState ("running" / "stopped"): State the runtime is now converging on

Response schema: apps.stop

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "App id"
    },
    "targetState": {
      "type": "string",
      "enum": [
        "running",
        "stopped"
      ],
      "description": "State the runtime is now converging on"
    }
  },
  "required": [
    "id",
    "targetState"
  ],
  "additionalProperties": false
}

restart_app

Stop an app, wait for it to report stopped, then start it again. It waits up to waitSec (default 30); if the app is still stopping when the wait runs out the start is issued anyway; check get_app_status afterwards.

Group: apps · Behavior: Write

Compact tool: apps_write · Action: restart_app

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

Permissions and REST equivalents

Operation	REST	Required scopes
apps.restart	POST /projects/{projectId}/apps/{appId}/restart	apps:write, compute:spend

Arguments

Argument	Type	Required	Description
waitSec	integer	No	Seconds to wait for the stop before starting, 0 to 180 (default 30)
projectId	string	Yes	Project id
appId	string	Yes	App id

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "waitSec": {
      "type": "integer",
      "minimum": 0,
      "maximum": 180,
      "description": "Seconds to wait for the stop before starting, 0 to 180 (default 30)"
    },
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    }
  },
  "required": [
    "projectId",
    "appId"
  ],
  "additionalProperties": false
}

Result

• id (string): App id

• targetState ("running"): State the runtime is now converging on

• stoppedBeforeStart (boolean): The app reported stopped before the start was issued; false when the wait ran out

• waitedSec (integer): Seconds spent waiting for the stop

Response schema: apps.restart

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "App id"
    },
    "targetState": {
      "type": "string",
      "const": "running",
      "description": "State the runtime is now converging on"
    },
    "stoppedBeforeStart": {
      "type": "boolean",
      "description": "The app reported stopped before the start was issued; false when the wait ran out"
    },
    "waitedSec": {
      "type": "integer",
      "description": "Seconds spent waiting for the stop"
    }
  },
  "required": [
    "id",
    "targetState",
    "stoppedBeforeStart",
    "waitedSec"
  ],
  "additionalProperties": false
}

Operation-specific errors: 402 balance_over_limit, 429 grid_quota_exceeded, 403 serverless_disabled.

delete_app

Delete a stopped app (admins, or its creator). Fails with app_running while any node is still live. Irreversible.

Group: apps · Behavior: Write

Compact tool: apps_write · Action: delete_app

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
apps.delete	DELETE /projects/{projectId}/apps/{appId}	apps:admin

Arguments

Argument	Type	Required	Description
projectId	string	Yes	Project id
appId	string	Yes	App id
confirm	true	Yes	Must be true: this action cannot be undone

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: this action cannot be undone"
    }
  },
  "required": [
    "projectId",
    "appId",
    "confirm"
  ],
  "additionalProperties": false
}

Result

• id (string): Id of the deleted app

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

Response schema: apps.delete

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

Operation-specific errors: 409 app_running.