Skip to main content

​
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
  • 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

​
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:

​
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

​
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

​
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 for pricing, examples, and beta limitations.