Dreamlayer MCP Server

@dreamlayer/mcp

Image generation and editing tools for MCP-compatible AI clients, backed by the DreamLayer Agent API.

Use it for raster logo concepts, product imagery, marketing visuals, print artwork concepts and game assets. Inspect output quality and task-specific requirements. See the installable agent workflows for task guidance and Godot/Unity import examples.

The full workflow below uses the published sprite-capable beta. Stable latest remains 0.3.0; use the explicit version shown here.

Install

Add it to your client. Claude Code:

claude mcp add dreamlayer --env DREAMLAYER_API_KEY=dlr_live_your_key -- npx -y @dreamlayer/mcp@0.4.0-beta.5

Codex:

codex mcp add dreamlayer --env DREAMLAYER_API_KEY=dlr_live_your_key -- npx -y @dreamlayer/mcp@0.4.0-beta.5

Cursor, or any other stdio MCP client:

{
  "mcpServers": {
    "dreamlayer": {
      "command": "npx",
      "args": ["-y", "@dreamlayer/mcp@0.4.0-beta.5"],
      "env": { "DREAMLAYER_API_KEY": "dlr_live_your_key" }
    }
  }
}

The key must be in the server's own environment. MCP clients spawn this as a subprocess, so a key exported in your shell does not reach it. That is the most common setup failure, and the server exits with an explanation rather than starting up broken.

Get a key at platform.dreamlayer.io. A new account starts at zero credits. Ordinary image operations cost one credit each; sprite bundles use the frame-count quote described below.

Tools

Operations

Omit operation and DreamLayer reads the prompt, which may come back asking a clarifying question. Name it and that inference is skipped entirely.

upscale doubles each side and finished images are capped at 4096 per side, so the longest side of your input must be 2048 or less. A larger one is refused before it costs a credit.

Behaviour worth knowing

A question is not a failure. An ambiguous prompt returns a question event ending in needs_input. Answer it by calling dreamlayer_generate again with respond and the conversation_id.

Retries are safe if you reuse the key. An idempotency_key is generated for you. Pass the same one back to retry after an uncertain response and the original result replays rather than paying twice.

Long runs are truncated, not lost. A stream over 256 events returns what it has, marks truncated, and gives you the execution_id and last event id to resume from.

Errors are stable and provider-neutral. Error tool results include code, reason, message, retryable, and request_id, matching REST and the CLI. A model should branch on reason and retryable, never message text. The response excludes prompts, local filenames, asset URLs, provider details, credentials, and raw upstream responses.

Requirements

Node.js 22.12 or later.

License

MIT. See LICENSE and NOTICE.

Sprite-sheet beta

Sprite requests accept exactly one of options.animation_prompt (1–4000 characters) or an options.action preset (walk, run, idle). Custom prompts can describe characters, creatures, objects, effects or 360° turntables. animation_mode is loop or once; presets default to loop, custom prompts to once. For a turntable, request a stationary camera and rotating subject. Broad requests do not guarantee correct motion, unseen details or successful effect transparency.

Request integer frame_count 7–100 (default 12) and frame_size 32, 64, 128, 256, 512, 720 or 1080 (default 512). These are square export canvases; a larger export does not guarantee additional detail. Aspect ratio and shared alignment are preserved with transparent padding. A bundle contains transparent PNG frames, sheet, atlas, preview and import instructions, including each frame's playback duration. Send background: "keep" in options when transparency is not needed: the frames ship with the generated background in place, plain rather than cut out, and cost the flat plain rate. A frame that cannot be cut out is retried at nearby moments of the same clip, and a single stubborn frame ships with its background rather than failing the sheet; atlas.json lists any such frame in kept_background_frames. Choose a repeating loop or a one-time action with a beginning and ending. If the requested number of distinct frames cannot be delivered, the job fails and held credits are returned. Translucent effects can lose detail or fail; small exports are not automatically pixel art.

Pricing is unchanged across sizes: frames 1–14 cost $0.14 each; additional frames $0.07 each. With background: "keep" every frame is a flat $0.07 with no tier, roughly half a transparent sheet (12 frames: 5.0 credits instead of 9.9). One credit is $0.17. Round the complete order upward once to a tenth of a credit. Check sprite_pricing in capabilities and approve the quote with max_credits. Credits are held during processing, settled after complete delivery and restored on failure/timeout. There is no customer cancellation. Keep the execution ID to resume status. Custom requests need the matching broad-animation server release; older servers reject them. New live generation quality, 100-frame duration and actual cost remain unverified.

Call dreamlayer_upload_image, then dreamlayer_generate with operation: "sprite_sheet", the uploaded input_asset_id, options: {action: "walk", frame_count: 12}, and max_credits set to your approved limit.

Each tool call waits for a bounded interval. If the result remains active, pass its execution_id and last_event_id to dreamlayer_events. When completed, use dreamlayer_download with execution_id and an absolute path ending in .zip. Existing files are never overwritten.

For affordability, compare the complete rounded quote in credits with available. One tenth of a credit is $0.017. Promotional and purchased amounts are displayed rounded down separately, so their displayed sum can be 0.1 credit below available; stored fractions are preserved. Compare against the combined total, not that sum. The order charge rounds only once, never per frame or per tier.

Tool discovery and recovery

Read tools/list for descriptions, input schemas, and operation availability. Read-only calls are marked with readOnlyHint; upload, generation, and local download are not. These annotations describe effects, not permission grants. Generation starts paid work.

Every tool returns structuredContent plus the same JSON serialized in a text block for older clients. Failures set isError: true. Generation results and errors include the idempotency key, including when the server generated it for you. Choose and save your own key before calling when you need recovery even after the MCP process itself is lost.

After interruption, call dreamlayer_execution with the saved execution ID, then dreamlayer_events with the last processed event ID. Retrieve completed work with dreamlayer_download. Never start a replacement generation merely because the stream closed. Keep the same uploaded asset ID and identical arguments when replaying a key.

MCP setup · API overview · Execution recovery

Abrupt stream failures trigger a canonical status read. If state is still uncertain, the error is temporarily_unavailable with recovery guidance and the known execution ID, cursor and retry key. local_output_failed means a completed output could not be written: fix the path and retry dreamlayer_download, not dreamlayer_generate. Client-side input validation uses invalid_request; other unclassified client failures use client_error and are not evidence that generation failed.

Sprite backgrounds in beta.5

options.background selects what the frames look like. remove, the default, cuts every frame out for transparent frames. keep leaves the generated background in place: the frames are plain rather than cut out, and every frame costs the flat sprite_pricing.plain_frame_cents with no tier, about half the transparent price. Twelve frames quote 5 credits kept against 9.9 transparent.

beta.4 and earlier reject this field: their options schema set additionalProperties: false, so a request naming a background never reached the service. Pin beta.5 or later to use it.

A spelled-out background: "remove" is normalised away before the request is sent, because it is exactly what an absent field already means and the service fingerprints the options it receives; sending it would otherwise split one job into two idempotency identities.

Parameter descriptions in beta.4

Every input parameter in tools/list now states what it accepts, including the nested sprite options fields: prompt, conversation_id, max_credits (image operations require exactly 1; sprite jobs at or above the quoted price), aspect_ratio, execution_id and last_event_id. Tool names, arguments and results are unchanged from beta.3.

Error handling updates in beta.3

Malformed event payloads return response_contract_error with retryable: false, preserving the execution ID, last event ID and idempotency key when known. Check client compatibility or contact support; do not submit replacement work. Interrupted network streams still reconcile canonical state.