> 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

Practical sequences for deployment, diagnosis, dedicated compute and billing.

Use these sequences to turn an intent into a reliable series of tool calls. Discover IDs from listings, inspect the user's permissions with `whoami`, and use `read_docs` when a feature is unfamiliar.

## Deploy an app

{% stepper %}
{% step %}

### Choose a project and source

Call `list_projects` or `create_project`. Choose an image, a template from `list_templates`, or a repository through `browse_github`. A template's `notes` explains any placeholders to replace before deployment.
{% endstep %}

{% step %}

### Create the app

Call `create_app` with the project ID, a name and configuration. For a container image, set `config.image`. For GitHub, provide `source` and omit `config.image`; the build supplies the image.

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

Creation attempts to start the app and requires spending permission. Choose resources that fit the user's request before calling it.
{% endstep %}

{% step %}

### Verify the result

Inspect `start.state`. For `building`, poll `get_build` using the returned `buildId`, then read `get_app_status`. Otherwise, follow app status directly. Use `endpoints` from status for the deployed addresses. Report a running service only after status and its endpoint support that conclusion.
{% endstep %}
{% endstepper %}

## Diagnose an app

Start with `get_app_status`. It separates aggregate state, desired state, per-node state and recent errors. Use `get_app_logs` for runtime output, `get_app_usage` for resource utilization, and `get_build_logs` for image-build failures.

| Observation                        | Useful next step                                                        |
| ---------------------------------- | ----------------------------------------------------------------------- |
| `building`                         | Follow `get_build`; inspect builder logs                                |
| `build_failed`                     | Read the failed step and logs; correct source settings or Dockerfile    |
| `provisioning`                     | Inspect grids, servers and pending orders                               |
| `start_blocked`                    | Read errors, placement requirements and balance                         |
| Container errors or repeated exits | Check command, environment, ports and runtime logs                      |
| Running but unreachable            | Check returned endpoint, container listen port and binding to `0.0.0.0` |

Describe the finding before proposing a change. For `update_app`, arrays replace existing arrays, so read configuration first and carry forward entries the user wants to keep. Secret values return null; retain null to preserve an existing secret.

## Order dedicated compute

1. Call `browse_catalog` for regions, zones and instance types.
2. Call `provision_servers` with `dryRun: true` to inspect estimated cost and balance requirements.
3. After the user chooses the order, call it with `dryRun: false` and a new idempotency key.
4. Poll each returned order with `get_provision_order`, following `pollAfterSec` where available.
5. Verify the registered machines with `list_servers`. Add them to a grid, or pass `gridIds` during provisioning to join them on arrival.

`power_servers` combines hibernate, wake and reboot. Hibernation retains the disk and its storage cost. Wake can fail when the provider has no available capacity. Replacement retires the old machine without retaining its disk.

## Stop and delete

Call `stop_app`, poll for stopped, then call `delete_app` with `confirm: true`. Project deletion similarly requires its apps to be stopped.

`delete_project`, `delete_app`, `delete_grid`, `deprovision_servers` and `replace_server` require `confirm: true`. Set it only when the user has requested or confirmed that specific action. The flag is a deliberate acknowledgment, not a way to resolve an unrelated error.

## Add credits

Use `get_balance` and `get_costs` to establish the current state. `add_credits` returns a hosted payment URL for the user to open; it does not charge their card itself. `set_auto_reload` changes automatic charging behavior and should be used only when the user asks to change it. Direct saved-card charges are available through REST, not through MCP tools.

## Handle errors and uncertain outcomes

A failed tool result sets `isError: true` and includes `structuredContent.error` with `code`, `message`, `requestId` and any code-specific fields. Authentication and rate limits may fail at HTTP level before a tool runs.

Retry transient failures only when repeating the action is safe. Reuse an `idempotencyKey` with the same arguments where supported; after an uncertain create, inspect the resource before starting another one. A new call to `restart_app` or `trigger_build` performs another restart or build.

For validation, permission, placement, balance and lifecycle errors, correct the cause first. Include the request ID when escalating to support.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kinesis.network/mcp/workflows.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.