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.

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:

{
  "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.

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.

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.

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:

{
  "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.