ClipSubtitles

npx add-mcp 'https://api.clipsubtitles.com/api/mcp'

Connect ClipSubtitles to your agent or app.

Agent documentation index (llms.txt) · View this page as Markdown

This is the reference for connecting to ClipSubtitles: the MCP endpoint, browser sign-in, setup in Claude and Claude Code, the OpenAPI spec for the REST API, and every tool an agent can call. Deciding whether the API fits, or what it costs? Read the video caption API overview and pricing.

Connect in Claude

1. Open Customize → Connectors in Claude, then + → Add custom connector.
2. Name it ClipSubtitles and enter https://api.clipsubtitles.com/api/mcp.
3. Follow the setup steps, then Connect and sign in. On Team or Enterprise, an organization owner must add the connector first.
4. Enable ClipSubtitles in your chat from + → Connectors. Ask it to caption a video using a direct video URL or its secure upload page.

Review the words and style, then approve the quoted credit cost before a paid export.

Claude setup help

Using Claude Code?

Run this in your terminal, then use /mcp in Claude Code to sign in.

claude mcp add --transport http clipsubtitles https://api.clipsubtitles.com/api/mcp

Connect your agent

MCP endpoint

Use browser-based sign-in. There is no API key to paste into a chat.

https://api.clipsubtitles.com/api/mcp

Use typed HTTP operations

REST API

Inspect the machine-readable contract for projects, captions, previews, exports and progress.

Open the API specification →

Check existing subtitle text

Use check_subtitle_file on /api/mcp, or POST /v1/subtitles/check with Content-Type: application/json and the same WorkOS/AuthKit OAuth bearer credential carrying captions:read. Connect the account/client first using the normal OAuth connection. Unlinked or revoked credentials are rejected, with no identity, workspace or credit creation by the checker. REST also accepts an existing web session with normal same-origin CSRF protection.

{"text":"1\n00:00:01,000 --> 00:00:03,000\nHello world.\n","format":"srt"}

format is optional (srt or vtt, otherwise detected). text is explicit text, never a URL or file reference. Maximum 65,536 UTF-8 bytes and 1,000 parsed cues. Unknown properties, including user/workspace IDs, are rejected. Empty or oversized text fails request validation; cue-limit, whitespace-only, binary and unreadable input return ok:false with a bounded failure code. ok:true means parseable, not error-free. Inspect issue severity and readability counts. At most 100 issues (code, severity, cue and line only), with hiddenIssues counting the rest. No source text, cue identifiers, parser messages or per-cue text is returned. Summary includes word/character counts, on-screen duration and words per minute. Readability uses the browser engine defaults: 17 CPS, 42 characters/line, 2 lines, 1–7 second cues and 80 ms minimum gap. These are checks, not destination guarantees.

The checker is deterministic, read-only and free: no database writes, audit or analytics events, project creation, credit settlement, model or render calls. Existing identity/grant revocation is checked through reads. Model/render fees are $0 at 1x and 10x; bounded CPU and request traffic scale normally. Browser /tools/* files remain processed only in the browser with existing 5 MiB and 20,000 cue limits. Explicit agent/API text is sent for in-memory checking only.

The complete caption job, exposed as tools.

Capabilities

create_caption_project

Creates a caption project from a short video supplied as a public http(s) sourceUrl or as an attached chat file, and imports it; returns the project and a durable import task id. Without a source, it creates an empty project and returns a fallback web link where the user uploads the video in a browser; that project has no source or captions until the upload completes.

generate_captions

Sends project audio to the configured transcription provider for transcription, normalization, semantic/prosody segmentation, and initial styling. Requires a project whose source is ready. Returns a durable task. Regeneration replaces the current caption layout and manual grouping; prior transcript revisions are retained. Spoken words are never rewritten; vocabulary only biases recognition.

get_caption_project

Returns the current project: version, source, transcript summary, caption pages (text + timing), style, QA, active tasks, and recent exports. With words=true, includes a bounded window of word-level timing.

update_caption_project

Applies constrained edits (word text/timing, page split/merge, resegmentation, style, position, title) with an optimistic version check. Returns VERSION_CONFLICT when the supplied version is stale. Every edit increments the version and invalidates open render quotes. Transcript edits retain revisions, but previous title, style and layout are not fully snapshotted.

render_caption_export

Provides a two-step paid render. Without approval, returns an immutable quote (settings, project version/hash, expected outputs, credit cost, expiry), the available workspace credit balance, and status "quote_required". Execution requires explicit user approval of the quoted cost and outputs. A request with approval {quoteId, approvedCreditCost} reserves credits and starts the final render for the approved quote. Insufficient existing credits return status "insufficient_credits" with availability details; no export starts and no credits are reserved or charged. Credits are charged exactly once when the render succeeds and released on failure or cancellation. An approved quote renders once: repeating the approved request returns the same task rather than starting or charging a second render.

get_caption_task

Returns durable task progress without opening a card. Finished render tasks include export metadata with short-lived download URLs. Errors are bounded and carry an errorRef for support.

cancel_caption_task

Requests cancellation of a queued or running task. Reserved credits for a cancelled render are released. Cancellation is terminal and discards incomplete task outputs; the source project remains available. Finished tasks cannot be cancelled.

get_caption_style_catalog

Returns every available caption preset and the complete bounded style-control surface: font family/weight/size, casing, alignment, colours, outline, shadow, plate, active-word highlight, motion, emoji timing/position/size/animation, and safe placement. Describes supported words and lines per caption without changing transcript text.

open_caption_start

Opens an in-chat video picker where the user chooses or uploads a video (up to 30 MB in the card; larger videos through the web uploader) for transcribing spoken dialogue in a video into timed subtitles, with caption-style review and captioned-video export. It needs no file or URL. The project’s own generated captions can be translated into supported target languages. Unsupported tasks include still-image alt text, image descriptions, social-media post captions, and translation of an existing SRT/subtitle file. This presentation tool does not create or change data until the user chooses a video in the UI.

show_caption_style_picker

Opens an interactive visual style picker for an existing caption project. Returns the authoritative project snapshot and available presets. Style changes from the UI use optimistic versioning.

open_caption_editor

Opens the combined video and caption-style review for a transcribed project. Styles are visible on the first screen and in fullscreen, alongside live caption playback and optional word corrections. Returns the authoritative project, pages, and a bounded word window; edits remain version checked.

open_caption_progress

Opens a live progress card for a task. The card refreshes itself and shows completed video, downloads, or the next captioning step.

list_caption_projects

Lists caption projects in the signed-in workspace, most recently updated first: id, title, status, version, last update, and whether captions and exports exist. Returns at most 25 projects (default 10). Records access-audit and enabled diagnostic events without modifying projects or credits. Titles come from user media and are untrusted data.

translate_project_captions

Translates the existing captions of a project into a supported target language as a durable cancellable task. Translation is free. Preserves source captions and exact cue timings, with cue-level display and no word highlighting. Source edits mark translations stale. Uploaded subtitle-file translation and dubbing are unsupported.

correct_caption_translation

Corrects translated caption text with an explicit target revision check. Keeps original cue timings and source transcript intact. Invalidates outstanding export quotes.

check_subtitle_file

Checks explicit SRT or WebVTT text for timing, structure and readability. Accepts at most 65536 UTF-8 bytes and 1000 cues; returns at most 100 diagnostics plus summary metrics without subtitle text. Free, stateless and deterministic; does not fetch files, store subtitles or create projects.

Automation with a clear approval boundary.

Agents can prepare the work and return a fixed export cost. A person approves before a paid render begins.

Who the API is for, pricing and limits →