AI Agent Video Automation: Designing the Control Loop

Hand an agent a video URL and ask for shorts, and you have written a distributed system whether you meant to or not. The model taking the request is not the thing that transcribes, scores, reframes and encodes. It is the thing that decides which work to start, notices when that work has finished, and decides what happens to the output. It is a dispatcher. The renderer lives somewhere else, it takes minutes, and it will occasionally fail in a way the dispatcher has to interpret.

That one fact — the work outlives the tool call — separates video automation from the CRUD-shaped integrations agents are usually demoed against. A weather lookup answers in 300 milliseconds. A clip job answers in minutes. Everything below follows from designing around that gap: how a tool hands back a job handle instead of a result, how the loop polls without flooding the context window, how a retry avoids starting a second job, and where a person has to put their name on something before an audience sees it.

The code targets one concrete implementation — the ClipSpeedAI MCP server at https://api.clipspeed.ai/mcp, ten tools over streamable HTTP — because abstract advice about asynchronous agent design is close to worthless without argument names attached. The shapes transfer to any service built the same way. If the protocol itself is new, What Is MCP? Model Context Protocol Explained is the prerequisite reading; this page assumes you already know what a tool list is and how a client fetches one.

The Job Handle Decides Everything Downstream

Start with the smallest question in the whole design: what does the tool return before the work is done?

There are two possible answers and they produce different systems. A blocking tool holds the connection open until the render finishes and returns clips. A handle tool returns an identifier immediately and expects you to come back for the result. ClipSpeedAI takes the second route — submit_to_clipspeed returns a projectId, clip_livestream returns a subscriptionId, and separate tools redeem those handles.

Blocking would be simpler to call and unusable in practice. Agent clients enforce per-call timeouts measured in seconds to low minutes. A blocking render would trip that timeout, the client would surface an error, the model would read the error as failure, and the model would retry — starting a second render of the same video while the first is still going. You would get duplicate work, no result, and a confused transcript. The handle pattern converts a long operation into a sequence of short ones, each of which fits comfortably inside a tool-call budget.

The cost is that you now own a state machine. A handle is a promise you have to redeem, bound, and eventually give up on. Most of the engineering on this page is bookkeeping around handles: storing them, deduplicating them, expiring them, and refusing to create more of them than your account can absorb. If you are writing a server rather than consuming one, How to Build an MCP Server (Practical Guide) works the same problem from the implementer's side, and MCP Tool Design: Writing Tools an Agent Can Actually Use covers why splitting start from poll makes a tool legible to a model.

The Example This Page Keeps Coming Back To

Generic pipelines produce generic advice. So: a two-host interview show. They record roughly eighty minutes on Thursday and publish the full episode. They also go live on Twitch on Sunday afternoons for two or three hours, unscripted. They want shorts from both, they have one YouTube channel to feed, and neither host wants to open an editor.

Those two sources are not the same problem, and the difference is not the file format.

• Thursday is a bounded job. There is an end of file. The whole recording exists before processing starts, the work has a finish line, and the agent's loop can be written as "start, wait, collect, stop." Failure is legible: either clips came back or they did not.
• Sunday is an open session. There is no end of file until the stream ends, which nobody controls. Clips arrive continuously, some of them are still finishing while you are reading the list, and the loop only terminates on an external condition. Failure is partial by default — you can have six good clips and a session that died.

Almost every mistake in agent video automation comes from writing the Sunday loop as though it were the Thursday loop. The recorded path forgives sloppiness because it terminates on its own. The live path does not.

Seven States a Clip Passes Through

Rather than a vendor-shaped pipeline diagram, track the states a single unit of work moves through, and who is responsible for advancing each one. This is the table to keep next to you while writing the loop, because every bug is a state that nothing advances.

Two things fall out of writing it this way. First, claimed exists before submitted on purpose — the reservation has to happen in your storage before the network call, or a retry that fires during a slow submit will start a second job. Second, the only transition an agent should never own is the last one. Everything above it is recoverable; that one is not.

What You Delegate, and What Stays Yours

A useful way to size the delegation: list the decisions in the pipeline and mark who makes each.

• Which source to process — the agent may propose, you should cap. A model that decides how many jobs to start eventually decides "all of them."
• Which caption template — genuinely fine to delegate, as long as the model reads the real list rather than guessing an id. list_templates returns exactly six: karaoke, hormozi, beasty, fire, youshaei, cinematic. The chosen id goes back as captionStyle.
• Which moments are worth cutting — not the agent's decision at all. That happens inside the service, and buying it is the entire reason you are calling an API instead of running ffmpeg.
• Which finished clips clear your bar — the agent can rank and filter, but on criteria you wrote down. "Pick the good ones" is not a criterion.
• Whether anything goes public — yours.

Notice how little the model is actually doing in a well-built version of this. It selects, sequences, reads results, and branches. That is orchestration, and it is worth tokens. Having a model type JSON into a fixed sequence is not. If the boundary between this and provider-native function calling is still fuzzy, MCP vs Function Calling: What Actually Differs is the page that untangles it.

Keys: Format, Counters, and Blast Radius

GUI clients authenticate to the server over OAuth. Command-line and headless clients send a bearer key, generated in the app under Account → API & Integrations → Generate API Key.

The key has a fixed, checkable shape: the literal prefix csai_live_ followed by 48 hexadecimal characters. That is worth a guard clause at process start, because a truncated or shell-mangled key otherwise surfaces as an authentication error three tool calls later.

import os, re, sys

KEY = os.environ.get("CLIPSPEED_API_KEY", "")
if not re.fullmatch(r"csai_live_[0-9a-f]{48}", KEY):
    sys.exit("CLIPSPEED_API_KEY is missing or malformed "
             "(expected csai_live_ + 48 hex chars)")

Three operational facts matter more than the format:

• The full key is shown once. Only a prefix is stored for display, so there is no "show me that key again" path. Put it in a secret manager or an environment variable the moment it appears, never in a config file that can be committed.
• Keys carry their own counters. Listing your keys returns a name, prefix, plan, rate limit, requests today, total requests, and last-request timestamp, along with active status and creation date. That turns rotation from guesswork into a check: before you revoke an old key, look at whether it is still being used and by roughly how much.
• Revocation is real and immediate. Deleting a key marks it inactive and stamps a revoked timestamp. A leaked key is a five-second problem, not a rebuild-the-integration problem.

Give every automated surface its own key — one for the Thursday cron, one for the live watcher, one for your laptop. Shared keys make the counters meaningless and turn any single leak into a full rotation. MCP Authentication: OAuth and Bearer Keys goes through both credential paths in detail, and MCP Security: Scopes, Keys and Safe Tool Design covers the threat model around a key that can reach a publish tool.

Connecting, in One Command

There is a single remote server. Nothing runs on your machine — no local process to supervise, no ffmpeg install, no per-client SDK. For Claude Code the whole integration is one line:

claude mcp add --transport http clipspeed https://api.clipspeed.ai/mcp \
  --header "Authorization: Bearer <API_KEY>"

For every other client the shape is identical and the syntax is theirs: register an HTTP MCP server pointing at that endpoint, with your key in an Authorization: Bearer header, following that client's own MCP documentation. Config file locations and field names differ between vendors and change between releases, so read their docs rather than trusting a copied snippet — including one from a page like this. ClipSpeedAI MCP for Claude Code: Complete Setup Guide has the step-by-step for the command above.

The remote-only design is doing quiet work here. There is no version skew between your machine and the renderer, no dependency to keep current, and the same credential works from a laptop, a CI job and a hosted connector. Remote MCP vs Local MCP Servers is the argument in full; How MCP Servers Work: Architecture and Request Flow covers what the transport is actually doing underneath.

The Ten Tools, Grouped by Role

Read the surface as a state machine and the groupings become obvious: two tools start work, two report on it, two steer a running session, three produce metadata, one publishes.

Before the code, one standing caveat that applies to all three workflows below. Argument names above are read off the live tool definitions, but response shapes are not part of a tool's input schema. Treat every field access in the samples — projectId, clips, score, hasCaptions, status — as a sketch, print one real response before you rely on it, and write defensively with .get() rather than subscripting. tools/list is the authority for inputs; a live call is the authority for outputs; both change.

Thursday: A Bounded Job, Written Safely

At the wire level a tool call is JSON-RPC over HTTP. A compliant client runs an initialize handshake first and carries the returned session id afterwards, so the curl below shows the payload shape, not a working client:

curl -sS https://api.clipspeed.ai/mcp \
  -H "Authorization: Bearer $CLIPSPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "submit_to_clipspeed",
      "arguments": {
        "videoUrl": "https://www.youtube.com/watch?v=EXAMPLE",
        "orientation": "vertical",
        "captionStyle": "hormozi",
        "count": 6
      }
    }
  }'

Use an SDK for anything real, so the handshake, session header and streamed responses are somebody else's problem:

import asyncio, json, os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

ENDPOINT = "https://api.clipspeed.ai/mcp"
HEADERS  = {"Authorization": f"Bearer {os.environ['CLIPSPEED_API_KEY']}"}

def payload(result):
    """Tool results arrive as content blocks; JSON tools return text."""
    return json.loads(result.content[0].text)

async def render_episode(s, video_url, *, deadline_s=1800, interval_s=30):
    started = payload(await s.call_tool("submit_to_clipspeed", {
        "videoUrl": video_url,
        "orientation": "vertical",
        "captionStyle": "hormozi",
        "count": 6,
    }))
    project_id = started["projectId"]

    waited = 0
    while waited < deadline_s:
        await asyncio.sleep(interval_s)
        waited += interval_s
        result = payload(await s.call_tool("check_clips",
                                           {"projectId": project_id}))
        clips = result.get("clips") or []
        if clips:
            return project_id, clips

    # the handle still exists; hand it to a human rather than resubmitting
    raise TimeoutError(f"{project_id}: no clips after {deadline_s}s")

async def main():
    async with streamablehttp_client(ENDPOINT, headers=HEADERS) as (r, w, _):
        async with ClientSession(r, w) as s:
            await s.initialize()
            project_id, clips = await render_episode(
                s, "https://www.youtube.com/watch?v=EXAMPLE")
            ranked = sorted(clips, key=lambda c: c.get("score") or 0,
                            reverse=True)
            for c in ranked[:3]:
                print(c.get("score"), c.get("title"))

asyncio.run(main())

Three deliberate choices in that loop. The wait is bounded, so a stuck job raises instead of hanging a process forever. The timeout does not resubmit — the projectId is still valid and still the way to reach that job, so the correct move is to surface it. And selection ranks rather than thresholding: check_clips returns a viral score per clip, and the honest use of it is as an ordering. Take the top few, or set a cut-off you have validated against your own posted results — do not treat any particular number as a documented pass mark.

AI Clipping API: Programmatic Short-Form Video goes deeper into what the scoring and reframing stages are doing to produce that list.

Sunday: A Loop That Has to Be Told When to Stop

The live path changes three things at once: the loop's exit condition is external, output arrives incrementally, and individual clips are visible before they are finished.

async def watch_stream(s, stream_url, *, poll_s=150, notify=print):
    session = payload(await s.call_tool("clip_livestream", {
        "streamUrl": stream_url,
        "layout": "square",
        "maxMinutes": 60,
    }))
    sub = session["subscriptionId"]

    finished = {}          # keyed so repeated polls cannot duplicate a clip
    try:
        while True:
            await asyncio.sleep(poll_s)
            state = payload(await s.call_tool("check_livestream",
                                              {"subscriptionId": sub}))

            for c in state.get("clips") or []:
                if c.get("hasCaptions"):
                    finished[c.get("id") or c.get("url")] = c

            if state.get("nearCap"):
                # extending is a spend decision — ask, never decide
                notify(f"session {sub} near its cap, "
                       f"{len(finished)} clips finished")

            if state.get("status") != "monitoring":
                break
    finally:
        await s.call_tool("stop_livestream", {"subscriptionId": sub})

    return list(finished.values())

What each detail is protecting against:

• hasCaptions is the completion flag. Captions burn in a couple of minutes after a clip is born, so a clip can appear in the list while it is still cooking. Filtering on it is the difference between shipping finished work and downloading half-rendered files.
• Accumulating into a dict, not a list. Every poll returns everything so far. Append naively across ten polls and clip one appears ten times.
• stop_livestream in a finally. If your process crashes mid-loop the session does not care — it keeps running until its cap. Stopping keeps the clips and releases the session.
• nearCap notifies rather than extends. Sessions auto-stop at maxMinutes (60 by default, hard-capped at 180 in total), and extend_livestream exists precisely so that continuing is an explicit act. Extending draws on a monthly live budget; that is a person's call, not a model's.
• square is the live default, not vertical. It is the right default for maximum view on gameplay and multi-person streams, and it is the single most common surprise for anyone who assumed 9:16 everywhere. Pass layout explicitly if you need something else.

The Sunday show runs two to three hours, which means one 60-minute session will not cover it and 180 minutes is a ceiling, not a suggestion. Plan the coverage window rather than assuming a session spans the broadcast. Livestream Clipping API: Clip While You Stream covers the streaming path in depth.

Seeding the Queue Without Handing Over the Credit Card

Discovery is where the run stops being a script. Nothing about the inputs is known at design time — the agent asks what is moving in a niche, and acts on the answer.

MAX_PER_RUN = 2

def candidates(found, limit):
    """discover_trending is documented as finding the fastest-growing
    recent video; normalise singular and list-shaped responses."""
    videos = found.get("videos") or found.get("results") or []
    if not videos and found.get("url"):
        videos = [found]
    return videos[:limit]

found = payload(await s.call_tool("discover_trending",
                                  {"niche": "AI tools", "days": 7}))

for video in candidates(found, MAX_PER_RUN):
    url = video.get("url")
    if not url or ledger.claim(url):        # already processed, skip
        continue
    started = payload(await s.call_tool("submit_to_clipspeed",
                                        {"videoUrl": url}))
    ledger.record(url, started["projectId"])
    pack = payload(await s.call_tool("creator_pack",
                                     {"projectId": started["projectId"],
                                      "platform": "tiktok"}))
    queue_for_review(started["projectId"], pack)

MAX_PER_RUN is a constant in code, not a sentence in a prompt. Prompt instructions are guidance; a constant is a limit. The distinction stops mattering right up until the run where it matters enormously.

The honest limit of this pattern: discover_trending ranks by view velocity inside a recency window — days defaults to 21 and clamps between 3 and 60. It tells you what is moving in a niche. It does not know whether a given video suits your channel, your tone, or the show your audience subscribed to. That judgment stays with you, or with a filter you wrote on purpose.

The Ledger That Makes Retries Boring

Agents retry. They retry on ambiguous errors, on timeouts, on responses they could not parse, and sometimes on a response they parsed fine but did not like. A pipeline without deduplication turns every one of those retries into a second render of a video you have already rendered — wasted capacity, duplicate clips, and a review queue full of near-identical entries.

The fix is small and it goes in your storage, not in the prompt:

import sqlite3

class Ledger:
    def __init__(self, path="clipspeed_runs.db"):
        self.db = sqlite3.connect(path)
        self.db.execute(
            "CREATE TABLE IF NOT EXISTS runs ("
            "  source_url TEXT PRIMARY KEY,"
            "  project_id TEXT,"
            "  created_at TEXT DEFAULT (datetime('now')))")
        self.db.commit()

    def claim(self, url):
        """Returns an existing project_id, or None if the URL is new.
        Insert the row BEFORE submitting so a retry mid-submit
        finds the claim instead of starting a second job."""
        row = self.db.execute(
            "SELECT project_id FROM runs WHERE source_url = ?",
            (url,)).fetchone()
        if row:
            return row[0]
        self.db.execute("INSERT INTO runs (source_url) VALUES (?)", (url,))
        self.db.commit()
        return None

    def record(self, url, project_id):
        self.db.execute("UPDATE runs SET project_id = ? WHERE source_url = ?",
                        (project_id, url))
        self.db.commit()

    def today(self):
        return self.db.execute(
            "SELECT COUNT(*) FROM runs "
            "WHERE date(created_at) = date('now')").fetchone()[0]

Normalise URLs before they hit the primary key — strip tracking parameters, unify youtu.be short links with watch?v= forms — or the same video slips through under two spellings. And note today(): a daily counter costs one query and gives you a hard ceiling that no prompt injection, model mood, or overlapping discovery window can talk its way past. Discovery windows genuinely do overlap; a video found on Tuesday with days=7 is still inside the window on Wednesday.

Keep the same discipline for live sessions. One subscriptionId per stream URL per day, stored the same way, prevents two watchers attaching to one broadcast and both burning session time.

Polling Cadence and the Cost of Asking Too Often

Every poll that returns nothing useful still costs a round trip and, in an agent context, a chunk of the context window filled with an identical "not ready" payload. Context exhaustion is a common way long agent runs die, and tight polling is a reliable way to cause it.

Reasonable starting points, to be tuned against what you observe rather than treated as specification:

• Recorded jobs: on the order of every 30 seconds. Long enough to avoid churn, short enough that a finished job is not sitting idle for minutes.
• Live sessions: every two to three minutes, which matches the cadence the live tools themselves suggest and roughly matches how long captions take to burn in after a clip is born.

Two refinements worth having. Poll in your code, not by asking the model to call the tool again — a Python while loop costs nothing per iteration, while a model-driven poll costs a full turn each time. And when you do surface poll results into a model's context, summarise: "3 of 6 clips finished" carries the decision-relevant information that a full JSON blob buries.

If the workflow has no decisions in it at all, this is the moment to notice. MCP vs REST API: When to Use Each makes the case that a fixed nightly job should call a plain HTTP endpoint and skip the model entirely.

Where a Person Has to Sign

Draw the line at irreversibility, not at importance. Reading, submitting, scoring, ranking and generating metadata are all cheap to undo — worst case you discard the output. Two actions are not cheap to undo, and both deserve a gate.

Publishing. publish_to_youtube defaults to private, which is the correct default and worth keeping. Let the agent do the whole upload — clip selection, title from creator_pack, description, the lot — and leave it private. A person reviews the staged uploads and flips visibility. This is not a temporary training-wheels arrangement; it is a reasonable steady state for most channels, because the review takes ninety seconds and the alternative failure mode is public.

Extending a live session. extend_livestream lengthens an open-ended job and draws down a monthly live budget. An agent that extends on its own has made an unbounded commitment on your behalf. The right behaviour is the one the nearCap signal is designed for: notice the ceiling approaching, say so, and wait.

A general principle for anyone designing tools rather than calling them: irreversible and costly actions belong in their own tool with explicit arguments, never as a boolean tucked inside a larger call. A model that has to name the dangerous tool is far less likely to trigger it by accident than one that has to remember to leave a flag alone.

Four Integration Surfaces, Four Different Jobs

Pick by workload shape, not by which demo was most impressive.

• An MCP server when a model is already in the loop and the work is conversational or exploratory — "clip this episode and tell me which three are worth posting." One integration serves every compliant client, and the model chains tools without you scripting the chain.
• A direct HTTP API when the workflow is fixed, high volume, or has to be auditable. A nightly job over a known feed gains nothing from a model choosing arguments and loses determinism, cheap retries and a clean audit log.
• A hosted automation builder when the pipeline is linear, the volume is modest, and nobody wants to own a deployment. You trade flexibility for not being on call.
• Self-hosted rendering when clipping logic is the product, the format requirements are unusual, or the content cannot leave your infrastructure. Price it honestly: transcription, moment scoring, face tracking, caption rendering and encoding are five separate systems plus the queue that runs them.

A common mistake is reaching for MCP on a batch job. If no judgment is being delegated, you are paying tokens for a cron. Another is self-hosting the render stage to save money and rediscovering why encoding farms are a business. A hybrid settles both: MCP for interactive work, plain HTTP for the schedule, one service and one credential behind both.

Best MCP Servers for Video and Content Workflows surveys the agent-facing options; Video Clipping API for Developers focuses on integration ergonomics if you land on the HTTP side.

Client Tiers, Stated Precisely

One server, many clients. But "speaks MCP" and "verified end to end" are different claims, and treating them as one wastes an afternoon.

The transport is the same everywhere: HTTP to https://api.clipspeed.ai/mcp, with OAuth for GUI clients and an Authorization: Bearer header for everything else. Per-client setup guides cover the individual clients, including ClipSpeedAI MCP for Windsurf: Complete Setup Guide for the fully-supported editor path and ClipSpeedAI MCP for ChatGPT: Complete Setup Guide for the rollout-gated one. If you are choosing where to run these loops day to day, Claude Code vs Cursor for MCP Workflows compares the two development surfaces directly.

Symptom, Cause, Fix

The failures worth building for, in the form you will actually encounter them — as a symptom, before you know the cause.

The credential row is worth internalising because it looks like the scariest failure and is the most trivial. When everything breaks simultaneously, that is an auth signature, not a product outage.

Buy the Middle, Own the Edges

Across every vendor in this category the same asymmetry holds. Acquiring sources and distributing output are cheap to build and expensive to operate — OAuth refresh, platform quotas, rate limits, the endless small breakages of other people's APIs. Understanding and rendering are expensive to build and comparatively safe to outsource, because the interface is narrow: a URL in, scored clips out.

That is why most teams buy the middle. When evaluating who to buy it from, categories matter more than brand names — browser-first clipping products aimed at creators, developer-facing APIs, general media-processing platforms, and self-hosted open source are answers to different questions, and public feature sets move constantly. Verify against current documentation rather than any comparison page, this one included.

Questions that separate candidates quickly:

1. Is there a documented, stable programmatic surface, or is the UI the only real interface?
2. Does work return a handle you can poll, or does the call block?
3. What is the unit of billing — source minutes, output minutes, jobs, seats?
4. Can you retrieve raw assets, or only view them in a player?
5. Is scoring exposed as a value you can rank on, or hidden behind an opaque ordering?
6. On partial failure, do you get partial output, restored capacity, or silence?
7. Does publishing default to private?
8. Can you revoke a credential yourself, immediately, without support?

Answer those eight per candidate and the choice tends to make itself. MCP for Video Editing and Clipping Workflows walks through the editing-side patterns if your team's centre of gravity is production rather than infrastructure.

What ClipSpeedAI Covers, and What It Does Not

It covers the middle of the pipeline and exposes it to agents natively. Scoring comes back per clip, so filtering is a comparison rather than a vibe. Clipping a stream while it runs is a genuinely different control problem from clipping a recording afterwards, and it is a first-class tool here rather than an afterthought. One endpoint and one credential serve Claude Code, a Python script, and a GUI connector alike.

The limits, plainly:

• No free plan. There is a free demo — one demo, on a video under 30 minutes. Past that, $1 starts a 3-day trial (a one-time $1 today, converting after 3 days unless cancelled). Plans are Starter $15/mo, Pro $29/mo and Ultra $49/mo, with annual billing saving 50%.
• Publishing is YouTube-only through the tool surface, and needs a connected account. Every other platform is an integration you build.
• Live sessions are capped at 180 minutes total and draw on a monthly live budget, so a long unattended broadcast needs a plan rather than an assumption.
• Four clients are verified end to end. The rest are protocol-compatible, which is real but is not the same guarantee.
• You do not control the clipping model. If your differentiator is a custom notion of what makes a good moment, buying a service that scores for you is the wrong layer to buy.

If you would rather run these workflows in conversation than in Python, MCP for Creators: Automating Video Without Code covers the same ground without the code. If you are building: start with the Thursday loop, add ranking, keep publishing manual for a fortnight, and automate the last mile only after you have watched the selection quality with your own eyes.

Frequently asked questions

What is the smallest agent video pipeline that actually works?

One connected MCP client, one API key, and three calls: submit_to_clipspeed with a video URL, a bounded polling loop on check_clips, and a human review step before anything becomes public. Discovery, creator_pack metadata and automated staging are all refinements to add once that base loop survives a week without supervision.

Why does the tool hand back a projectId instead of the clips?

Because rendering takes minutes and agent clients time out tool calls in seconds. A blocking call would trip the client timeout, the model would read the error as failure, and it would retry — starting a second render of the same video while the first is still going. Returning a handle turns one long operation into a series of short ones, each of which fits inside a tool-call budget.

How often should the polling loop run?

On the order of every 30 seconds for recorded jobs and every two to three minutes for live sessions, tuned against what you observe rather than treated as a specification. Poll inside your own code rather than by asking the model to call the tool again — a Python loop costs nothing per iteration, while a model-driven poll costs a full turn and a context-window slot each time.

Should an agent publish videos on its own?

Publishing is the one step you cannot take back, which is why publish_to_youtube defaults to private. The pattern that holds up is to let the agent do the entire upload — clip choice, title, description — and leave the result private, then have a person flip visibility after a quick look. That review costs about ninety seconds; the failure mode it prevents is public.

Why are my livestream clips square when my recorded clips are vertical?

Because the live path defaults to layout: square, which maximises usable view on gameplay and multi-person streams, while the recorded path defaults to orientation: vertical for 9:16. Pass layout explicitly on clip_livestream if you need something else. More generally, set layout and orientation by hand in any automated pipeline rather than inheriting defaults you have not checked.

How do I stop an agent from starting the same job twice?

Keep a ledger keyed on the normalised source URL, and insert the claim row before the tool call rather than after — a retry that fires during a slow submit needs to find the claim already there. Strip tracking parameters and unify short links before they hit the key, or one video slips through under two spellings. Prompt wording will not do this job; storage will.

What can I safely do with the viral score?

check_clips returns a viral score with each clip, and the dependable use of it is as an ordering: sort, take the top few, and let a person confirm. Treating a specific number as a documented pass mark is not supported — if you want an absolute cut-off, derive one from clips you have actually posted and measured, and revisit it.

What happens to a live session if my process dies mid-loop?

The session does not care about your process; it keeps running until it hits maxMinutes, which defaults to 60 and is hard-capped at 180 in total. Clips made before that point are kept and stay downloadable. Call stop_livestream from a finally block so a crash still releases the session, and store the subscriptionId somewhere durable so you can stop or poll it from a different process.

Can I run these workflows without MCP at all?

Yes, and for scheduled work you probably should. MCP is the agent-facing surface; a fixed, high-volume nightly job is better served by a script calling the service directly, where retries are cheap and behaviour is deterministic. Use MCP where a model is genuinely deciding something — which sources to process, which clips clear your bar — and plain automation for everything else.

Which clients are actually verified for ClipSpeedAI's MCP server?

Claude (claude.ai), Claude Code, Claude Desktop and Windsurf are verified end to end. Cursor, Codex, OpenClaw and Hermes use the same HTTP plus bearer-key pattern and work by configuration, with full verification in progress. ChatGPT support is gated by the vendor's connector rollout and is not yet verified.

Related reading