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. create_upload_urls is hidden from Claude’s hosted app because it cannot complete the direct local-file upload to Bloom. Reconnecting does not enable it. The tool remains available to other clients, including Claude Code and ChatGPT. See Upload local files for supported alternatives.

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

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. If check_credits reports that the workspace’s billing account isn’t set up, retrying won’t help. Contact support@trybloom.ai with the billing ID from the message.

​
A local upload cannot reach Bloom

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 a cached create_upload_urls call reports that direct uploads are unsupported, 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. Pass the verified upload IDs to the consuming tool in the returned workspace.
  • 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.