> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dreamlayer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tool reference

> Discover image tools, understand their effects, and recover paid work safely.

Requires version `0.4.0-beta.2` or later. Install this beta explicitly with `npx -y @dreamlayer/mcp@0.4.0-beta.3`.

Connect the [Image Agent MCP Server](/mcp/clients), then let your client call `tools/list`. The generation operation enum is narrowed using the hosted API's capabilities. A temporary capability lookup failure falls back to the built-in image operations; it does not prove account access.

| Tool                      | Use it for                                               | Effects                                                         |
| ------------------------- | -------------------------------------------------------- | --------------------------------------------------------------- |
| `dreamlayer_capabilities` | Discover operations and sprite pricing                   | Reads; no generation charge                                     |
| `dreamlayer_balance`      | Check available credits                                  | Reads; no generation charge                                     |
| `dreamlayer_upload_image` | Upload a local reference; returns `input_asset_id`       | Sends the selected file to the hosted API; no generation starts |
| `dreamlayer_generate`     | Generate, edit, remove a background, upscale, or animate | Starts paid work; preserve the request and idempotency key      |
| `dreamlayer_execution`    | Read canonical state using `execution_id`                | Reads; use after uncertainty                                    |
| `dreamlayer_events`       | Resume using `execution_id` and optional `last_event_id` | Reads existing work; does not create a job                      |
| `dreamlayer_download`     | Save a completed execution to an absolute local path     | Writes a new file; does not overwrite or regenerate             |

## First successful workflow

1. Read capabilities and balance.
2. Confirm the requested operation and its cost with the user. Image operations cost one credit; sprites require their quoted `max_credits`.
3. For a reference operation, upload the selected file once.
4. Choose and save an `idempotency_key`, then call `dreamlayer_generate` with the operation and inputs.
5. Read `status`. If it asks a question, collect the missing input. If still running, resume events or read execution state.
6. Download only after completion.

```json theme={null}
{
  "name": "dreamlayer_generate",
  "arguments": {
    "operation": "image_to_image",
    "prompt": "Make the jacket blue",
    "input_asset_id": "d34db33f-0000-4000-8000-000000000002",
    "idempotency_key": "example"
  }
}
```

## Recovery rules

Use `dreamlayer_execution`, not a fresh generation, after a dropped connection. Pass the last processed event ID to `dreamlayer_events`. Reuse the same input asset ID, key, and arguments if replay is necessary. A new upload changes the request.

Errors return `isError: true` and a JSON error with `reason`, `retryable`, and `request_id`. Do not treat a question or a stream boundary as a failed generation. The protocol's text content remains available to clients that do not consume structured results.

Use the installed package's `tools/list` response as the authority for metadata available in that version. Tool annotations describe effects; clients still own permission decisions. See [limits](/agent-api/limits), [retry handling](/agent-api/idempotency-and-retries), and [CLI automation](/cli/automation).