Skip to main content
Bloom 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 the client’s tool list or reconnect the server. Bloom returns the tools currently available to the authenticated account, and that set can vary during a rollout. Do not call a tool remembered from another account, an earlier session, or copied documentation when it is absent from the current tools/list response.

​
Authentication fails

  • For OAuth, reconnect Bloom 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 bloom_get_account after reconnecting.
Never paste a secret into a prompt or commit it to a project file. See Connect Bloom for client-specific configuration.

​
A Brand is still processing

bloom_onboard_brand returns as soon as creation is queued. Call bloom_get_brand with the returned id and wait: true. A bounded wait can return status: "analyzing". Repeat the same call with the same ID. Generate only after the Brand reports ready.
  • logo_required means an older Brand or explicit-logo onboarding run needs another logo.
  • failed includes a machine-readable failure code and a message safe to show to the user.

​
An image is still processing

Generation and image transformations return new image IDs immediately. For one image, call bloom_get_image with wait: true. For several, call bloom_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 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 bloom_check_credits for the selected workspace. Billing failures can include an action URL for purchasing credits, resuming a subscription, or changing plan.

​
A local upload cannot reach Bloom

A filesystem path on the agent’s machine is not a public image URL.
  • In clients that support MCP Apps, use bloom_open_upload_ui for images or bloom_open_logo_upload_ui for a primary logo.
  • In a headless workflow, use bloom_create_image_upload_url or bloom_create_logo_upload_url, upload the bytes as directed, then use the returned image or Brand result.
  • Use bloom_upload_image only when the source already has a publicly reachable URL.
Read the live tool descriptions before starting a signed upload; the image and logo flows are intentionally separate.