# Driving Homotope from an AI agent

> An agent connected to Homotope’s MCP server (https://homotope.app/mcp) turns an image into a print-ready or cut-ready file in at most 3 jobs: suggest the preset, compute, look at the preview and run the cut check, then correct with the advice the check returns, and stop when the check passes and the zoomed preview no longer shows the defect the user named.

## Who this is for

This page is the playbook for an AI agent (Claude Code, Claude, ChatGPT, Gemini CLI, or a script) that uses Homotope through its MCP server at `https://homotope.app/mcp`. The raw text is at [/en/agents.md](https://homotope.app/en/agents.md). Every `vectorize_image` call is a job counted against the user’s account; every other tool is free. So look before you compute again.

## The loop in four steps

1. **Suggest.** Call `suggest_preset` with the image (`image_base64`, `image_url` or `source_job_id`). It is free and computes nothing. Or pass `"preset":"auto"` to `vectorize_image`.
2. **Compute.** Call `vectorize_image` with that preset. For a sticker, a window sticker or a die-cut print, add `cut_contour` with the real `width_mm` (its margins are in mm at that size). It answers at once with a `job_id`: poll `get_job` until `done` (or `failed`). This is the only step that counts.
3. **See and check.** Call `get_preview` (`"side":"both"` compares with the original; `zoom` frames a box of the cut check or the part the user complained about), then `check_cut` with the real `width_mm` (and the printer’s `safety_mm` and `spacing_mm` if they gave them). Read `report.blocking`, `printer.status` and `advice`.
4. **Correct with the advice.** Take the first `advice` entry and compute again from the same source (`source_job_id`: no new upload), then go back to step 3. How to apply each kind of advice is below.

## Applying an advice entry

- `setting` is an engine setting (`tolerance`, `smoothing`, `noise`, `colors`…): pass it in `options` with its `value` (or one step in its `direction`), with the concrete preset (`preset_suggested.preset` from `get_job` if you used `"auto"`, which takes no options).
- `setting` is `contour`: a number is the new `cut_contour.margin_mm`, a word is the new `cut_contour.mode`.
- `setting` is `width_mm`: the scale is unknown. Ask the user for the real width and call `check_cut` again: no new job is needed.
- `setting` is `none`: nothing in Homotope fixes it (the source, the layout or the printer’s file must change). Tell the user the `why` text and stop computing.

## When to stop

- Stop when `check_cut` passes (`report.blocking` is 0 and `printer.status` is `ok`; `warn` only if the user accepts it) AND the zoomed `get_preview` no longer shows the defect the user named.
- At most 3 jobs per image. After the last one, show the best result and the remaining advice instead of computing again.
- Stop at once on an advice with `none`, on a 402, or on a 429 `too_many_variants`.

## Limits

- Each `vectorize_image` is one job: one of the free plan’s 2 trial jobs of the month (the same as in the web app), then the Pro quota (100 jobs a month), then one credit. A failed job is refunded.
- 402 `payment_required`: the account has no right left. The error carries `purchaseUrl`: give it to the user, do not retry, never quote a price (prices are on the Pricing page).
- 429 `too_many_variants`: more than 8 jobs of the same image in a rolling hour. `retryAfterSeconds` says when; meanwhile, look (`get_preview`, `check_cut`) rather than compute.
- 429 `rate_limited` (`suggest_preset` 30 a minute per API key or connection, `get_preview` 30 a minute per account) or `too_many_jobs` (queue full): wait `retryAfterSeconds`.
- The source image is kept 7 days. After that, `source_job_id`, the `source` side of `get_preview` and `suggest_preset` by job answer 410 `source_expired`: ask the user for the image again.
- `get_preview`: `width` up to 1024 px, 1 Mpx at most; `zoom` is in image pixels, the frame of the `check_cut` boxes.

## What each tool costs the account

- `vectorize_image`: one job (trial, Pro quota or credit).
- `suggest_preset`, `get_preview`, `check_cut` and its `advice`, `read_printer_template`: free, nothing written.
- `get_job`, `get_svg`, `get_result`, `list_vectorizations`: free; the formats of a finished job come with the job.

## Production files and the printer check

- `get_result` with `"format":"pdf"`, the real `width_mm` (a 1:1 file, what printers ask for) and `bleed_mm` (often 2 mm). A job submitted with `cut_contour` carries a CutContour spot-colour layer; `white_underprint` and `finish_layers` add the printer’s white and finishing layers.
- DXF for a cutter: `"format":"dxf"` (one layer per colour), `cut_only` for the CutContour alone; `layers` gives colour separations.
- The printer sent a template PDF? `read_printer_template` (`pdf_url` or base64, free, nothing kept) returns its trim size, bleed and safety zone: copy them into `get_result` as `page_width_mm`, `page_height_mm`, `bleed_mm` and `safe_mm` (`same_pages` 2: front and back, `verso_job_id`). The user drew their own cut line? Pass it to `vectorize_image` as `cut_contour_image_url` (or base64) instead of `cut_contour`. `get_preview` takes `white_underprint` and `finish_layers` to show those layers on the result.
- The printer part of `check_cut` needs `width_mm`: shapes within `safety_mm` of the cut line (default 3 mm), stickers closer than `spacing_mm` (default 4 mm), strokes under 0.25 pt, a single closed CutContour in `single` mode. Without `width_mm` these checks are “unavailable”, never passed.

## Example: a 140 × 40 cm window sticker

The user wants a window sticker 1,400 mm wide with a cut contour and 2 mm bleed. Two jobs here; a third only if the second check still fails.

```
suggest_preset    {"image_url":"https://…/vitrine.png"}
vectorize_image   {"image_url":"https://…/vitrine.png","preset":"auto",
                   "cut_contour":{"width_mm":1400}}
get_job           {"job_id":"<id>"}            (until "done")
get_preview       {"job_id":"<id>","side":"both","width":1024}
check_cut         {"job_id":"<id>","width_mm":1400}
vectorize_image   {"source_job_id":"<id>","preset":"<preset_suggested.preset>",
                   "cut_contour":{"width_mm":1400,"margin_mm":<advice value>}}
check_cut         {"job_id":"<id2>","width_mm":1400}
get_result        {"job_id":"<id2>","format":"pdf","width_mm":1400,"bleed_mm":2}
```

## Connecting

Claude Code: add the server, then sign in from `/mcp` (OAuth, the user’s Homotope account). A script uses an API key in the `Authorization: Bearer` header; never write a key into a prompt, a file or a repository.

```
claude mcp add --transport http homotope https://homotope.app/mcp
```