MCP Tool Catalog

The NativeAds MCP server exposes 34 tools. This page lists each one with its purpose, key inputs, and behavior hints. See Connect via MCP to set up a client, and the REST API Guide for the underlying HTTP shapes.

New to the platform? Call get_started first for orientation, then follow the Recommended workflow below. It is the order that produces on-brand results.

Reading the annotations

Each tool carries hints that clients use to decide how to present it:

• Read-only — does not change any state.
• Idempotent — calling it again with the same input has the same effect.
• Destructive — permanently removes data. Only one tool is destructive: delete_brand_dna_version.
• Async — returns a task id; poll get_task until terminal is true. Eight tools are async.

Unless noted, string ids are required. Optional inputs are marked.

Recommended workflow

Brand DNA is the platform's model of a brand's visual and verbal identity, and it is what makes generated creative on-brand. Create it before generating.

Guide, do not one-shot. When a human is present, do not silently create a brand and extract DNA end to end. Explain what you are about to do, ask what the user can provide (above all their logo and brand assets), and recommend the choices that raise quality. Confirm with the user before every meaningful action, creating the brand, starting Brand DNA, uploading assets, and generating; propose and wait for a yes rather than acting silently.

0. Orient — call get_started for the plan, whether Brand DNA is available, whether a brand exists, and a suggested next action.
1. Create the brand — ask the user for the brand name and their logo, propose an industry and a short description, and confirm these before calling create_brand (only name is required; or find an existing brand with list_brands). Do not upload the logo or other files yet: asset upload needs the brand to exist, so it happens in step 2.
2. Add Brand DNA and activate it — Brand DNA is the platform's model of the brand's visual and verbal identity and the single biggest driver of output quality, the core of what makes NativeAds on-brand. Explain this to the user, then guide them to get the most out of it: recommend the full set together, their logo and brand assets (images and videos), any brand-guideline PDFs, and their website URL(s). Do not assume a URL alone is enough or quietly fall back to URL-only. Call get_active_brand_dna; if it returns nothing, the brand has none yet. Confirm what the user will provide, upload each asset and PDF (initiate_asset_upload with isLogo: true for the logo → client PUT → confirm_asset_upload), then call create_brand_dna_version with those assetIds and the website urls together. Proceed with a smaller set, or skip Brand DNA, only when the user explicitly declines; tell them the output will be off-brand, then it is their call. Poll get_brand_dna_version until its status is ready (get_task reports the workflow as completed, not ready). Then review it with the user: state the confidence score and any missing fields, and if the DNA is weak or missing the logo or brand colors, recommend adding it and offer to re-run with rerun_brand_dna_version. Correct wrong content via patch_brand_dna_version / update_brand_dna_version, then activate_brand_dna_version. Generation without active Brand DNA still runs, but output will be off-brand.
3. Enhance the prompt (recommended) — enhance_scene_forge_prompt / enhance_img2video_prompt, poll get_task until terminal, then read the result with get_scene_forge_prompt_enhancement / get_img2video_prompt_enhancement and review the enhanced prompt before generating.
4. Generate — scene_forge (images) or image_to_video (video); pass promptIsEnhanced: true when you use an enhanced prompt (for video, as userPrompts: [enhancedPrompt]). Feature the real product via productAssetIds (+ environmentAssetId); a Scene Forge image makes a strong startImageAssetId for video. Brand DNA is applied by default for scene_forge, but must be requested with useBrandDna: true for image_to_video and enhance_img2video_prompt. Newly uploaded assets must reach status complete (poll list_assets) before you reference them.
5. Retrieve output — poll get_task until terminal; the submit result's resultTool names the reader. A completed scene_forge returns several variations sorted best-first: present them all, relay each variation's warnings verbatim as non-fatal advisories, and skip any variation carrying an errorCode. Use download_asset for a shareable URL per chosen asset.

get_task reports status only, never the result payload — always read the actual output with the get_*/list_* tool the submit result named.

Iterating. For a cohesive set, hold productAssetIds, environmentAssetId, and theme constant and vary only the prompt, reusing one confirmed enhanced prompt across siblings. For more of the same look, prefer extend_scene_forge / extend_generated_videos_group over a fresh call. There is no seed or negative-prompt field; write "avoid X" into the prompt.

Choosing options. aspectRatio maps to placement: 9:16 stories/reels, 1:1 square feed, 3:4 portrait, 16:9 display/YouTube, 21:9 wide banner (2:3/3:2/4:3 also available). Choose deliberately; a mismatch can raise a hard-spec warning. image_to_video dimension in pixels: 16:9 is 1280x720, 9:16 is 720x1280.

Handling failures. A failed task carries an error class: UserRequestError (including content-policy) means fix inputs and do not resubmit unchanged (its message is safe to show); ModelProviderError is transient, retry later; NativeAdsSystemError, surface generically. get_task's retryable reflects this. On a tool error, data.type guides you: upgrade_required (plan lacks the feature, e.g. Brand DNA, or a limit is reached), payment_required (billing inactive or past due), conflict (re-read and retry), invalid_argument, not_found.

Connection errors happen before a tool runs (HTTP, not tool errors): 401 = missing/expired/revoked key or OAuth token; 403 = the credential is not a machine principal (mint a per-user API key); 429 = org rate limit, back off and slow polling.

Language. This MCP surface currently returns English-canonical Brand DNA and enhanced prompts; there is no per-request output language yet.

Brands

Tool	Purpose	Key inputs	Hints
create_brand	Create a brand in your organization. Only name is required.	name; optional industry, description, mission, values[], tone[], voice[], logoAssetId	write
list_brands	List brands, with optional filters.	optional industry, name, sortBy	read-only
get_brand	Fetch a single brand.	brandId	read-only
update_brand	Update brand fields; only fields you pass change.	brandId; optional name, industry, description, mission, logoAssetId, values[], tone[], voice[]	idempotent

Brand DNA

Brand DNA is extracted asynchronously from uploaded assets and/or URLs. Exactly one version is active at a time; creating a version does not activate it, call activate_brand_dna_version once it is ready.

Tool	Purpose	Key inputs	Hints
create_brand_dna_version	Start a new Brand DNA extraction from assets/URLs.	brandId; optional name, assetIds[], urls[]	async
rerun_brand_dna_version	Reset a version to pending and re-run extraction with a new source set.	brandId, versionId; optional assetIds[], urls[]	async
activate_brand_dna_version	Make a version the active one (must be ready).	brandId, versionId	idempotent
cancel_brand_dna_version	Cancel an in-progress extraction.	brandId, versionId	idempotent
get_brand_dna	Fetch the active Brand DNA payload for a brand.	brandId	read-only
get_active_brand_dna	Fetch the active DNA version's detail.	brandId	read-only
get_brand_dna_version	Fetch a specific version's detail.	brandId, versionId	read-only
list_brand_dna_versions	List all DNA versions for a brand.	brandId	read-only
update_brand_dna_version	Rename and/or overwrite a version's canonical DNA payload (optimistic lock).	brandId, versionId, updatedAt; optional name, dna	write
patch_brand_dna_version	Apply a partial JSON Merge Patch to the DNA payload.	brandId, versionId, patch	idempotent
delete_brand_dna_version	Permanently delete a version. Not reversible.	brandId, versionId	destructive

The urls input on create_brand_dna_version and rerun_brand_dna_version accepts only public http/https addresses.

Assets

Uploads are a presign → client-PUT → confirm flow. The MCP transport never carries file bytes; your client uploads directly to the returned presigned URL.

Tool	Purpose	Key inputs	Hints
initiate_asset_upload	Reserve an upload and return presigned PUT URLs.	brandId, files[] (each: fileName, fileType, fileSize, dimension); optional categoryId	write
confirm_asset_upload	Confirm a completed upload and start processing.	uploadId; optional categoryId	write
cancel_asset_upload	Cancel an in-progress upload.	uploadId	idempotent
list_assets	List assets with optional filters.	optional brandId, type, status, tags[], campaignId	read-only
download_asset	Return a short-lived presigned download URL.	assetId	read-only

Allowed fileType values: image/jpeg, image/png, image/svg+xml, image/tiff, video/mp4, video/quicktime, application/pdf.

Generation

Tool	Purpose	Key inputs	Hints
scene_forge	Start a Scene Forge image generation.	brandId, blendingPrompt; optional promptIsEnhanced, useBrandDna, theme, aspectRatio, productAssetIds[], environmentAssetId, partner	async
enhance_scene_forge_prompt	Enhance a Scene Forge prompt.	brandId, originalPrompt; optional productAssetIds[], environmentAssetId, useBrandDna, partner	async
image_to_video	Start image-to-video generation.	brandId, startImageAssetId, userPrompts[], dimension; optional endImageAssetId, intermediateImageAssetIds[], model, duration, enableAudio, useBrandDna, promptIsEnhanced, partner	async
enhance_img2video_prompt	Enhance an image-to-video prompt.	brandId, startFrameAssetId, originalPrompt, aspectRatio; optional endFrameAssetId, intermediateFrameAssetIds[], model, duration, enableAudio, useBrandDna	async
get_scene_forge_prompt_enhancement	Fetch an enhancement's result (optimizedPrompt, theme) to review before generating. promptEnhancementId is the task id enhance_scene_forge_prompt returned.	brandId, promptEnhancementId	read-only
get_img2video_prompt_enhancement	Fetch an enhancement's result (enhancedPrompt) to review before generating. promptEnhancementId is the task id enhance_img2video_prompt returned.	brandId, promptEnhancementId	read-only
extend_scene_forge	Add more image variations to a completed Scene Forge, reusing its recipe (prefer over a fresh scene_forge for more of the same look).	sceneForgeId	async
extend_generated_videos_group	Add more video variations to a completed group, reusing its recipe.	groupId; optional variationCount	async
list_scene_forges	List Scene Forge generations for a brand.	brandId; optional status, partner, page, limit, sortBy, sortOrder	read-only
list_generated_video_groups	List image-to-video generation groups for a brand.	brandId; optional partner, page, limit, sortBy, sortOrder	read-only

Video model options: veo-3.1, veo-3.1-fast, kling-v3-pro, kling-v3-omni-pro, grok-imagine-video, seedance-1.5-pro, seedance-2.0-pro, pixverse-v6, optimized.

useBrandDna defaults differ by media: it is on by default for scene_forge and enhance_scene_forge_prompt, but off by default for image_to_video and enhance_img2video_prompt — pass useBrandDna: true to apply Brand DNA to video. Applying Brand DNA requires a plan that includes it.

Orientation, tasks and usage

Tool	Purpose	Key inputs	Hints
get_started	Orientation for a cold start: plan, subscription/lockout, whether Brand DNA is available, whether a brand exists, role, and a plain-language nextAction. Call it first.	none	read-only
get_task	Fetch an async task's status. Poll until terminal is true; succeeded marks a clean finish, and retryable (on failure) says whether resubmitting may help.	taskId; optional kind	read-only
list_recent_tasks	List recent async tasks to recover task ids lost after a disconnect (including enhancement ids, which have no other list tool). Each task_id is the id the matching get_*/list_* tool consumes.	optional kind, status, brandId, limit	read-only
get_feature_usage	Read your organization's consumption versus plan caps (image and video pools).	none	read-only

Working with async tools

The eight async tools (create_brand_dna_version, rerun_brand_dna_version, scene_forge, extend_scene_forge, enhance_scene_forge_prompt, image_to_video, extend_generated_videos_group, enhance_img2video_prompt) return a task id immediately. Poll get_task with that id until terminal is true (workflow status becomes completed, failed, or cancelled — note get_task reports completed, not the brand-DNA-version word ready), then read the finished resource with the tool the submit result named in resultTool. Suggested cadence: first poll ~5s after submit, then every 10-15s.

The finished resource per async tool: Brand DNA → get_brand_dna_version / get_active_brand_dna; prompt enhancements → get_scene_forge_prompt_enhancement / get_img2video_prompt_enhancement (this is where the enhanced prompt text lives — get_task does not carry it); generations → list_scene_forges / list_generated_video_groups, then download_asset.