MCP Tools
Novabrand exposes nine MCP tools for project discovery, setup, image lookup, generation, polling, and credit checks.
Tool reference
| Tool | Purpose | Required input |
|---|---|---|
| list_projects | List account projects and brand readiness. | none |
| create_project | Create a project from a brand website. | name, website_url |
| check_brand_analysis | Poll setup status after project creation. | brand_analysis_id |
| list_product_images | List product images available in a project. | project_id |
| list_models | List reusable brand model images. | project_id |
| generate_ad | Generate ad creatives asynchronously. | project_id, product_image_uuids, generation_type |
| generate_model_shot | Generate model photoshoots asynchronously. | project_id, product_image_uuids, model_image_uuids |
| check_generation | Poll generation status and final assets. | kind, id |
| get_credits | Read remaining generation credits and plan limits. | none |
Generation options
| Field | Applies to | Notes |
|---|---|---|
| generation_type | generate_ad | campaign, pdp_hero, text_ad, ugc_ad, lifestyle, or studio. |
| variant_count | generate_ad, generate_model_shot | Integer from 1 to 5. |
| aspect_ratio | generate_ad | Optional values such as 1:1, 4:5, 9:16, or 16:9. |
| quality | generate_ad | Optional values such as 1K, 2K, or 4K. Higher quality can cost more credits. |
| custom_prompt | generate_ad | Optional ad/product photoshoot prompt, maximum 600 characters. |
| scene | generate_model_shot | Optional model photoshoot scene prompt, maximum 500 characters. |
| guidance.style | generate_model_shot | ugc, balanced, or editorial. |
| guidance.framing | generate_model_shot | auto, wide, portrait, hands, detail, or shoulder. |
Creative types
| generation_type | Best for |
|---|---|
| campaign | A polished campaign creative with the product in an on-brand scene. |
| pdp_hero | A hero image suited to a product detail page. |
| text_ad | A creative formatted for text-forward ad placements. |
| ugc_ad | A casual, user-generated-content style ad. |
| lifestyle | The product shown in a real-world lifestyle setting. |
| studio | A studio-style product shot on a clean background. |
Image list result fields
list_product_images returns product_images and list_models returns model_images. Pass the file_uuid of each item as product_image_uuids or model_image_uuids when you generate.
| Field | Meaning |
|---|---|
| file_uuid | The image id to pass into generate_ad or generate_model_shot. |
| url | A viewable URL for the image. |
| file_name | The original file name. |
| project_uuid | The project the image belongs to. |
| source | model_images only. How the model image was added, for example uploaded. |
Polling result fields
check_brand_analysis and check_generation share the same status fields. Keep polling until the work finishes, then read the result.
| Field | Meaning |
|---|---|
| status | queued, processing, completed, or failed. |
| progress | Progress from 0 to 100. |
| current_stage | Brand setup moves through queued, analyzing, finalizing, and complete. Generation moves through preparing, refining, generating, finalizing, and complete. |
| completed | check_generation only. Becomes true once the asset is ready. |
| project_uuid | check_brand_analysis only. Present once brand setup completes. |
| brand_profile | check_brand_analysis only. The brand profile produced once setup completes. |
| asset | check_generation only. The generated asset object once completed, otherwise null. |
| error_message | A safe summary when a job fails, otherwise null. |
Generated asset fields
When check_generation reports completed: true, the asset holds one entry per variation in generated_assets.
| Field | Meaning |
|---|---|
| generated_assets[].asset_url | The image URL for the variation. |
| generated_assets[].preview_url | A smaller preview image URL. |
| generated_assets[].title | A suggested title when one is generated. |
| generated_assets[].ad_copy | Generated ad copy when available. |
| generated_assets[].is_watermarked | true when the returned image is a watermarked preview. |
| generation_type | The creative type that was requested. |
| variant_count | How many variations were generated. |
Watermarking
Free plans return generated images as watermarked previews while paid plans return the original-resolution images. Check is_watermarked before you publish an asset.
Credit fields
| Field | Meaning |
|---|---|
| limit | Generation credits included in the current plan period. |
| used | Credits already used in the current period. |
| remaining | Credits still available this period. |
| plan | The readable plan name. |
| billingPeriodStart | The start of the current credit period. |
| billingPeriodEnd | The end of the current credit period. |
How credits are counted
Each generation costs variant_count multiplied by a quality factor, so higher output quality costs more per image. The exact charge for a request is returned as credits_used when the generation starts.