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

# Image Agent MCP Server

> Give an MCP-compatible AI client bounded image tools with one line of config.

# Image Agent MCP Server

## What this lets you do

Give Claude Code, Codex, Cursor, or any MCP-compatible client the ability to generate and edit images through your DreamLayer account, without writing an integration.

## What you need

* Node.js 22.12 or later. If you do not have it: `brew install node` on macOS, or the installer
  at [nodejs.org](https://nodejs.org)
* A DreamLayer API key with credits
* An MCP client that can start a local stdio server

There is nothing to clone and nothing to build. `npx` fetches the published package on first run,
so the first launch pauses for a few seconds while it downloads. Later launches are immediate.

For sprite sheets, use the published `0.4.0-beta.3` version in the commands and
configuration below. It is also available as `@dreamlayer/mcp@beta`. The unversioned
`latest` release remains `0.3.0` and does not include sprite sheets. Existing image
tools remain available in the beta.

## Steps

### 1. Add the server to your client

```bash theme={null}
claude mcp add dreamlayer -- npx -y @dreamlayer/mcp@0.4.0-beta.3
```

### 2. Give it the key

The server reads `DREAMLAYER_API_KEY` from its own environment. Set it in the MCP server's config block rather than exporting it globally, so the key is scoped to this one process:

```json theme={null}
{
  "mcpServers": {
    "dreamlayer": {
      "command": "npx",
      "args": ["-y", "@dreamlayer/mcp@0.4.0-beta.3"],
      "env": { "DREAMLAYER_API_KEY": "dlr_live_your_key_here" }
    }
  }
}
```

### 3. Apply the client rules

* Read capabilities first and require `api_version` to be `1`. That is the Agent API contract
  version, and it is the same `1` you send as the `DreamLayer-Version` header.
* Use `dreamlayer_balance` to read the current key owner's credits without starting paid work.
* Assign one stable idempotency key per logical mutation, and reuse it on retry.
* Persist opaque IDs and the latest event ID so a dropped stream can resume.
* Treat a `question` event ending in `needs_input` as a prompt for the user, not a failure.
* Never request provider, model, workflow, routing, or internal-cost metadata. It is not exposed.
* Branch on the returned public error `reason` and `retryable` fields. Preserve the request ID for support.

## Confirm it worked

The client lists DreamLayer tools, the capabilities tool reports `api_version: "1"`
and includes `sprite_sheet`, and `dreamlayer_balance` returns your balance. These
are read-only checks. Generating and downloading an asset is a separate, billable
check that requires your approval.

## Common errors

| Error                                 | What to do                                                                                                                             |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| The tool list is empty                | Confirm the client starts the server as a stdio process and that Node.js is on its PATH.                                               |
| Every tool call returns an auth error | `DREAMLAYER_API_KEY` is unset in the server's environment. A key exported in your shell does not reach a subprocess the client spawns. |
| Generation fails with no credits      | Buy a pack on the Billing page. A new account starts at zero.                                                                          |

## Troubleshooting

The server writes JSON-RPC to stdout and logs to stderr. If a client reports a protocol error, check that nothing else is writing to stdout in the same process.

## Next steps

* [Configure a specific client](/mcp/clients)
* [Use the same key from the command line](/cli)
* [Review jobs and events](/agent-api/jobs-and-events)

## Sprite-sheet beta

Upload a reference with `dreamlayer_upload_image`, then call `dreamlayer_generate`
with `operation: "sprite_sheet"`, the returned `input_asset_id`, an approved
`max_credits`, and `options`. Supply exactly one of `animation_prompt` or an
`action` preset (`walk`, `run`, or `idle`).

Options also include `animation_mode` (`loop` or `once`), `frame_count` (7–100,
default 12), and `frame_size` (32, 64, 128, 256, 512, 720, or 1080, default 512).
Custom instructions default to `once`; presets default to `loop`.
The frame-size response issue is fixed; 512 is the default, not a required workaround.
Retrieve existing completed outputs using their original execution IDs without regenerating.

For example, ask: "Make a 7-frame, 512-pixel looping 360-degree sprite turntable
from this image. Keep the pose fixed and the camera stationary. I authorize at
most 5.8 API credits. Save the completed ZIP as turntable.zip."

The assistant should obtain spending approval before submitting. Use the returned
execution ID to follow events or status and download the finished ZIP. Credits
settle on complete delivery or return on failure or timeout. Sprite requests have
no customer cancellation. See [sprite sheets](/agent-api/sprite-sheet) for pricing,
examples, and beta limitations.