> ## 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.5`.

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; default sprite prices are historical compatibility estimates | 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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.