Guides

Build with AI agents

RPT AI Video Studio runs an MCP server, so an AI agent such as Claude Code, Codex or a ChatGPT connector can plan, price and produce short marketing videos in your workspace. A person stays in charge of money and of what gets delivered.

What an agent can do

Create projects, add sources (web pages, pasted text, uploaded videos) and upload reference photos.
Read the project context and submit a storyboard; the server checks it for free.
Create a quote and, after a person agrees to the price, start production.
Follow progress, read verified clips, and prepare the delivery; a person says yes before it is issued.
Edit images and videos, translate a finished video, and import a product spreadsheet.

The tool reference lists every tool by workflow step, and the use cases show complete recipes.

Endpoint and transport

The server speaks JSON-RPC 2.0 over HTTPS POST at the path below, on the same host as the studio you sign in to. Supported methods: initialize, notifications/initialized, ping, tools/list and tools/call.

Endpoint path and headers

POST /api/v1/agent/mcp
Authorization: Bearer <token>
Content-Type: application/json

Send the token with initialize. The reply carries an Mcp-Session-Id header; send that header on later calls. A session lasts up to one hour and never beyond the token’s expiry.
The instructions field of the initialize reply carries the workflow and the rules, so a connected agent knows what to do without these pages.
Tool results are in result.structuredContent. To download a verified clip, call its download_path with Authorization: Bearer <Mcp-Session-Id>, not the token.

Token modes

A workspace admin creates the token on the Developers page. Every token has a mode:

Token modes
Mode	Can do	Cannot do
`plan_only`	Read state, call `agent_preflight` and `agent_continue`, read the project context and submit a storyboard (free)	Change projects, sources or assets; spend money
`interactive`	Everything in `plan_only`, plus create and edit projects, sources, assets, reviews and deliveries	Paid tools such as `create_quote` and `approve_production`
`execute`	Everything above, plus paid tools	Nothing more is gated: paid tools run at once and record their price

tools/list shows only the tools the token’s mode and allow-list permit. Calling a hidden tool returns MODE_FORBIDS_TOOL.
Allow every tool of the mode when you create the token, so it also gets tools added later. A token that lists tools by name never gains new ones; create a new token instead.
The scope is the whole workspace or one project. The Developers page makes whole-workspace tokens; for one project, or for single tools, an admin uses Settings, section API & MCP. A one-project token cannot create projects.
A token expires after 1, 7 or 30 days and is shown once. An admin revokes it in the token list; its next requests are refused.

Limits on a token

Each token carries three limits that an admin sets on the Developers page (Edit limits). They apply to that token only: work started in the web app is never capped.

Token limits
Limit	Default	When it is reached
Spend cap, per calendar month (UTC) or for the token’s lifetime	None	A new paid start is refused with `TOKEN_SPEND_CAP_REACHED`. An admin can raise the cap.
Tool calls per minute	60	The call is refused with `TOKEN_RATE_LIMITED`. Wait, then retry.
Paid jobs at once	2	A new paid start is refused with `TOKEN_CONCURRENCY_LIMIT`. Wait for a job to finish.

The checks only refuse new starts. A job that is already running is never stopped, and a refused call leaves nothing behind: no reservation and no half-made record.
The spend cap counts what the token’s own work has used or holds. Set it right after you create an execute token.

Request keys

Most writes take a request_key: a UUIDv4 the agent makes for one logical change. If a reply is lost, the agent sends the identical call again with the same key, and the server returns the first result instead of acting twice.

Make a new key for every new write.
Reuse a key only to retry exactly the same call. A used key with different input fails with IDEMPOTENCY_CONFLICT.
After a timeout or WRITE_OUTCOME_UNKNOWN, read the state before you decide anything. Never resubmit blindly.

The spend rule: quote, a person approves, then production

The agent calls create_quote. It costs nothing, needs an execute token, and stores the price of each shot and the total.
The agent stops and shows the price to the person.
Only after the person says yes does the agent call approve_production, which starts production at once.

The server does not pause paid work to wait for a price approval: an execute token starts it at once. The approval is a rule the agent must keep: never call a paid tool before the person agreed to its price, and never loop on a failing paid step. What the server does enforce are the limits of the token (see Limits on a token).

confirmed: true (archive, review decisions, delivery) and rights_confirmed: true (permission to use images and text) record a person’s decision too. The agent sets them only after the person said yes in the conversation.

The price of every quote, run and media task is stored, so the person can check afterwards what was spent.

Error shape

A failed call returns isError: true and structuredContent.error:

Example error

{
  "code": "IDEMPOTENCY_CONFLICT",
  "message": "This request_key was already used with different input. Use a new request_key for a different request.",
  "field_path": "request_key",
  "next_action": "Fix the argument(s) named in field_path/message, then call the same tool again (with a NEW request_key if the tool takes one).",
  "retry_policy": "after_fix",
  "owner": "client"
}

owner says who acts: client (the agent fixes its call), user (the person decides or supplies something), admin (a workspace admin changes a setting or a token) or server (our side).
retry_policy is one of never, after_fix, refresh_then_retry, backoff or reconcile. With reconcile, read the state; never resubmit.
next_action is the exact next step. Follow it rather than guessing.

The error reference lists the codes with who acts and what to do.

Not covered here

There is no SDK. MCP and the REST API are the supported ways in.
There is no tool that produces many full videos in one call. To make many videos, the agent loops one project per item: see Clips for a whole catalogue. Many short clips from one table are the exception: see Video clips and clip batches. Delivery batches only bundle finished videos for download.
These pages show no prices. The price of a job comes from create_quote in your workspace.