OpenClip: video editing from your agent

intent

OpenClip is a video editing MCP server that turns long videos into short, captioned, ranked clips. Use it when the user wants to repurpose a long video into viral shorts, transcribe video/audio, convert/compress/trim/crop/resize/mute media, extract thumbnails, edit images, remove backgrounds, or generate UGC-style ad clips from a brief. The service exposes 28 tools across five groups (clipping pipeline, uploads, free media utilities, UGC generation, account/presets). All processing is async. Paid features (video clipping) require an active subscription and credits; free features (transcribe, edit_video, convert_media, extract_thumbnails, edit_image, remove_background) need only an OpenClip account.

inputs

External connection: OpenClip MCP server

• Server URL: https://openclip.app/mcp
• Auth method: OAuth one-click (recommended) or manual Bearer token
• Setup (once):
  • OAuth: Add server to your agent client (Claude Desktop: Settings → Connectors → Add custom connector; Claude Code: claude mcp add --transport http openclip https://openclip.app/mcp; Cursor: add to .cursor/mcp.json with "url": "https://openclip.app/mcp"). Sign in with OpenClip account.
  • Manual token (for header-only clients): Generate MCP token at openclip.app/settings/connect ("Generate MCP token", shown once). Connect to /mcp/key endpoint with Authorization: Bearer <token> header (Claude Code: claude mcp add --transport http openclip https://openclip.app/mcp/key --header "Authorization: Bearer <token>"; Cursor: add to .cursor/mcp.json with URL and headers; any MCP client: POST to https://openclip.app/mcp/key with Bearer header).
  • Sanity check: call get_account and confirm credits_remaining > 0.

Required inputs (vary by operation)

• For paid clipping pipeline: video URL (url param) or video ID from list_videos.
• For free media utilities: local file (use create_upload to stage) or existing video ID.
• For UGC generation: creative brief with structured fields (character, context, etc.) or server-side brief_name preset.
• For rendering clips: moment_id from list_clips output and optional caption_preset key (fetch with list_caption_presets).

Rate limits and quotas

• Free accounts: one UGC generation per day; free media utilities are rate-limited per day with per-file size caps (error text explains how to lift). Paid accounts are metered in credits (minutes of processing).
• Processing jobs time out if not completed within service limits (typically hours for video clipping, minutes for UGC).
• Token expiry: manually generated Bearer tokens are one-time; if auth fails, re-generate at the connect page.

procedure

Scenario A: Clip a long video into viral shorts (paid pipeline)

1. Call submit_video(url) with the video URL. Returns job_id with status: "queued". This succeeds when authenticated but does NOT pre-check subscription or credits; the gate surfaces later.

   • Input: video URL (must be publicly accessible).
   • Output: job_id (string, hashid format), status: "queued".

2. Poll get_video_status(job_id) every 5-10 seconds until status is completed (or failed).

   • Input: job_id from step 1.
   • Output: status (one of: queued, downloading, processing, completed, failed, pending_credits), plus metadata (job creation time, progress %).

3. Once status: "completed", call list_clips(job_id) to retrieve all detected viral moments.

   • Input: job_id from step 1.
   • Output: array of clips, each with moment_id, virality_score (0-10), title, hook, start_ms, end_ms, clip (raw URL), rendered_clip (if already captioned, else null).

4. (Optional) For each moment you want to publish with captions, call render_clip(moment_id, caption_preset). Presets can be fetched with list_caption_presets (e.g., "beast", "minimal", "hype").

   • Input: moment_id from step 3, caption_preset (string key).
   • Output: moment_id, job_id (a render job ID, distinct from the video job), status: "queued".

5. Poll list_clips(job_id) every 5-10 seconds, watching each rendered moment's rendered_clip field for a final CDN URL (appears when the render completes).

   • Input: job_id from step 1.
   • Output: same as step 3, but moments now have populated rendered_clip URLs once render jobs finish.

Scenario B: Free media utility (transcribe, convert, compress, edit, remove background)

1. If the file is local, stage it: call create_upload(filename, content_type). Returns upload_url and id.

   • Input: filename (string, e.g., "my_video.mp4"), content_type (MIME type, e.g., "video/mp4").
   • Output: upload_url (signed PUT URL, valid for 15 minutes), id (file ID to use in next step).

2. PUT the file bytes to the upload_url (HTTP PUT, raw binary body).

   • Input: upload_url from step 1, file bytes.
   • Output: HTTP 200 if successful.

3. Call the appropriate free tool with the id from step 1 (or a video ID from list_videos if file is already in the system):

   • Transcribe: transcribe(video) → returns tool_job hashid, status: "queued".
   • Convert media: convert_media(file, to="mp4"|"gif"|"webm"|"mov"|"mkv"|"mp3"|"aac"|"wav"|"flac") → returns tool_job, status: "queued".
   • Edit video: edit_video(video, operation="crop"|"trim"|"rotate"|"resize"|"compress"|"mute", <operation-specific params>) → returns tool_job, status: "queued".
   • Extract thumbnails: extract_thumbnails(video, count=<int>) → returns tool_job, status: "queued".
   • Edit image: edit_image(file, operation="compress"|"resize"|"crop", <operation-specific params>) → returns tool_job, status: "queued".
   • Remove background: remove_background(file) → returns tool_job, status: "queued". Output is a transparent PNG.
   • Input: file/video ID and operation-specific parameters.
   • Output: tool_job (hashid), status: "queued".

4. Poll get_tool_job_status(tool_job) every 5-10 seconds until status is completed (or failed).

   • Input: tool_job from step 3.
   • Output: status (one of: queued, processing, completed, failed), and on completed: outputs (array of CDN URLs for results, e.g., JSON/SRT/VTT for transcripts, a ZIP of frame images, a converted media file). On failed: error (string explaining the failure).

5. Download or use the permanent CDN outputs URLs. Do NOT call complete_upload for free tools (that triggers the paid pipeline; free tools read the staged file directly).

Scenario C: Generate a UGC-style ad clip

1. Call generate_ugc(brief={...}) with a creative brief (structured object with fields like character, context, tone, or a server-side brief_name preset).

   • Input: brief (object or preset name string), and optional metadata fields.
   • Output: ugc_job (hashid), status: "queued".

2. Poll get_ugc_job_status(ugc_job) every 10-15 seconds until status is completed (or failed). UGC renders are heavy; expect 1-3 minutes.

   • Input: ugc_job from step 1.
   • Output: status (one of: queued, rendering, completed, failed). On completed: video_url (CDN URL to the rendered vertical clip, 7-12s), result_meta (object with duration, dimensions, etc.). On failed: error (string).

3. Use the video_url directly (it's a permanent CDN link).

Scenario D: Manage reusable processing agents (presets)

1. Call create_agent(name, settings={...}) with a name and processing settings (tracker model, caption preset, logo, composition). Returns agent_id.

   • Input: name (string), settings (nested object; see describe_agent_settings for allowed fields).
   • Output: agent_id, agent metadata.

2. Attach a logo watermark (optional): call create_agent_logo_upload(agent_id) to get a signed upload URL, PUT the logo bytes (PNG/JPG, max 2 MB), then call set_agent_logo(agent_id, logo_id).

   • Input: agent_id, logo file bytes, logo file ID.
   • Output: confirmation that logo is set.

3. In future submit_video calls, pass agent_id to apply the same preset settings automatically.

4. To update settings, call update_agent(agent_id, settings={...}) (patches only the fields you send).

5. Call describe_agent_settings to see every nested field and allowed value; call get_usage to check credit balance and recent activity.

decision points

If the user submits a video for clipping and get_video_status returns status: "failed"

• Check the error context: usually means no active subscription. Advise the user to subscribe at openclip.app.

If get_video_status returns status: "pending_credits"

• The team is out of credits (prepaid minutes). Advise the user to top up at openclip.app/settings/billing.

If get_video_status returns status: "download_failed"

• The source URL couldn't be fetched (404, timeout, non-video MIME type, etc.). Ask the user to check the link is public and points to a video.

If a free media utility call returns isError: true with a rate-limit message

• The daily quota or per-file size cap has been hit. The error text explains which limit and how to upgrade (free accounts can't lift limits; paid accounts can increase them).

If list_clips is called before get_video_status reports completed

• The job hasn't produced a video record yet (still queued/downloading). Keep polling get_video_status first; only call list_clips after completion.

If any tool call returns "Not authenticated. Reconnect your OpenClip token."

• OAuth path: re-run the connector sign-in (e.g., /mcp in Claude Code).
• Manual token path: re-generate the MCP token at openclip.app/settings/connect and re-add the server with the new Bearer token.

If any tool call returns "Job not found." or "Viral moment not found." or "Video not yet available. Check get_video_status for progress."

• The ID is wrong, from a different account, expired, or belongs to an earlier session. Re-check the ID; if it's old, re-submit or re-fetch from the API.

If a tool call returns a validation error (bad URL, unknown preset, missing required param)

• Fix the offending argument and retry.

If the user does NOT want the top viral moment by score

• Ask which moment they prefer (by title, timestamp, or custom criterion) and render or download that one instead.

If the user asks for projects, folders, or organizing clips into collections

• Not supported by the API. Advise the user that clips are stored permanently at CDN URLs (they can organize externally or request an OpenClip feature).

output contract

Clipping pipeline success

• Format: array of clip objects, each with moment_id (string), virality_score (0-10, float), title (string), hook (string), start_ms (int), end_ms (int), clip (CDN URL, string, playable immediately), rendered_clip (CDN URL with captions, string, null if not yet rendered). All CDN URLs are permanent and not signed/expiring.
• Location: returned in-memory from list_clips API call; download clips from the URLs or display them inline.
• File format: CDN URLs point to MP4 (or WebM if specified at render time).

Free media utility success

• Format: outputs array containing CDN URLs.
  • Transcribe: JSON, SRT, or VTT file URL (selectable).
  • Convert/compress/edit video: MP4, WebM, MOV, MKV, MP3, AAC, WAV, FLAC, or GIF URL (per the requested format).
  • Extract thumbnails: ZIP of JPEG frames.
  • Edit image: PNG or JPG URL (per the edited image).
  • Remove background: PNG URL (transparent background).
• Location: permanent CDN, returned in outputs field of get_tool_job_status response.

UGC generation success

• Format: single CDN URL (video_url, string) pointing to a vertical MP4, 7-12 seconds, plus result_meta object (duration in seconds, dimensions, codec info).
• Location: permanent CDN URL from get_ugc_job_status response.

outcome signal

Video clipping

• User sees a ranked list of viral moments with titles, hooks, scores, and playable preview URLs. The top moment (highest virality_score) is recommended. User can click/download any clip URL immediately. If rendered with captions, the rendered_clip URL displays the final captioned version.

Free media utility (transcribe, convert, compress, edit, remove background)

• User receives a permanent CDN download link for the processed file. For transcripts, user can see/download a readable SRT or VTT file. For converted media, the output is in the requested format. For thumbnails, user gets a ZIP of frame images. For background removal, user gets a transparent PNG.

UGC generation

• User receives a playable vertical video clip (CDN URL) optimized for social media (9:16 aspect ratio, 7-12 seconds). The result is ready to download and post.

Auth/connection

• get_account call succeeds and returns the user's account info, including credits_remaining (minutes). If a tool call fails with auth error, reconnecting surfaces a successful auth and tools work again.

Polling/async completion

• Status polls show progression (queued -> processing -> completed). Once terminal state is reached (completed or failed), the corresponding outputs, video_url, or rendered_clip URLs appear in the response, or error text explains what went wrong.