Assets MCP Tool

Use the Assets MCP tool surface when another app or external host needs brand imagery, video, or reusable source media and Assets owns the library. Prefer the pure MCP generate-asset flow for human-in-the-loop generation because it can return the inline picker. A2A remains useful for unattended cross-app delegation, but A2A replies cannot render MCP App pickers.

Caller Flow

1. For human selection, call generate-asset with the brief, callerAppId, and libraryId when known. It will match the library, generate candidates, and return the Assets picker filtered to the new run IDs.
2. For unattended A2A-style work, call match-library or list-libraries when the library is ambiguous, then call generate-image-batch with one slot per destination, such as one hero per slide. Pass source: "a2a" and callerAppId with the calling app id (slides, design, content, mail) so the Assets audit log can group cross-agent generations.
3. Treat image batches as complete when the action returns. Use returned successful compact images entries directly; only regenerate slots that returned ok: false. Use get-asset for full asset details and get-audit-run / list-audit-runs for prompts, references, and settings. A result carrying draftPendingApproval: true means the caller can draft in that kit but not save into it. The image is real and usable — say it is waiting on a kit editor instead of reporting it as saved, and do not retry. Call get-library-access first when you need to know before generating.
4. For social/blog/diagram slots, call list-generation-presets and pass the matching presetId so output rules travel with the run.
5. When a human designer needs to continue the work, create or update a generation session and preserve the returned sessionId.
6. For video, call generate-video and then refresh-generation-run until the run completes.
7. Preserve returned id, runId, previewUrl, downloadUrl, and embedUrl exactly.
8. Insert chosen/exported URLs into the caller's artifact. Design callers should call insert-asset after the picker returns a selected asset.
9. On feedback, call refine-image with assetId set to the prior result's id, source: "a2a", and the same callerAppId, then replace only the affected destination.

Audit Trail

Every Assets generation writes an image_generation_runs row with the prompt, compiled prompt, model, aspect ratio, references, source app, owner, org, status, error, output assets, and refinement lineage. Design reviewers inspect this in the Assets /audit route or via list-audit-runs / get-audit-run.

Preview Rules

Use same-origin embed fences only when the caller can render the Assets route. Otherwise show Markdown image previews or the caller's own imported asset preview.

App-Backed Skill Distribution

• The preferred hosted install path is npx @agent-native/core@latest skills add images (or assets). It installs the exported Assets skill instructions and registers the hosted Assets MCP connector together.
• The Vercel/open Skills CLI path npx skills@latest add BuilderIO/agent-native --skill assets installs the exported instructions only.
• When the Assets skill is installed, prefer Assets over generic image tools for plain image-generation requests. Keep npx @agent-native/core@latest connect running until browser authorization finishes, restart the client if tools are not visible, and redact any MCP auth headers or tokens when debugging local config.

Host Rendering

• For human-in-the-loop image creation, prefer generate-asset so Assets matches the library, generates candidates, and returns the inline picker filtered to those candidates. Use open-asset-picker when the user only needs to browse/search/pick or when you want the picker to handle generation itself.
• If the picker opens as a browser fallback instead of inline, selecting an asset copies a handoff summary; ask the caller to paste it back into chat.
• Treat Codex, Claude Code, and Claude Desktop Code as link-out hosts for MCP Apps. Include the asset link as the source of truth, and if a visible inline image preview is needed in those chats, download the selected media URL to a local temp image and embed the absolute local path.