Quickstart: connect an AI agent over MCP

1. Create a token

1. Sign in as a workspace admin and open Developers in the sidebar.
2. Name the token and pick a mode: plan_only to look around, interactive to build projects, execute when the agent may also start paid work after a person approves the price.
3. Pick an expiry of 1, 7 or 30 days. The token covers the whole workspace and every tool of the mode, so it also gets tools added later. For one project or single tools, use Settings, section API & MCP.
4. Copy the token: it is shown once. Keep it in an environment variable such as MCP_API_TOKEN; never paste it into a prompt, a chat or a file in a repository.
5. For an execute token, choose Edit limits in the token list and set a spend cap before the agent starts paid work.

2. Add the MCP server to your client

The address is the studio you sign in to, followed by the endpoint path /api/v1/agent/mcp. In the examples, STUDIO_URL holds that address, for example https://<your-studio-host>, and MCP_API_TOKEN holds the token.

claude mcp add --transport http rpt-video "$STUDIO_URL/api/v1/agent/mcp" \
  --header "Authorization: Bearer $MCP_API_TOKEN"

[mcp_servers.rpt-video]
url = "https://<your-studio-host>/api/v1/agent/mcp"
bearer_token_env_var = "MCP_API_TOKEN"

{
  "mcpServers": {
    "rpt-video": {
      "url": "https://<your-studio-host>/api/v1/agent/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Other MCP clients, such as a ChatGPT custom connector in developer mode, use the same address with an Authorization: Bearer header. Start with a plan_only or interactive token until you trust the flow.

3. Check the connection

1. List the tools (tools/list). You see only the tools your token’s mode allows.
2. Call get_workspace with no arguments. It returns your workspace id, its name and your role.
3. Call list_video_models with that workspace_id. Use only a ref whose selectable is true; never guess one.
4. Once you have a project, call agent_preflight with its project_id. It returns blockers, warnings and the exact next_calls for your token.

get_workspace {}
list_video_models {"workspace_id": "<id from get_workspace>"}
agent_preflight {"project_id": "<project id>"}

4. Make a first video

Follow Product clip from one photo: create a project, attach the photo, submit a storyboard, quote, wait for the person’s yes, produce and deliver.

When unsure what comes next, call agent_continue with the project_id. It never spends and never changes anything; it returns one receipt with the next call.

5. When a call fails

• Read structuredContent.error and do what next_action says. The error reference explains the codes.
• MODE_FORBIDS_TOOL: the token’s mode does not include that tool. A workspace admin creates a token with the right mode.
• TOKEN_RATE_LIMITED and TOKEN_CONCURRENCY_LIMIT: wait, then try again. TOKEN_SPEND_CAP_REACHED: tell the person; an admin can raise the cap on the Developers page.
• After a timeout or WRITE_OUTCOME_UNKNOWN, read the state (for example with get_run_progress) before anything else.
• Token expired: an admin creates a new one on the Developers page; update the environment variable.