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

# Agent workflows

Deploy, diagnose, share and operate Kinesis through MCP actions.

The names below are **actions**. In default compact mode, send reads to the group tool and changes to its `_write` tool with `{action, params}`. With `?mode=all`, call the action name directly. `browse_github` and `read_docs` are direct in both modes.

For `profile=openai`, call individual action names directly. Use the [profile guide](/mcp/openai-profile.md) for credential restrictions; `get_byod_token` is unavailable and secrets belong in the portal. Logs remain raw output.

Check identity using `account` → `whoami`, then `account` → `list_orgs`. Choose the organization and check your role. Organization-level actions take its slug in `params.org`; project, app and grid calls resolve it from the resource. In compact mode, use `describe_action` before constructing complex arguments.

## Deploy an app

1. Use `projects` → `list_projects`, or `projects_write` → `create_project` with `org`, `name` and optional `visibility: "private"` or `"org"`.
2. Choose an image, an app template using `apps` → `list_templates`, or a GitHub source through `browse_github`. Read template notes for placeholders.
3. For complex hardware or grid requirements, use `apps` → `check_placement` with `projectId` and placement-related `config`. This checks fit without creating an app.
4. Call tool `apps_write` with:

```json
{
  "action": "create_app",
  "params": {
    "projectId": "<project-id>",
    "name": "web",
    "idempotencyKey": "deploy-web-001",
    "config": {
      "image": "nginx:stable",
      "ports": [{"port": 80, "protocol": "http80_load_balancer"}],
      "instances": {"min": 1, "max": 1}
    }
  }
}
```

In all mode, call `create_app` with only the `params` object above.

Creation attempts to start the app and requires `apps:write` and `compute:spend`. The organization pays. Developers need serverless enabled for this example, or must add an accessible grid to `config.grids.ids`. Inspect `start.state`: for `building`, poll `get_build` with the returned `buildId`, then `get_app_status`. Otherwise follow status directly. Use the returned `endpoints` and verify readiness before reporting a running service.

GPU apps require an accessible grid; serverless GPUs are currently paused. A GPU template’s `notes` explains the required `config.grids.ids`.

### Build from a public repository

As a member of the project’s organization with permission to edit it, set `source.kind: "github"` and the connected `installationId`. Choose either `source.repo` or `source.clone`. A clone needs `sourceRepo` and `targetRepoName`; `targetVisibility` defaults to `private`. It creates a repository in the connected account and builds from that copy. Follow the build's `vcs_import` step and subsequent build status.

Use `browse_github` with `kind: "contents"` to inspect a directory or text file. If a repository lacks a Dockerfile, inspect its build instructions and provide `source.dockerfileContent`. Omit `config.image` and `config.registryAuth` for repository builds.

### Reuse an app's environment

Set `envFrom: {projectId, appId, overrides?}` on `create_app` to copy environment variables and their secret values on the server. The caller needs Developer access to the source app. Omit `config.env`; supply per-key changes in `envFrom.overrides`. A null override retains the copied value, and a copied secret remains secret. This is a copy made at creation, not a live link. See [App configuration](/api/app-configuration.md).

## Diagnose and maintain an app

Start with `apps` → `get_app_status`. Inspect aggregate and per-node state, errors and runtime `workOrders`; grid-backed apps also expose scheduling context such as fill and queue state.

| Finding                             | Next action                                                               |
| ----------------------------------- | ------------------------------------------------------------------------- |
| Building or build failed            | `get_build` and `get_build_logs`                                          |
| Provisioning or stalled placement   | `check_placement`, then `servers` → `get_server` or `get_provision_order` |
| Node health or installation problem | `servers` → `get_server_logs`, for a server in the selected organization  |
| Container errors or repeated exits  | `get_app_logs`; check command, environment, ports and resources           |
| Running but unreachable             | Verify endpoint, listen port and binding to `0.0.0.0`                     |
| High resource use                   | `get_app_usage`                                                           |
| Need a text log export              | `export_logs`; inspect `truncated` before treating the export as complete |

Log retention uses `get_log_retention` and `set_log_retention`: set 1–180 days, or 0 for the platform default. `clear_logs` deletes records older than `olderThan` and requires `confirm: true`.

Read configuration before `update_app`: arrays replace existing arrays, while null retains an existing secret. `move_app` moves an app to another project of the same organization and requires `apps:admin`, an admin role or app-creator permission, and permission to edit the destination; use its returned project ID for subsequent calls.

## Roll back a repository build

1. Use `list_builds` to choose a build whose image was built.
2. Call `apps` → `check_rollback_build` with `projectId`, `appId` and `buildId`. If `imageAvailable` is false, build its commit again with `trigger_build`.
3. With `apps:write` and permission to edit the app, call `apps_write` → `rollback_build`. A running app redeploys; a stopped app uses the image at its next start.
4. Inspect the returned `build` and `redeploying`, then app status.

Rollback changes the image in the current configuration; it does not restore old environment variables or other settings. It cannot run during an active build or before an app has deployed. A later build or automatic deployment replaces it again. The action has write/destructive/idempotent/open-world annotations and no `confirm` argument.

## Invite people and share a project

1. Call `sharing` → `list_members` with `org` to find members and their user IDs.
2. Add a member with `sharing_write` → `add_grantees`: `resourceType`, `resourceId`, and `people: [{userId, role}]`. Access begins immediately. Resource-grant value `editor` means Developer in the portal; `viewer` reads. Grants cannot exceed the organization role, and grids accept `viewer` for use only.
3. For someone new, use `sharing_write` → `invite_member` with `org`, `email`, organization `role` (`admin`, `developer`, `viewer`) and optional `addTo`. The link expires in seven days. Developers invite at their own role or below when enabled.
4. Use `list_member_invitations` and `revoke_member_invitation` for pending invitations. Repeating an invite sends a fresh link; wait at least a minute between sends.

Member reads require `members:read`; changes require `members:write`. Resource sharing and invitation `addTo` also require the resource-family admin scope. Only admins or a project/app’s creator manage its access; only admins manage grid sharing.

Recipients use `account` → `list_org_invitations`, then `account_write` → `answer_org_invitation` with `action: "accept"` or `"decline"`. Credentials limited to organizations or projects cannot answer these invitations. Older resource-invitation actions handle existing invitations only; `invite_user` has been replaced by organization invitations and direct member grants.

Use `set_member_role` to change a role. Use `remove_member` with `confirm: true` to remove someone or leave with your own user ID. Their resources remain and apps keep running. The owner must first use `transfer_ownership` with `confirm: true`; only the current owner may do so.

Manage grants with `list_grantees`, `set_grantee_role` and `revoke_access`. Give up your own grant with `leave_shared_resource`. A remaining project grant or organization-wide visibility may still provide access.

Use `account` → `list_notifications`, and `account_write` for `mark_notifications_seen` or `dismiss_notifications`. Omitting `id` from either write applies to all active notifications.

## Inspect settings and trace activity

Call `account` → `get_org` with `org`. Admins use `account_write` → `update_org` to rename it or change `serverlessEnabled` and `membersCanInvite` with `org:write`. Its slug stays fixed.

Admins read `account` → `list_audit_log` with `org`, optional `limit` and `cursor`, following `nextCursor`. It needs `audit:read` specifically. Entries are latest-recorded-first and include actor, action, outcome, error code, details and changes. Retention is one year. Older OAuth connections need re-approval for new scopes.

## Operate dedicated compute

Work as an organization admin. Include `org` on server, order, SSH and provisioning actions.

1. Use `catalog` → `browse_catalog` to find regions and instance types.
2. Use `servers_write` → `provision_servers` with `dryRun: true` to inspect estimates.
3. When the order matches the user's request, use `dryRun: false` and a new idempotency key.
4. Poll `get_provision_order`, following `pollAfterSec`.
5. Verify `list_servers` or `get_server`. Use `gridIds` during provisioning or add machines to a grid afterwards.

`power_servers` selects hibernate, wake or reboot. Hibernation retains storage costs. Replacement retires the old machine without retaining its disk.

For a machine the user owns, `get_byod_token` returns an expiring, single-use token and install command to run on that machine. The public action uses Kinesis Remote Reach and returns `needVpn: true`; it has no connection-mode or SSH-management input options. The portal separately guides users through Direct or Remote Reach setup. Remote Reach carries TCP app traffic over outbound UDP and does not support UDP app endpoints.

`list_smart_lifecycle` and `set_smart_lifecycle` control automatic idle hibernation and wake-up on owned servers. For SSH, use `list_ssh_keys`, `add_ssh_key` and `assign_ssh_key` with `action: "assign"` or `"unassign"`. Assign only to `eligibleServers` returned by the listing. Remote Reach machines and rented marketplace machines are not eligible. Call `servers_write`; the inner action belongs inside `params`:

```json
{
  "action": "assign_ssh_key",
  "params": {
    "action": "assign",
    "org": "acme",
    "keyId": "<key-id>",
    "addresses": ["<server-address>"]
  }
}
```

For grids, `set_server_priority` accepts -100 to 100; -100 is backup only. `control_grid_app` lets an admin of the grid’s organization start/stop a workload using its runtime `appGuid`. Starting also requires `compute:spend` and bills the app’s organization; its creator receives a notification with the reason.

## Billing and invoices

Use the `billing` tool. `get_balance` and `get_costs` show the selected organization’s balance and costs; billing requires an admin role and `org`; `list_charges` and `list_credits` expose ledger history. `list_invoices` and `get_invoice` return invoice data. Invoice PDF download is REST-only.

MCP does not expose `add_credits` or `set_auto_reload`. On a balance refusal, explain the entitlement and leave billing to an organization admin. MCP errors omit payment links. REST retains checkout sessions, saved-card top-ups and auto-reload updates. Use `billing_write` for `set_default_payment_method` and `remove_payment_method`. Removing the final card disables auto-reload; removal requires `confirm: true`.

`billing_write` → `redeem_voucher` applies a code. `get_node_protection` and `set_node_protection` control balance-triggered hibernation; enabling requires `thresholdHours` from 2 to 48. Node protection depends on remaining balance; Smart Lifecycle depends on idle servers.

## Understand tool annotations

Read tools carry `readOnlyHint: true`. Write tools carry `readOnlyHint: false`; `destructiveHint: true` includes changes to existing state, such as updates, stops, token replacement, notification changes and accepted sharing roles. It does not mean every such action takes `confirm`. The separate `confirm: true` argument is required only where the action schema says so. `openWorldHint` covers public publishing or reaching people beyond Kinesis: deployment/start and domain actions, and `invite_member`, may carry it. Read each action’s annotations rather than inferring them from its name. Clients use these hints to decide how to present approvals; scopes and resource roles still govern execution.

## Stop, delete and retry

Stop apps and poll until stopped before deleting them or their project. A Developer deleting their project must also have created every app inside it; otherwise an admin must act. The current actions requiring `confirm: true` are `delete_project`, `delete_app`, `delete_grid`, `deprovision_servers`, `replace_server`, `clear_logs`, `remove_payment_method`, `remove_member` and `transfer_ownership`. Set it when the user requested or confirmed the action.

Tool failures set `isError: true` and return `structuredContent.error` with a stable `code`, message and code-specific details. MCP tool errors include `requestId` only for server-side failures (status 500 or above), not validation, permission or other client errors. REST error bodies and the HTTP `X-Request-Id` header retain request IDs. Compact action-schema failures include the full `inputSchema` and field paths under `params`. Authentication and rate limits can fail at HTTP level.

Retry transient errors only when safe, reusing an `idempotencyKey` with unchanged arguments where supported. Inspect resources after an uncertain create. Repeating `restart_app` or `trigger_build` performs another restart or build. Fix validation, permissions, placement and balance before retrying.


---

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