Skip to main content
Rainbrand MCP tools can return structured content or a tool result marked with isError. Read both the content and error state before continuing.

​
A tool is missing

Refresh your client’s tool list. If the tool is still missing, reconnect Rainbrand and complete authentication again. Only call tools listed in the refreshed tools/list response.

​
Authentication fails

  • For OAuth, reconnect Rainbrand and complete the browser sign-in again.
  • For an API key, confirm that the header uses x-api-key or Authorization: Bearer, that the complete key is present, and that the key has not been revoked.
  • Confirm the current identity with get_account after reconnecting.
Never paste a secret into a prompt or commit it to a project file. See Connect Rainbrand for client-specific configuration.

​
An existing connection still shows Bloom

A connection added with the former https://mcp.trybloom.ai/mcp address or a bloom server name keeps working with the same account, brands, and tools. You don’t need to reconnect. To show the new name, remove the old connection, then add Rainbrand with https://mcp.rainbrand.com/mcp.

​
A brand is still processing

Call get_brand with the returned brand_session_id and wait: true. If it returns analyzing, repeat the same read. A timeout leaves analysis running; do not create another brand to check progress. Waiting applies only to current initialization. Omit version_id when checking progress: a version-specific read returns the saved snapshot immediately. timeout has no effect without wait: true. For a newly created brand, stop waiting when the status is ready or failed. A failed brand includes a machine-readable failure code and a message safe to show to the user; unavailable canonical fields are omitted. An existing legacy Visual DNA brand can return logo_required. Stop waiting and create a new brand from sources if needed; MCP cannot replace its logo.

​
A Brand Edit is still preparing

If create_brand_edit or continue_brand_edit returns preparing, call get_brand_edit with the same edit_id and wait: true. Repeat that read if it times out while preparation continues; do not start another edit to check progress. Stop waiting when the edit requests input, produces a candidate, or ends in another state. Follow the corresponding action in Edit a brand.

​
An image is still processing

Generation and image transformations return new image IDs immediately. For one image, call get_image with wait: true. For several, call list_images once with all image_ids and wait: true. Check the returned status. A timed-out wait can return a pending operation, and an accepted operation can later fail. Do not present a result until it is completed and has an image_url.

​
Tool arguments are rejected

Read the current input schema returned by tools/list. Common causes include:
  • a missing required Brand ID or image ID;
  • an invalid UUID;
  • a value outside an enum such as aspect ratio, model, or image size;
  • too many reference images or variants; or
  • using API-style camelCase fields in an MCP tool that expects snake_case.
Correct the arguments rather than retrying the same request.

​
The request is rate-limited

API-key requests share one request budget across REST and MCP. MCP returns rate_limit_exceeded when that key is over its limit. Honor the Retry-After header when present; otherwise wait for the documented reset period before retrying. OAuth access tokens do not use this API-key request limiter. See Credits and limits.

​
Generation cannot start

Before retrying, check:
  1. the brand exists and is ready;
  2. the source or reference image exists and is accessible;
  3. the workspace has enough credits; and
  4. the requested size is available to the current plan.
Use check_credits for the selected workspace. Billing failures can include an action URL for purchasing credits, resuming a subscription, or changing plan. When Model Gateway billing is enabled, a billing rejection returns a tool result marked with isError. Its text explains the failure and includes a pricing link. Follow that explanation before retrying; see Credits and limits for eligibility and charges. If check_credits reports that the workspace’s billing account isn’t set up, retrying won’t help. Contact support@rainbrand.com with the billing ID from the message.

​
A local upload cannot reach Rainbrand

A filesystem path on the agent’s machine is not a public URL. Private attachment URLs from the host client are not supported. Use the upload guide to choose between the MCP picker, direct HTTP upload, and a public HTTPS URL. If the client cannot execute the PUT returned by create_upload_urls, switch to an available alternative. For picker errors:
  • Pass exactly one destination to open_upload_ui: workspace_id for staging or brand_session_id for saving images to a Brand Library. Use workspace_id: null to stage in your personal workspace.
  • Resolve a staging reference with get_file_picker_handoff before using it. Use the verified upload IDs with Rainbrand tools that accept them in the returned workspace, and each file’s temporary url where a generation model input expects a file URL.
  • If images were saved to a Brand Library but the agent cannot see them, use the final Library image IDs in the picker’s chat message. These are ready to use without resolving a staging reference.
  • If some files fail, retry them or let the user explicitly Continue with successful files. Never include failed uploads, and do not start onboarding after cancellation or when no files succeeded.
  • Upload expired files again.
For a workspace mismatch, stage the files in the brand’s workspace. For a new brand, use the same workspace for staging and onboarding. Follow the workspace instructions when passing a picker handoff to another tool. Staging alone does not finish the task. Check the consuming tool’s result before reporting success. For a logo change, follow Edit a brand after saving the image to the Brand Library. Older Visual DNA brands do not support logo replacement.