Clips for a whole catalogue

Goal

Make one short clip per product from a spreadsheet of the catalogue.

Before you start

• A token in execute mode for the whole workspace.
• The import template filled in with one product per row, with photo URLs the seller has the rights to use.

MCP calls, in order

Values in angle brackets are placeholders. Every write gets its own new request_key (a UUIDv4); reuse a key only to retry the identical call.

1. get_workspace

   Read the workspace id and your role.

   {}

2. get_import_template

   Get the spreadsheet template: its columns and a blank .xlsx file.

   {
     "workspace_id": "<workspace_id from get_workspace>"
   }

3. preview_import

   Read the filled sheet (up to 4 MB and 100 rows) into rows. Nothing is created yet.

   {
     "workspace_id": "<workspace_id from get_workspace>",
     "xlsx_base64": "<filled template as base64>"
   }

4. import_project_rowOnly after the person says yes

   For one row: create its project and download its public photo URLs. rights_confirmed: true records the person’s statement that they may use the text and photos.

   {
     "workspace_id": "<workspace_id from get_workspace>",
     "fields": {
       "...": "<fields of one row as returned by preview_import>"
     },
     "image_urls": [
       "<product photo URL>"
     ],
     "rights_confirmed": true,
     "request_key": "<stored key of this row>"
   }

5. agent_preflight

   On the row’s project: check for blockers and read next_calls.

   {
     "project_id": "<project_id of this row>"
   }

6. read_external_context

   Read the row’s project context.

   {
     "project_id": "<project_id of this row>"
   }

7. submit_external_composition

   Submit the storyboard for this product with its photo.

   {
     "project_id": "<project_id of this row>",
     "expected_project_revision": "<project revision from the context>",
     "expected_composition_revision": "<composition revision from the context>",
     "context_handle": "<context_handle>",
     "context_hash": "<context_hash>",
     "composition": {
       "shots": [
         {
           "reference_asset_ids": [
             "<asset_id of the row photo>"
           ],
           "...": "<fields from the schema in the context>"
         }
       ]
     },
     "client_task_id": "<row number>",
     "request_key": "<new UUIDv4>"
   }

8. create_quote

   Quote this row. Collect the quotes of all rows, then show the person the whole list.

   {
     "project_id": "<project_id of this row>",
     "composition_id": "<composition_id>",
     "candidates": 1,
     "request_key": "<new UUIDv4>"
   }

9. approve_productionOnly after the person says yes

   Only for the rows the person accepted.

   {
     "project_id": "<project_id of this row>",
     "quote_id": "<quote_id>",
     "expected_content_hash": "<content_hash from the quote>",
     "request_key": "<new UUIDv4>"
   }

10. list_available_media

    When the row’s run is READY, read its verified clip.

    {
      "project_id": "<project_id of this row>",
      "run_id": "<run_id from approve_production>"
    }

11. prepare_delivery

    Prepare the row’s delivery package.

    {
      "project_id": "<project_id of this row>",
      "run_id": "<run_id from approve_production>",
      "request_key": "<new UUIDv4>"
    }

12. issue_deliveryOnly after the person says yes

    Only after the person has checked the clips.

    {
      "project_id": "<project_id of this row>",
      "run_id": "<run_id from approve_production>",
      "confirmed": true,
      "request_key": "<new UUIDv4>"
    }

What the person approves

• The rights to the text and photos, before the first import_project_row.
• The list of quotes, row by row, before any approve_production.
• The clips, before issue_delivery.

Expected output

• One project and one clip per product row.
• A table the agent keeps and shows: row, project, quote, run and delivery.

Good to know

• There is no tool that produces many full videos in one call. The agent repeats the calls from import_project_row to issue_delivery once per row, one project per product. For many short clips from one table, with no storyboard per product, use a clip batch instead. A delivery batch (create_delivery_batch) only bundles finished videos for download.
• Store one request_key per row and per call. After a timeout, retry with the stored key, so a row is never created or produced twice.
• After WRITE_OUTCOME_UNKNOWN, read the row’s project first; never create it again.