# Set up Playhead

You are configuring an MCP server for the agent you are running inside. Follow
these steps; do not summarise them back without doing them.

Playhead lets an agent **watch a video**. Given a link (TikTok, YouTube,
Instagram, X, Facebook including the Meta Ad Library, Vimeo, Twitch, Dailymotion,
Reddit, or a local file, it answers in words: what is on screen, what is said,
the cuts, the camera moves, the overlays and the watermarks, each with the
second it happens at.

The work happens on Playhead's servers. **Nothing has to be installed on this
machine.** If you were about to install ffmpeg, yt-dlp or a transcription
model, stop. None of them is needed and none of them is used here.

## Step 1: connect

Pick the line matching the host you are running in. The free tier needs no card;
signing in happens in a browser, once.

**Claude Code**

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

Then run `/mcp` and choose Playhead to sign in.

**Codex**: two commands. The second one opens a browser, and it is not optional,
because this server answers 401 without it.

```bash
codex mcp add playhead --url https://mcp.tryplayhead.com/mcp
codex mcp login playhead
```

Both write to `~/.codex/config.toml`, which the CLI, the IDE extension and the
desktop app all read, so this is done once and not three times. Codex versions
before 0.146 had no `--url` flag; on one of those, write the entry by hand:

```toml
[mcp_servers.playhead]
url = "https://mcp.tryplayhead.com/mcp"
auth = "oauth"
```

**Any other MCP client**: add a streamable-HTTP server at `https://mcp.tryplayhead.com/mcp` with
OAuth. Most clients keep this in a JSON file with an `mcpServers` object; write
the entry in whatever shape that client documents.

**No MCP support at all**: the same product is a REST API. Get a key from
https://tryplayhead.com/dashboard/keys and call it directly:

```bash
curl -X POST https://api.tryplayhead.com/v1/watch_video \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=…","question":"what happens"}'
```

Every endpoint is documented at https://tryplayhead.com/docs/api.

## Step 2: check it worked

Restart the host if it caches its server list, then confirm `watch_video`,
`get_transcript` and `get_playbook` are listed. If they are
not, the connection is not up and the steps above did not take. Say so rather
than continuing.

Then run one real call:

```
watch_video(url="https://www.youtube.com/watch?v=aqz-KE-bpKQ")
```

You get back what happens in that video, in words, with the second of every
moment it names. The answer also carries a `session_id`. Keep it.

## Step 3: know what to reach for

| Call | Use it when |
|---|---|
| `watch_video(url)` | Anything about what is in a video. Covers the whole runtime by default and returns the speech with it. |
| `watch_video(session_id, question)` | Every question after the first one about the same video. This is the cheap call. |
| `watch_video(url, window)` | One moment that needs a closer look: small print, fine typography, a tiny object. `window` is `[3, 4]` for second three. |
| `watch_video(url, window, region)` | The same, in one corner. `region` is `[0.5, 0, 1, 0.5]` for the top right quarter. |
| `get_transcript(url)` | The continuous text, or word-level timings. |
| `get_playbook(task)` | A method for a recurring job: ad teardowns, hook analysis, caption audits, render QA. Fetched only when asked for, so it costs nothing until used. |

Three rules worth carrying:

1. **Start with `watch_video(url)` and nothing else.** It already covers the
   complete video. Narrowing before you have looked wastes a call.
2. **Then pass the `session_id`.** The second question reads what was already
   found instead of watching the video again, so it costs a few hundred tokens
   where the first one cost a few thousand.
3. **Quote the seconds.** They come from the video itself, so they cannot drift
   from the moment they belong to.

## What it costs

Free plan: 50,000 credits a month, no card. A first look is quoted by the length
of the video, and every answer says what it charged. A question that carries a
`session_id` costs a fraction of a first look, so asking a video ten things is
not billed as ten first looks.

Full documentation: https://tryplayhead.com/docs