Documentation

The Capso > MCP server.17 tools. Your videos, editable by agents.

One Streamable-HTTP endpoint that lets Claude Code, Codex, Cursor, VS Code — any MCP client — read, edit, and publish your recordings. Every edit is a non-destructive overlay, identical to what the web editor writes.

endpoint https://app.getcapso.com/api/mcp/mcp

Overview

The Capso MCP server exposes the video editor to AI agents over the Model Context Protocol (Streamable HTTP). Agents work with the same normalized data the editor uses — blur regions, annotations, zoom keyframes, CTAs, captions, chapters — rendered at playback with nothing re-encoded. An open editor tab picks up agent edits automatically.

Trimming, cutting, and exporting are not available through this API — they run in the browser editor. Everything else about a recording is agent-editable.

Authentication

Every request carries an API key as a bearer token: Authorization: Bearer capso_sk_…. Create keys in Settings → Account → API Keys (Pro plan and up — Pro 3 keys, Team 10, Enterprise 25). The secret is shown once at creation; revoking a key takes effect on its next request.

Keys carry scopes chosen at creation:

recordings:read — list and read videos, transcripts, analytics
recordings:write — edit overlays, settings, captions, chapters; create share links
ai:run — transcription and credit-consuming AI operations

Connect a client

Copy-paste setup for Claude Code, Codex, Cursor, and VS Code lives on the > Agents page. The short version for Claude Code:

claude mcp add \
  --scope user \
  --transport http \
  --header "Authorization: Bearer capso_sk_..." \
  capso https://app.getcapso.com/api/mcp/mcp

Conventions

Units. Coordinates (x, y, width, height, targetX/Y, positionX/Y) are percentages of the video frame, 0–100, origin top-left. All times are seconds.
Batch-first. The manage_* tools take an action plus an array of up to 50 items. update and delete require each item’s id — get ids from get_recording.
Verify from the response. Every write returns the full post-write state of that resource plus the video duration — no second read needed.
Self-correcting errors. Validation errors state the violated constraint with real values (e.g. endTime 95s exceeds the video duration of 62.4s) so an agent can fix its call. Plan-gate and credit errors are terminal — report them, don’t retry.
Prefer free paths. Chapters and captions can be derived from get_transcript at no cost; run_ai spends the user’s monthly credits.

Discovery

Read before you write — every edit starts with the recording’s full context.

> list_recordings

recordings:read

List the user’s recordings (own videos plus workspace-visible ones), newest first.

Parameter	Type	Description
search	string?	Filter by title (case-insensitive substring, ≤200 chars)
limit	int?	Page size 1–50, default 20
cursor	string?	Previous response’s nextCursor for the next page

Returnsrecordings[] — id, title, durationSeconds, status (READY = editable), visibility, createdAt, hasTranscript — plus nextCursor.

> get_recording

recordings:read

Everything needed to plan an edit in one call. Always call this before editing.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings

ReturnsMetadata, durationSeconds, canvas & branding settings, chapters, caption style, ALL overlays with ids (blur regions, annotations, zoom keyframes, CTAs, scenes), active share links, and background-job statuses.

> get_transcript

recordings:read

Read the transcript — use segments to locate moments for chapters, blurs, or CTAs.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings
format	'text' \| 'segments'	Default segments — timed [{start, end, text}] in seconds

Returnslanguage plus the plain text or the timed segments array.

NoteIf no transcript exists yet, run generate_transcript first.

> get_job_status

recordings:read

Poll background jobs (e.g. after generate_transcript). Poll every ~5s until COMPLETED.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings
jobType	string?	Filter to one type, e.g. "transcribe"

Returnsjobs[] — type, status (PENDING | PROCESSING | COMPLETED | FAILED), attempts, lastError, timestamps.

Overlay editing

Batch-first tools — one call applies up to 50 items. action "add" creates every item; "update" and "delete" require each item’s id (from get_recording). Every call returns the full post-write list plus the video duration so you can verify without a second round-trip.

> manage_blur_regions

recordings:write

Privacy blurs, rendered non-destructively at playback.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings
action	'add' \| 'update' \| 'delete'	Batch action
regions[]	object[] (1–50)	id? · x, y, width, height (% of frame) · startTime, endTime (s) · blurAmount 1–100 (default 20) · blurType blur \| mosaic \| blackbar

Returnsduration + the full blurRegions list.

NoteUse blackbar for credentials and secrets — screen-text blur can be reversible.

> manage_annotations

recordings:write

Visual annotations shown during playback.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings
action	'add' \| 'update' \| 'delete'	Batch action
annotations[]	object[] (1–50)	id? · type pen \| highlighter \| arrow \| rectangle \| text \| spotlight · timestamp (s) · duration (s, default 3) · color (CSS) · strokeWidth 1–40 · opacity 0–1 · text ≤2000 · points [{x, y}] %

Returnsduration + the full annotations list.

Notepoints for arrow = [from, to]; for rectangle = [topLeft, bottomRight].

> manage_zoom_keyframes

recordings:write

Smooth pan/zoom moments. Adding any keyframe auto-enables zoom playback.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings
action	'add' \| 'update' \| 'delete'	Batch action
keyframes[]	object[] (1–50)	id? · timestamp (s) · targetX, targetY (% focal point) · zoomLevel 1–5 (default 2) · duration 0.1–10s transition (default 0.6) · holdDuration 0–120s (default 1.5) · easing linear \| easeIn \| easeOut \| easeInOut

Returnsduration + the full zoomKeyframes list.

NoteKeep holds 1.5–3s and keyframes ≥4s apart — the camera needs time to travel and return.

> manage_cta_overlays

recordings:write

Interactive call-to-action docks at the bottom of the player. Playback pauses the first time each CTA appears.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings
action	'add' \| 'update' \| 'delete'	Batch action
overlays[]	object[] (1–50)	id? · type (snake_case: button, email_gate, banner, form, poll, quiz, rating, nps_score, pricing_card, scheduler, contact_card, chapter_nav, …) · timestamp (s) · duration 1–3600s (default 5) · title ≤200 (required on add) · description ≤1000 · buttonText ≤100 · buttonUrl https · collectEmail · isActive

Returnsduration + the full ctaOverlays list.

Noteemail_gate requires Pro or higher. Email submissions automatically become CRM contacts.

> manage_scenes

recordings:write

Edit or remove detected scenes. Scenes are created by run_ai scene_detection — this tool never creates.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings
action	'update' \| 'delete'	Batch action
scenes[]	object[] (1–50)	id (required) · title ≤200 · transition crossfade \| slide \| fade \| cut \| zoom

Returnsduration + the full scenes list.

Recording settings

Metadata, canvas appearance, and branding. Send only the fields that change.

> update_recording

recordings:write

Update metadata, playback, lead capture, and the canvas backdrop.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings
title / description	string?	≤500 / ≤5000 chars
visibility	'PRIVATE' \| 'WORKSPACE' \| 'PUBLIC'	Who can view
zoomEnabled	boolean?	Toggle zoom-keyframe playback
requireEmail	boolean?	Email gate (Pro+)
emailGateTimestamp	number? \| null	Gate moment in seconds; null = gate before playback
canvas*	various?	canvasEnabled · canvasBackground gradient \| solid \| blur · canvasColor (hex) · canvasGradient (CSS) · canvasPadding 0–20 · canvasCornerRadius 0–40 · canvasDeviceFrame none \| browser \| mac-window · canvasShadow

ReturnsThe updated full recording context.

> update_branding

recordings:write

Workspace logo overlay on the video (Pro or higher).

Parameter	Type	Description
recordingId	string	Recording id from list_recordings
enabled	boolean?	Show or hide the logo
positionX / positionY	number?	% of frame, 0–100, origin top-left
opacity	number?	0–1
scale	number?	0.5–2

ReturnsThe updated branding settings.

Captions & chapters

Wholesale writes — derive both from the transcript for free before spending AI credits.

> set_captions

recordings:write

Write the caption track and/or styling. captions is the FULL replacement track.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings
captions[]	object[]? (≤2000)	{start, end, text ≤500} in seconds — keep lines under ~7 words
style	string?	minimal \| bold \| colorful \| karaoke \| neon \| typewriter \| cinema \| pop \| outline \| glass
color / font	string?	Hex color, font family
size	'sm' \| 'md' \| 'lg'	Caption size
position	'top' \| 'center' \| 'bottom'	Caption position

ReturnsThe stored caption style.

NoteStyled captions require Pro or higher.

> set_chapters

recordings:write

Write chapter markers (progress bar + navigation list). Free — no AI credits.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings
mode	'replace' \| 'append'	Default replace — swaps the whole list
chapters[]	object[] (1–100)	{title 1–200 chars, timestamp seconds}

Returnsduration + the full post-write chapter list.

NoteAim for 3–8 chapters with short descriptive titles; first chapter at 0.

AI operations

Run Capso’s AI features. Costs come from the user’s monthly credit budget — errors state when credits or plan tier are missing; don’t retry those.

> generate_transcript

ai:run

Enqueue transcription as a background job. Free — 0 credits. No-op if a transcript exists.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings

ReturnsENQUEUED (poll get_job_status, jobType "transcribe") or ALREADY_EXISTS.

> run_ai

ai:run

Synchronous credit-consuming operations. Most require Pro+ and a transcript.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings
operation	enum	summary (1 credit) · chapters (1) · captions (2) · auto_edit_analysis (3) · filler_analysis (2) · scene_detection (2)
options	object?	For captions: {language: BCP-47, style: caption style name}

ReturnsThe operation result plus credits used and remaining.

Noteauto_edit_analysis produces cut metadata only — actual trimming happens in the browser editor, not through this API.

Publishing & analytics

Ship the video, then measure it.

> create_share_link

recordings:write

Create a share link and get its full URL — the shareable artifact.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings
password	string?	8–100 chars (Pro+)
expiresInDays	int?	1–365 (Pro+)
maxViews	int?	View cap ≥1
requireEmail	boolean?	Email gate (Pro+) — captures become CRM contacts
emailGateTimestamp	number?	Seconds into the video; omit to gate before playback
emailGateMessage	string?	≤500 chars shown on the gate

Returnsid, slug, url, gating settings, passwordProtected.

> get_analytics

recordings:read

Aggregated engagement — use it to report performance or find where viewers drop off.

Parameter	Type	Description
recordingId	string	Recording id from list_recordings

ReturnsViews, unique viewers, completion, top drop-off points (seconds), device breakdown, CTA responses, email captures.

Rate limits & errors

120 tool calls / minute per API key. On 429-style errors, wait and retry.
AI budget is shared. run_ai uses the same per-user AI rate limit (20/hour) and monthly credit budget as the web app.
Auth failures — invalid, revoked, or expired keys are rejected per request; a payment-locked workspace rejects with a billing message.
Tool errors, not protocol errors. Failures come back as readable tool results so the agent can adjust — missing scopes name the scope to add.

Example workflows

> Blur the API key at 0:42 in my latest demo, then chapter it.

list_recordings → get_recording → manage_blur_regions (blackbar) → get_transcript → set_chapters

> Gate my onboarding video behind an email at 30 seconds and send me the link.

get_recording → create_share_link {requireEmail, emailGateTimestamp: 30} → returns URL

> How did last week’s pricing walkthrough perform? Tighten where people drop off.

get_analytics → get_transcript → manage_zoom_keyframes / set_chapters at the drop-off points

> capso-video-editing skill

A Claude Code skill that teaches these workflows — blur-PII recipes, chaptering, lead capture, polish-for-sharing — plus screen-zone heuristics for placing blurs and zooms, and a guide to every CTA type.

Download skill

install unzip capso-video-editing-skill.zip -d ~/.claude/skills/