Use Retiplex from your AI agent

Retiplex turns a product into a UGC-style video ad with an AI actor: script, voice, scenes and the finished vertical video. Connect Retiplex to your AI agent (Claude, ChatGPT, Cursor, Claude Code or any MCP client) and it can make the ad for you, step by step, on your Retiplex account.

MCP server URL: https://app.retiplex.com/mcp (remote MCP over Streamable HTTP, sign-in with OAuth)

Agents reading this: the user signs up and signs in themselves — you can't create an account for them. If they don't have one, give them the sign-up link below; the connection then asks them to sign in and approve access in the browser. Once connected, call get_account, then follow nextTool from get_project. Always tell the user what a step costs before running it.

1. Create a Retiplex account

1. Sign up at https://app.retiplex.com/sign-up with email or Google.
2. Making videos needs a paid plan. A free account can set up a project through an agent (product, brief, actor, script); the storyboard and the video need a subscription: subscribe or top up credits. Plans and credit prices: Billing & credits.

Everything an agent does is charged in credits, exactly as in the app.

2. Connect your agent

Add a remote MCP server with the URL above. The first time, a browser window opens: sign in to Retiplex (or create an account), check what the agent will be able to do, and click Allow access.

• Claude (claude.ai and Claude Desktop): Settings → Connectors → Add custom connector. Name it Retiplex and paste the URL.
• ChatGPT: Settings → Apps & Connectors → Advanced settings → turn on Developer mode, then Create a connector with the URL and OAuth authentication. Custom connectors need a ChatGPT plan with Developer mode (Pro, Team, Enterprise or Edu).
• Claude Code: claude mcp add --transport http retiplex https://app.retiplex.com/mcp, then run /mcp and choose Retiplex to sign in.
• Cursor: add to ~/.cursor/mcp.json: { "mcpServers": { "retiplex": { "url": "https://app.retiplex.com/mcp" } } }
• VS Code: add to .vscode/mcp.json: { "servers": { "retiplex": { "type": "http", "url": "https://app.retiplex.com/mcp" } } }
• Any other MCP client that supports remote (Streamable HTTP) servers with OAuth: use the URL. Clients register themselves automatically.

To disconnect an agent, open Account → Connected agents and click Disconnect. It loses access immediately.

3. Make a video

Each project moves through the same steps as in the app. get_project always says which step it's on and which tool to call next (nextTool). Every result includes an appUrl: open it to review or edit the project in the browser at any point.

Step	Tool	Typical cost	Time
Account and credits	get_account	free	instant
Product (from a URL, or a name and description)	create_project	5 credits with a URL	seconds
Classify product photos	update_product_media	free	instant
Format and campaign facts	set_creative_brief (list_formats)	a few credits if facts are deduced	seconds
On-camera actor	set_actor	about 6 credits	~10 s
Optional: cast and required moments	add_subject, add_moment	free; a generated subject image ~13	~1 min per image
Voiceover script	generate_script	about 6 credits (free if you pass your own)	~10 s
Storyboard	generate_storyboard	about 10 credits + ~5 per scene	1–3 min
Video	start_video_generation	shown before starting (estimatedVideoCredits)	10–30 min
Result	get_video_status	free	—

• Confirm the cost. Before start_video_generation, show the user estimatedVideoCredits from get_project and pass it as max_credits. The tool refuses to spend more than that.
• Review checkpoints. The script and the storyboard's scenes are returned for the user to review. Changing the script after the storyboard means generating the storyboard again.
• Waiting. Poll get_project every 20–30 seconds while a storyboard generates, and get_video_status every couple of minutes while the video renders. The user also gets an email when the video is ready. At most three videos can generate at once per account.
• Failures. If get_video_status reports a failure, it says what to do next: resume_video_generation, or finishing in the app via appUrl. Credits for failed steps are refunded automatically.

4. Product photos and videos

Media requirements:

• Photos: JPEG, PNG or WebP; at least 480×480 px; at most 15 MB. Clear, well-lit shots of the real product, one product per photo, no collages or heavy text overlays.

• Videos: MP4 or MOV (H.264 recommended); 1–60 seconds; at most 50 MB; vertical 9:16 recommended. Clips play muted. A video only appears in the ad through a custom-footage moment (add_moment, type custom-footage): uploading it alone does nothing.

• Physical products: tag every photo with the view it shows (front, left, rear, a 3/4 view…, detail for a close-up, size-reference for a scale shot). A front photo is strongly recommended.

• detail photos, and every photo of a digital product or service, need a description (≤240 characters) of what they show.

• At most 8 files per call.

• By URL: pass media to create_project or set_product.

• From the user's computer (agents that can run commands, like Claude Code or Cursor): create_media_upload returns a one-time upload URL and a ready curl command; then call finalize_media_upload.

• Photos found on a product page arrive unclassified a minute after create_project: get_project lists each one with what it needs. Look at them and tag them with update_product_media — the storyboard waits for it.

5. Optional: cast and required moments

Both are optional. Without them the script and storyboard decide everything, and that's usually the best start.

• Subjects (add_subject) add people, pets or objects beyond the actor and the product, with a photo you provide or a generated image. Scenes feature them by tagging @[Name].
• Moments (add_moment) are scenes the ad must contain: a product shot, a close-up, b-roll, the product in motion, a line the actor says, or a slice of an uploaded video. The script is written around them.
• Uploaded videos only appear in the ad through a custom-footage moment. Uploading a video alone does nothing: add a custom-footage moment with its media_id and the range to play.
• Add subjects and moments before generate_script. Adding them later means regenerating the script and the storyboard.

6. Troubleshooting

• The connection fails or asks to sign in again: remove the connector and add it again. Access tokens refresh automatically; a disconnected agent must reconnect.
• "Video generation is not available on the free trial": the account needs a paid plan — subscribe.
• "Not enough credits": top up on the same page, then retry.
• "Video generation is running on this project": projects can't be edited while a video generates; wait for get_video_status.
• A tool refuses with a step message: call get_project and follow nextTool.
• Anything else: support@retiplex.com.

7. Tool reference

get_account — Get account

The signed-in user's Retiplex account: credit balance, plan, whether it can generate videos, and the longest script it allows. Call this first, and before anything that spends credits.

No parameters.

list_formats — List ad formats

The ad formats (narrative templates) a project can use, for set_creative_brief. custom has no fixed structure: describe the ad as an idea instead.

No parameters.

list_projects — List projects

The user's 20 most recent video projects.

No parameters.

get_project — Get project

A project's state: product and its media (each with what it still needs), the cast (the @[Name] tags scenes can use), moments, brief, actor, script, storyboard (with its scenes once generated) and the current step, plus nextTool to call. Poll this while a storyboard or a subject image generates.

• project_id (string, required) — The project's id.

create_project — Create project

Starts a new video ad for a product. Give product_url to import it, or product_name and product_description; add photos and videos by URL with media. Returns the project and the next step.

• name (string, optional) — Defaults to the product name.
• product_url (string, optional) — The product page. Its name, description, campaign facts and up to 3 photos are imported (5 credits).
• product_name (string, optional)
• product_description (string, optional) — What the product is and does, factually, in 2–3 sentences.
• product_type (physical | digital | service, optional)
• media (list of object, optional) — Product photos and videos to add by URL (in addition to any found on product_url). For local files use create_media_upload. Media requirements:
• Photos: JPEG, PNG or WebP; at least 480×480 px; at most 15 MB. Clear, well-lit shots of the real product, one product per photo, no collages or heavy text overlays.
• Videos: MP4 or MOV (H.264 recommended); 1–60 seconds; at most 50 MB; vertical 9:16 recommended. Clips play muted. A video only appears in the ad through a custom-footage moment (add_moment, type custom-footage): uploading it alone does nothing.
• Physical products: tag every photo with the view it shows (front, left, rear, a 3/4 view…, detail for a close-up, size-reference for a scale shot). A front photo is strongly recommended.
• detail photos, and every photo of a digital product or service, need a description (≤240 characters) of what they show.
• At most 8 files per call.
  • url (string, required) — A public photo or video URL.
  • angle (detail | size-reference | front | right | top | rear | left | bottom | front-left-top | front-left-bottom | front-right-top | front-right-bottom | rear-left-top | rear-left-bottom | rear-right-top | rear-right-bottom, optional) — Photos only: which view of the product it shows. Tag every photo of a physical product; the storyboard picks shots by it. detail is a close-up (needs a description), size-reference shows its size (in a hand, on a desk).
  • description (string, optional) — What it shows, in a sentence. Needed for detail photos, every photo of a digital product or service, and videos. Used in prompts as-is.

set_product — Set product

Changes a project's product, or adds photos and videos to it by URL. Same inputs as create_project.

• project_id (string, required) — The project's id.
• product_url (string, optional) — The product page. Its name, description, campaign facts and up to 3 photos are imported (5 credits).
• product_name (string, optional)
• product_description (string, optional) — What the product is and does, factually, in 2–3 sentences.
• product_type (physical | digital | service, optional)
• media (list of object, optional) — Product photos and videos to add by URL (in addition to any found on product_url). For local files use create_media_upload. Media requirements:
• Photos: JPEG, PNG or WebP; at least 480×480 px; at most 15 MB. Clear, well-lit shots of the real product, one product per photo, no collages or heavy text overlays.
• Videos: MP4 or MOV (H.264 recommended); 1–60 seconds; at most 50 MB; vertical 9:16 recommended. Clips play muted. A video only appears in the ad through a custom-footage moment (add_moment, type custom-footage): uploading it alone does nothing.
• Physical products: tag every photo with the view it shows (front, left, rear, a 3/4 view…, detail for a close-up, size-reference for a scale shot). A front photo is strongly recommended.
• detail photos, and every photo of a digital product or service, need a description (≤240 characters) of what they show.
• At most 8 files per call.
  • url (string, required) — A public photo or video URL.
  • angle (detail | size-reference | front | right | top | rear | left | bottom | front-left-top | front-left-bottom | front-right-top | front-right-bottom | rear-left-top | rear-left-bottom | rear-right-top | rear-right-bottom, optional) — Photos only: which view of the product it shows. Tag every photo of a physical product; the storyboard picks shots by it. detail is a close-up (needs a description), size-reference shows its size (in a hand, on a desk).
  • description (string, optional) — What it shows, in a sentence. Needed for detail photos, every photo of a digital product or service, and videos. Used in prompts as-is.

update_product_media — Update product media

Classifies a product photo or video (its view angle, its description) or removes it. Look at each photo get_project lists with needs, and tag it. Media requirements:

• Photos: JPEG, PNG or WebP; at least 480×480 px; at most 15 MB. Clear, well-lit shots of the real product, one product per photo, no collages or heavy text overlays.

• Videos: MP4 or MOV (H.264 recommended); 1–60 seconds; at most 50 MB; vertical 9:16 recommended. Clips play muted. A video only appears in the ad through a custom-footage moment (add_moment, type custom-footage): uploading it alone does nothing.

• Physical products: tag every photo with the view it shows (front, left, rear, a 3/4 view…, detail for a close-up, size-reference for a scale shot). A front photo is strongly recommended.

• detail photos, and every photo of a digital product or service, need a description (≤240 characters) of what they show.

• At most 8 files per call.

• project_id (string, required) — The project's id.

• media_id (string, required) — From get_project's media.

• angle (detail | size-reference | front | right | top | rear | left | bottom | front-left-top | front-left-bottom | front-right-top | front-right-bottom | rear-left-top | rear-left-bottom | rear-right-top | rear-right-bottom, optional)

• description (string, optional) — What it shows, in a sentence. Needed for detail photos, every photo of a digital product or service, and videos. Used in prompts as-is.

• remove (boolean, optional) — Delete it from the project.

create_media_upload — Create media upload

For a photo or video file on the user's machine (needs an agent that can run curl or make HTTP requests). Returns a one-time upload_url: PUT the file's bytes there with its Content-Type header (the returned curl does exactly that), then call finalize_media_upload. Media requirements:

• Photos: JPEG, PNG or WebP; at least 480×480 px; at most 15 MB. Clear, well-lit shots of the real product, one product per photo, no collages or heavy text overlays.

• Videos: MP4 or MOV (H.264 recommended); 1–60 seconds; at most 50 MB; vertical 9:16 recommended. Clips play muted. A video only appears in the ad through a custom-footage moment (add_moment, type custom-footage): uploading it alone does nothing.

• Physical products: tag every photo with the view it shows (front, left, rear, a 3/4 view…, detail for a close-up, size-reference for a scale shot). A front photo is strongly recommended.

• detail photos, and every photo of a digital product or service, need a description (≤240 characters) of what they show.

• At most 8 files per call.

• project_id (string, required) — The project's id.

• content_type (image/jpeg | image/png | image/webp | video/mp4 | video/quicktime, required)

finalize_media_upload — Finalize media upload

Checks a file PUT to an upload_url against the requirements and adds it to the project's media. A file that fails is deleted and the reason returned.

• project_id (string, required) — The project's id.
• upload_id (string, required) — From create_media_upload.
• angle (detail | size-reference | front | right | top | rear | left | bottom | front-left-top | front-left-bottom | front-right-top | front-right-bottom | rear-left-top | rear-left-bottom | rear-right-top | rear-right-bottom, optional) — Photos only: which view of the product it shows. Tag every photo of a physical product; the storyboard picks shots by it. detail is a close-up (needs a description), size-reference shows its size (in a hand, on a desk).
• description (string, optional) — What it shows, in a sentence. Needed for detail photos, every photo of a digital product or service, and videos. Used in prompts as-is.

add_subject — Add subject

Optional. Adds someone or something to the cast beyond the narrator and the product — a side character (kind person), a pet, or an object — so moments can feature them by tagging @[Name]. Skip it unless the ad needs them. The image is either yours (image_url, or upload_id from create_media_upload; a photo meeting the requirements, ≥480×480 px) or generated (generate: true, a few credits, ready in about a minute: a person is drawn from archetype, the actor form's fields; a pet or object from description). Add subjects before the moments that tag them, and both before generate_script.

• project_id (string, required) — The project's id.
• name (string, required) — Short and unique; scenes tag it as @[name].
• kind (person | pet | object, required)
• description (string, required) — Who or what it is, in a sentence or two. Used in prompts.
• image_url (string, optional)
• upload_id (string, optional)
• generate (boolean, optional)
• archetype (object, optional) — generate + kind person only: their look.
  • sex (male | female | androgynous, required)
  • age (integer, required)
  • skinColor (very light/pale | light/fair | light-medium-brown/olive | medium-brown/tanned | medium-dark/brown | dark/deep brown | very dark/ebony | black, required)
  • ethnicity (string, required)
  • bodyType (slim/lean | athletic/fit | average | curvy | stocky/broad | plus-size, required)
  • hairstyle (string, required)
  • facialFeatures (string, optional)
  • clothing (string, required)

remove_subject — Remove subject

Removes a subject (or a pending/failed subject image) that no moment tags.

• project_id (string, required) — The project's id.
• subject_id (string, required) — From get_project's cast or pendingSubjects.

add_moment — Add required moment

Optional — except for uploaded videos. Adds a required moment: a scene the ad must contain; the script is written around it and the storyboard places it where it fits. Without moments the script and storyboard decide everything, which is fine. BUT an uploaded video only appears in the ad through a custom-footage moment — uploading it alone does nothing; give footage (its media_id and the range to play, muted). Types: product-shot (someone holds/uses the product, face in frame), product-shot-faceless (close look at the product, no face), b-roll (supporting footage: a place, object, mood), product-action (the product in motion, from its photos), talking-person (the narrator says dialogue to camera), custom-footage. Tag who's in frame in the description with @[Name] from get_project's cast (e.g. "@[Main Character] pours @[Glow Serum] into her palm"). Add moments before generate_script; the total must fit the script's length.

• project_id (string, required) — The project's id.
• type (product-shot | product-shot-faceless | b-roll | product-action | talking-person | custom-footage, required)
• description (string, required) — What happens, with @[Name] tags for who/what is in frame.
• dialogue (string, optional) — talking-person only: the exact words the narrator says.
• text_overlay (string, optional) — On-screen text for this moment.
• product_media_ids (list of string, optional) — Product photos the shot must feature (from get_project's media).
• footage (object, optional) — custom-footage only: which clip and which part of it plays.
  • media_id (string, required) — A video from get_project's media.
  • start_seconds (number, required)
  • duration_seconds (number, required)

remove_moment — Remove moment

Removes a required moment (from get_project's moments) from the ad.

• project_id (string, required) — The project's id.
• moment_id (string, required) — From get_project's moments.

set_creative_brief — Set creative brief

Sets the ad's format and campaign facts (who it's for, the benefit to sell, the action to drive). Facts you leave out are deduced from the product (a few credits). For the custom format pass idea — the ad you have in mind, in your own words — and a full brief is written from it.

• project_id (string, required) — The project's id.
• format (problem-solution | testimonial-review | before-after-transformation | reaction-video | storytime | custom, optional) — From list_formats. Required the first time.
• target_audience (string, optional)
• benefit_to_highlight (string, optional)
• primary_ad_goal (string, optional) — The action viewers should take, e.g. "Buy now", "Download the app".
• funnel_stage (top-of-funnel | mid-funnel | bottom-funnel, optional)
• idea (string, optional) — custom format only: the ad you want, described freely.

set_actor — Set actor

Casts the on-camera narrator and renders their portrait, which every scene is generated from — the app's actor form. Leave archetype out to cast someone fitting the audience automatically. Pass archetype to design them: for a project with an actor, only the fields you give change (e.g. just clothing); a first actor needs every field except facialFeatures. Each call renders a new portrait (1 credit); show the user previewUrl.

• project_id (string, required) — The project's id.
• archetype (object, optional)
  • sex (male | female | androgynous, optional)
  • age (integer, optional)
  • skinColor (very light/pale | light/fair | light-medium-brown/olive | medium-brown/tanned | medium-dark/brown | dark/deep brown | very dark/ebony | black, optional)
  • ethnicity (string, optional) — e.g. "Eastern European"
  • bodyType (slim/lean | athletic/fit | average | curvy | stocky/broad | plus-size, optional)
  • hairstyle (string, optional) — e.g. "long blonde straight hair"
  • facialFeatures (string, optional) — e.g. "freckles, green eyes"; null clears it.
  • clothing (string, optional) — Upper-body clothing only, e.g. "casual white t-shirt".

generate_script — Generate script

Writes the voiceover script from the brief (calling it again writes a different variation), or saves script if you pass one. target_seconds sets the length (10–120s; trial accounts less). Changing the script after a storyboard means regenerating the storyboard.

• project_id (string, required) — The project's id.
• target_seconds (integer, optional)
• script (string, optional) — Your own script, spoken text only. Skips generation (free).

generate_storyboard — Generate storyboard

Plans the scenes from the script, actor and product photos. Runs in the background for 1–3 minutes: poll get_project until storyboard.scenes > 0, then review the scenes with the user. Needs a paid plan. Regenerating replaces the scenes.

• project_id (string, required) — The project's id.

start_video_generation — Start video generation

Generates the video from the storyboard: hook, voice, every scene, then the final render. Takes 10–30 minutes and spends the estimate get_project returns (estimatedVideoCredits). Confirm that with the user and pass it as max_credits. Poll get_video_status.

• project_id (string, required) — The project's id.
• max_credits (integer, required) — The most this run may cost; it refuses above it.

get_video_status — Get video status

Progress of a project's video generation, and the finished video's URL once it's rendered. Poll every couple of minutes, not faster.

• project_id (string, required) — The project's id.

resume_video_generation — Resume video generation

Retries a failed or stalled video generation from where it stopped, when get_video_status suggests it.

• project_id (string, required) — The project's id.

---

This guide: https://app.retiplex.com/help/agents (Markdown: https://app.retiplex.com/help/agents.md). Connected agents can also read it as the MCP resource retiplex://guide.