# MCP tools

> Every tool the vvgen MCP server exposes, with parameters.

Generated from the server's own tool list. Endpoint: `https://api.vincevangen.com/mcp`. Model arguments take aliases, see [Models](https://vincevangen.com/docs/models.md).

## Generate

### vvgen_generate_image

Make a photo or picture from a prose prompt: people, products, scenes (icons, cards, charts: write code). model: fast (drafts, no refs) | standard (cheap stills of people, scenes, illustration; no refs, not for lettering or product labels) | default | best | text (lettering in the scene) | text-best (a scene full of signs that must all read) | premium | transparent; vvgen_list_models shows what each takes, and a request it cannot honour is refused before billing. A clear brief: one final on default. Options wanted or an open brief: n=4 on fast, then from_draft finishes the pick as an edit (dearer than one final; drafts pay off only against two or more finals). Example: {"prompt": "a ceramic coffee dripper on a walnut counter, soft window light from the right, product photo", "model": "default", "seed": 7}

- `prompt` (string)
- `from_draft` (string): A draft's id: that picture finished on `model`, as an edit. prompt: optional changes.
- `model` (string) (default "default")
- `aspect_ratio` (1:1 | 4:3 | 3:4 | 16:9 | 9:16 | 3:2 | 2:3 | 4:5 | 5:4 | 21:9): Sets a ~1 MP pixel size (16:9 = 1344x768); see vvgen_list_models. (default "1:1")
- `n` (integer): Variants (max 8), seeds seed..seed+n-1, one paid call each. (default 1)
- `seed` (integer)
- `style` (string): Style preset or saved style anchor (vvgen_list_presets).
- `reference_images` (list[string]): Asset ids, http(s) URLs or local paths (remote: vvgen_create_upload first).
- `transparent` (boolean): PNG with alpha: native only for model=transparent editing ONE reference with alpha, else a paid background removal runs after (a warning says so).
- `enhance` (boolean): Rewrite the prompt with a small LLM first (paid).
- `filename` (string)
- `width` (integer): With height: exact pixels, on pixel-size models; out of range is refused.
- `height` (integer)
- `negative_prompt` (string): Only for models with a negative field; dropped with a warning on FLUX/Gemini.
- `preview` (boolean) (default true)
- `post` (list[string]): Ops on each output, in order: trim | pad:<frac> | square | fit:WxH (shrink to fit inside, never enlarges) | contain:WxH (scale to fit inside) | cover:WxH (crop to exactly WxH) | resize:W[xH] | rmbg (paid background removal) | key:<hex>|auto[:tol] (colour to alpha; auto = the border colour; tol = max per-channel difference 0-255, default 24; models rarely paint the exact hex: use auto or rmbg; a key that removes nothing warns) | defringe[:px] | match_color:<hex>[:deg] | slice:CxR[:WxH] (cut a sprite sheet into equal frames + a GIF) | tileable (seamless texture wrap) | pixelate[:H][:colors] (fake pixel art to its own grid, 1x) | png | webp | jpeg.
- `checks` (list[string]): Free checks per variant: alpha_coverage:<min>-<max> | edge_halo:<max> | color_distance:<hex>:<max> | size:WxH | components:<n> | frames:<n> (sprite-sheet frame count) | seam:<max> (texture wrap, 1.0 = seamless) | palette:<n>. Failing variants are rejected (files kept).
- `judge` (list[string]): Yes/no statements for a vision model, e.g. "contains no readable text"; one paid call per variant that passed checks. Advisory: the checks and your own look at the preview decide.
- `keep` (all | all-passing | best-passing): best-passing (default for n>1 with checks/judge) | all-passing | all (annotate only). Rejects are listed under `rejected` with reasons.
- `text_overlay` (list[object]): Free exact text per kept result (layers as in vvgen_add_text); returns overlaid files, `parent` = clean base.
- `confirm_spend` (number): Only once the user approved a cost refusal: its amount.

### vvgen_edit_image

Edit a photo or compose from images with an instruction. images[0] is the canvas (size kept on pixel-size models), the rest are 'image 2', 'image 3'. Lead with the change, then 'keep everything else exactly the same'. Images: default/best 4, precise/text/text-best 1, fill 1 + mask. `parent` is null; sources are in `refs`. Output is often JPEG: post ["png"] for PNG. Example: {"prompt": "Put the bag from image 1 on a sunlit cafe table, keep the bag exactly the same", "images": ["a_3f9c2e"]}

- `prompt` (string, required)
- `images` (list[string], required): Asset ids, http(s) URLs or local paths (remote: vvgen_create_upload first).
- `model` (string) (default "default")
- `n` (integer) (default 1)
- `seed` (integer)
- `style` (string)
- `filename` (string)
- `preview` (boolean) (default true)
- `post` (list[string]): As in generate_image.
- `checks` (list[string]): As in generate_image.
- `judge` (list[string]): As in generate_image.
- `keep` (all | all-passing | best-passing): As in generate_image.
- `text_overlay` (list[object]): As in generate_image.
- `confirm_spend` (number): As in generate_image.
- `mask` (string): fill: white = repaint

### vvgen_generate_asset

Make a typed asset from a preset: avatar, product-shot, hero, sticker, blog-header ... (app-icon, favicon, logo-concept, sprite-sheet: concepts to redraw in code). The preset brings template, model, aspect, style, post ops, exports and checks/judge. One variant on the preset's model is the normal call; n>1 on model=fast explores and keeps the best passing. vvgen_list_presets with name=<preset> shows all of it before you pay. Example: {"preset": "hero", "subject": "pour-over coffee on a counter at dawn, plain wall on the left", "text_overlay": [{"text": "Brewlog", "position": "left"}]}

- `preset` (string, required)
- `subject` (string, required)
- `style` (string)
- `model` (string)
- `n` (integer) (default 1)
- `seed` (integer)
- `reference_images` (list[string]): As in generate_image.
- `enhance` (boolean)
- `filename` (string)
- `preview` (boolean) (default true)
- `checks` (list[string]): As in generate_image.
- `judge` (list[string]): As in generate_image.
- `keep` (all | all-passing | best-passing): As in generate_image.
- `text_overlay` (list[object]): As in generate_image.
- `confirm_spend` (number): As in generate_image.
- `lighting` (string): hero, product-shot, avatar: replaces the preset's lighting, e.g. "from the right".
- `params` (object): The preset's slots (vvgen_list_presets: slots), e.g. sprite-sheet {"frames": 4, "action": "a hop"}.

### vvgen_generate_video

Make a short video clip, as a job (wait_seconds, or poll vvgen_get_job). Text-to-video, or image-to-video with `image` (aspect from the image). Durations, resolutions and aspects per alias: vvgen_list_models; others are refused before billing. Billed per second. One action and one camera move; state the camera. Example: {"prompt": "slow push-in on steam rising from a coffee cup, morning light", "model": "fast", "wait_seconds": 120}

- `prompt` (string, required)
- `model` (string) (default "default")
- `image` (string)
- `duration` (integer) (default 5)
- `resolution` (string) (default "720p")
- `aspect_ratio` (string)
- `seed` (integer)
- `enhance` (boolean)
- `filename` (string)
- `wait_seconds` (integer) (default 0)
- `confirm_spend` (number): As in generate_image.

### vvgen_generate_music

Make a music track or soundtrack (30-500 s, billed per second) as a job, ~1 s per output second: wait_seconds = duration + 20 returns it in one call, else poll vvgen_get_job. prompt: genre, mood, instruments, vocals, tempo, key as tags. lyrics: [verse]/[chorus] (empty: the model writes them); instrumental=true for none. cover|cover-nofsq|repaint need input_audio; reference_audio borrows a clip's sound. For a loop pass loop=true (prompt words alone do not loop). Thin or harsh: same call and seed with post ["polish"] (free). Example: {"prompt": "lo-fi hip hop, warm Rhodes, 80 bpm", "instrumental": true, "duration": 30, "loop": true, "wait_seconds": 50}

- `prompt` (string, required)
- `lyrics` (string)
- `instrumental` (boolean)
- `duration` (integer) (default 60)
- `bpm` (integer)
- `seed` (integer)
- `n` (integer) (default 1)
- `format` (mp3 | flac | wav) (default "mp3")
- `task` (text2music | cover | cover-nofsq | repaint) (default "text2music")
- `input_audio` (string)
- `reference_audio` (string)
- `negative_prompt` (string)
- `repaint_start` (number)
- `repaint_end` (number)
- `think` (boolean)
- `language` (string)
- `filename` (string)
- `post` (list[string]): ["polish"]: free fix for thin, muddy, harsh or phasey sound; polish:<mix> sets strength 0-1 (default 0.15).
- `loop` (boolean): Free seamless loop: whole bars (set bpm for exact bars), crossfaded wrap, -1 dBTP. The track gets shorter; .loop.wav/.loop.ogg exports sit beside an mp3 (mp3 leaves a gap when looped).
- `wait_seconds` (integer) (default 40)
- `confirm_spend` (number): As in generate_image.

### vvgen_get_job

Status or result of a video/music job, or an upload_id; wait_seconds blocks up to that long (max 600). Example: {"job_id": "j_8d2a", "wait_seconds": 60}

- `job_id` (string, required)
- `wait_seconds` (integer) (default 0)

## Post-process and check

### vvgen_remove_background

Remove the background of an existing image (Bria, paid), trim to content, save a PNG with alpha. For new art, transparent=true on generate does this for you. Example: {"image": "a_3f9c2e"}

- `image` (string, required)
- `filename` (string)
- `preview` (boolean) (default true)
- `confirm_spend` (number): As in generate_image.

### vvgen_add_text

Draw exact text onto an existing image with bundled fonts, saved as a new image (free, instant): titles, labels, buttons, banners, social cards. The source is kept (the result's `parent`): re-word or translate by calling again. One layer per text block. Example: {"image": "a_3f9c2e", "layers": [{"text": "Brewlog", "font": "display", "position": "top"}, {"text": "Your coffee, dialed in.", "size": 40}]}

- `image` (string, required)
- `layers` (list[object], required)
- `filename` (string)
- `preview` (boolean) (default true)

### vvgen_judge_image

Ask a vision model yes/no checks about an image: per-check answers, located defects, pass, status (inconclusive = an item unanswered). Advisory: run vvgen_check_image first and look yourself. reference_images compare identity/style. Example: {"image": "a_3f9c2e", "checks": ["exactly one person", "contains no readable text"]}

- `image` (string, required)
- `checks` (list[string], required)
- `reference_images` (list[string]): As in generate_image.
- `context` (string)
- `strict` (boolean)

### vvgen_check_image

Check an image for free (no model call): size, cutout edges, brand colour ... the `checks` of vvgen_generate_image, with pass, measured value and detail per check. Example: {"image": "a_3f9c2e", "checks": ["size:1200x630", "color_distance:#2b1d14:40"]}

- `image` (string, required)
- `checks` (list[string], required)

### vvgen_enhance_prompt

Rewrite a short brief into a full prompt following the target model family's rules (one small paid LLM call). kind: t2i | edit | video. Returns JSON {prompt, aspect_ratio, ...}. Example: {"brief": "hero image for a coffee app", "kind": "t2i", "model": "best"}

- `brief` (string, required)
- `kind` (string) (default "t2i")
- `model` (string) (default "default")
- `style` (string)
- `asset_type` (string)

## Discover and style

### vvgen_list_models

List the model aliases per kind with live price, output licence (commercial use: yes | no | unclear) and what each takes: references, pixel sizes or aspect only, alpha route, video start image and durations; plus the pixel size each aspect_ratio gives. Example: {"kind": "image"}

- `kind` (image | edit | video | music | utility)

### vvgen_list_presets

List style presets, this project's style anchors and asset presets. name=<preset> shows one recipe before you pay: prompt template, model, aspect and pixels, style text, transparent, post ops, size exports, default checks and judge rubric. Example: {"name": "product-shot"}

- `name` (string)

### vvgen_create_style

Save a style anchor for a consistent series: name + prompt + ordered reference images (this project's ids), as a fixed version (island-v1; new content makes island-v2). Pass style="island" (latest) or "island-v1" on generate/edit/asset: its refs go first and count against the model's slots. Example: {"name": "island", "asset_ids": ["a_3f9c2e"], "prompt": "in the gouache style of the reference images"}

- `name` (string, required)
- `asset_ids` (list[string]): At most 8; a local server also takes file paths.
- `prompt` (string)
- `avoid` (string)
- `suffix` (string)
- `note` (string)

## Files and history

### vvgen_import

Bring in an image vvgen did not make (a designer's, another tool's): free, no model call. Records size, alpha and provenance (origin: import + your claim; licence unknown), then optional post, checks, exports, text_overlay; the source is not changed. Example: {"image": "a_3f9c2e", "claimed": "Codex image tool", "exports": ["64", "128", "256"]}

- `image` (string, required): Asset ids, http(s) URLs or local paths (remote: vvgen_create_upload first).
- `claimed` (string): Its source, recorded as said.
- `exports` (list[string]): 256 | WxH[:contain|fit] (cover) | scale:k
- `post` (list[string]): As in generate_image.
- `checks` (list[string]): As in generate_image.
- `text_overlay` (list[object]): As in generate_image.
- `filename` (string)
- `confirm_spend` (number): As in generate_image.

### vvgen_history

Recent assets (id, path, model, seed, prompt, cost). Example: {"limit": 5, "search": "coffee"}

- `limit` (integer) (default 10)
- `search` (string)

### vvgen_get_file

One result as an image you can see, by asset id (a_...) or path, longest side at most max_px (cap 2048); png keeps alpha, jpeg is smaller. Use it to hand a person the full image in chat (no download). Also id, path, size, provenance. Audio: an embedded resource; video: metadata only. file: a name from the asset's exports/frames/gif. Example: {"asset_id": "a_3f9c2e", "max_px": 1024}

- `asset_id` (string, required)
- `max_px` (integer) (default 1024)
- `format` (png | jpeg) (default "png")
- `file` (string)

### vvgen_create_upload

Gets a local file or a person's photo (image or audio, 25 MB) onto this server. A file you can read, including one attached in a chat (it sits in your sandbox): run the returned curl on it. No shell, or curl cannot reach us (sandbox without network access): give the person page_url to pick the file in a browser; vvgen_get_job on the upload_id waits for its asset id. Example: {"filename": "logo.png"}

- `filename` (string)