Playhead documentation

The MCP server and the SDK both call the REST API, so nothing is available through one and missing from another. Start where your work already is.

claude mcp add --transport http playhead https://mcp.tryplayhead.com/mcp

• The answer is words, with the second on it. Every claim carries the second it is about, and the times come from the video itself, so they cannot drift from the moment they belong to.
• Coverage, stated. Ask nothing and the whole video is covered, second zero to the end. What the question asked for and the video does not show is named rather than guessed at.
• Cuts, transitions, freezes, black frames and silence as measured numbers, so a pacing figure is counted rather than estimated.
• A transcript with word-level timings, and an assessment of whether the audio was speech at all.
• No verdicts you did not ask for. Nothing is called “a hook” or “a strong opening” on its own. Ask for that and you get it, with the second it is about, so you can check it.

The first band is also the floor, so a short advert is quoted the same 1,100 credits as a full minute. You can read the quote before you call, and every answer says what it actually charged. Pricing has the rate in dollars, and Sessions covers why a follow-up costs a fraction of this.

• Quickstart→Connect Playhead to your agent, or make one API call with curl or the SDK. A free account starts with 50,000 credits and needs no card.
• Connect your agent→One-click connect buttons for Claude, Claude Code, ChatGPT, Codex, Cursor and VS Code. There is no API key to paste: you sign in instead.
• MCP server→watch_video, watch_videos, run_playtool, get_transcript, attach_stream and more. What each one returns, when to reach for it, and what it costs.
• Sessions→Every answer carries a session_id. Pass it with the next question about the same video and that question reads what was already found.
• Sources and formats→YouTube, TikTok, Instagram, X, Facebook and Meta Ad Library, Vimeo, Twitch, Dailymotion, Reddit, any other site, plus production formats like MXF and ProRes.
• Playbooks→Seven worked methods: ad teardowns, hook analysis, caption audits, accessibility passes, brand checks, render QA and turning a recording into an SOP.
• Examples→Worked examples: finding every cut, reading on-screen text, auditing an ad, checking a render, aligning a transcript to frames.
• TypeScript SDK→A typed Node client for the Playhead API: ask, transcript, batches, uploads, jobs and credits, with typed errors that carry the call that would have worked.
• REST API→Every endpoint: POST /v1/watch_video, /v1/batches, /v1/transcript, /v1/uploads, GET /v1/jobs, /v1/credits and DELETE /v1/videos.
• Authentication→Bearer API keys for your own code, OAuth 2.1 for connected agents. A key is shown once, so a lost key is replaced rather than recovered.
• Pricing→One flat rate per 1,000 credits. What a first look costs, why the second question is cheap, and how to ask about many videos at once.
• Errors→Every error type, what causes it, and which ones carry a suggestion object holding the exact call to send instead.
• Compare→How a hosted MCP server differs from an Agent Skill that needs a video toolchain and a transcription key on the machine you are sitting at.

Can an AI agent watch a video?

Not on its own. A language model cannot open a video file, so asked about one it answers from the title, the description or the transcript. Connect Playhead as an MCP server and your agent gets tools that read the video itself, with the second on every moment they name.

Does this work on a phone?

Yes. Playhead runs on our servers rather than on your device, so nothing has to be installed. Add it once and the same connection works in the browser, the desktop app and the mobile apps. A local script cannot do this, because there is nowhere on a phone for one to run.

Which platforms are supported?

YouTube, TikTok, Instagram, X, Facebook including the Meta Ad Library, Vimeo, Twitch, Dailymotion and Reddit are supported by name. Any other page or direct media URL is attempted as well, and you can upload your own files, including production formats such as MXF and ProRes.

Can it detect cuts and transitions?

Yes. Cut times come back as a list of seconds with a pacing summary, and transitions are named separately: dissolves, fades, dips, wipes, pushes, slides, zooms and doorways. That separation matters, because a dissolve counted as a cut makes an edited video's pacing read faster than it is.

Does it transcribe the audio?

Yes, with word-level timings when you ask for them. The uploader's own captions are used when they exist, because a person typed the names. Every transcript also says whether the audio was speech at all, so music over a video is not handed back to you as dialogue.

Do I have to install anything?

No. Nothing runs on the machine you are sitting at. Playhead fetches the video, reads it and makes the transcript on its own servers. That is the difference from the local scripts and Agent Skills that do something similar: those need a working toolchain on your own machine.

Is there an API and an SDK?

Yes. There is a REST API at api.tryplayhead.com and a typed TypeScript client published as @playhead/sdk. Both do the same work, so pick whichever fits the language you are writing in.

What does it cost?

A free account gets 50,000 credits a month and needs no card. A first look is quoted by the length of the video, and every answer says what it charged. A second question about the same video costs a fraction of the first, because it reads what that look already found.