What is an MCP server?

Model Context Protocol is a standard for giving an AI agent tools it can call. An MCP server publishes a set of tools with typed arguments; the agent decides when to call them from the question it was asked. Playhead publishes five.

Why do only two contact sheets come back at a time?

An MCP client caps a single tool result — Claude's ceiling is 1 MB — and a result over the cap is dropped whole rather than truncated. One sheet is around 370 KB of base64, so two per call is the physical ceiling. Everything beyond comes back as a link plus the exact follow-up call, which costs no context.

How does the agent decide which detail level to use?

From the question. Surveying a long video and reading one frame of animation are different jobs, so the tool description tells it to start at standard, use overview for anything long, and raise the level only when a question demands it — on a short window.

Can I run the MCP server myself?

Yes. npx -y @playhead/mcp runs it over stdio against our API, and --http --port=8787 runs the HTTP transport. Both still call the hosted engine, so an API key or an OAuth token is still what pays for the work.

The MCP server

The MCP server gives an agent five tools. watch_video is the one it reaches for by default and covers the complete video unless a window is given; the other four exist for the cases where that is the wrong shape — reading text, reading words, checking a balance, or looking up a method.

Last updated 6 August 2026

The five tools

An agent picks between them from the question it was asked. Two of them touch no video at all, and cost nothing.

MCP tools at a glance
Tool	Returns	Cost
`watch_video`	Contact sheets as images, each preceded by its timestamp anchor, plus what was covered, what the detectors measured, and the exact next call.	About 18k tokens of context for a full result. Roughly one credit per minute of video at standard.
`inspect_frame`	One frame at 1560 px on its long edge.	One flat credit. About 1.6k vision tokens.
`get_transcript`	Plain text, optionally with word-level timings, plus whether the audio was speech at all.	No image tokens at all. The cheapest call there is.
`get_account`	Which plan is connected, credits left, and what recent calls cost.	Nothing. No video is touched.
`get_playbook`	A method for one recurring job: the call order, what is measurable, and where judgement belongs.	Nothing. No video is touched.

`watch_video(url, start?, end?, detail?, language?)`

The default, and the right answer to almost any question about what is on screen. Without start and end it covers the complete video.

urlstring: A platform link, any other page with a video on it, or a path to a local file when running over stdio.
startnumber: Window start in seconds. Omit for the whole video.
endnumber: Window end in seconds. Omit for the whole video.
detailenum: overview, standard (default), detail, fine, motion or single. Raise it only when the question demands it.
languagestring: Force a language. Set it when the audio is mostly music, crowd or engine noise — detection misfires there.

`inspect_frame(url, t)`

Reading small text, judging a typeface, checking a logo. Even a motion tile is too small for that.

urlstring: The same source as watch_video.
tnumber: The exact second to look at.

`get_transcript(url, words?, language?)`

The question is about what is said rather than what is shown.

urlstring: The same source as watch_video.
wordsboolean: Include word-level timestamps.
languagestring: Force a language. auto detects.

`get_account(history?, limit?)`

Before an expensive pass over something long, or when a call was refused for want of credit.

historyboolean: Include recent jobs and what they cost.
limitnumber: How many recent jobs to list. Default 10.

`get_playbook(task, section?)`

A job with a known shape — an ad teardown, a caption audit, a render QA pass — rather than a one-off question.

taskenum: Which playbook.
sectionstring: One section of it, fetched only when asked for.

How much comes back at once

This is a property of MCP clients rather than of Playhead, and it is the single most common surprise when building on the server.

An MCP client caps one tool result — Claude's ceiling is 1 MB, and a result over it is dropped whole rather than truncated. One contact sheet is around 370 KB of base64, so two sheets per call is the physical ceiling whatever detail level you pick. Everything beyond that comes back as a link plus the exact follow-up call, which costs no context.

The practical consequence: a 50-second video at standard is nine sheets, so an agent walking all of it makes five calls. For a first pass over anything long, overview is the right level — it packs 60 seconds of video into one sheet instead of six.

Detail levels covers the arithmetic behind that in full.

Running it yourself

The npm package is MIT. It is a client of the hosted API, so a key or a token still pays for the work.

Remote HTTP transport — the default, and what the connect buttons usebash

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

stdio, which additionally allows local file pathsbash

npx -y @playhead/mcp
# or, with Claude Code:
claude mcp add playhead -e PLAYHEAD_API_KEY=sk_live_… -- npx -y @playhead/mcp

claude_desktop_config.jsonjson

{
  "mcpServers": {
    "playhead": {
      "command": "npx",
      "args": ["-y", "@playhead/mcp"],
      "env": {
        "PLAYHEAD_API_URL": "https://api.tryplayhead.com",
        "PLAYHEAD_API_KEY": "sk_live_…"
      }
    }
  }
}

Configuration

Environment variables read by the npm package. CLI flags --api-url, --api-key, --http and --port override them.

Environment variables for @playhead/mcp
Variable	Default	Purpose
`PLAYHEAD_API_URL`	`https://api.tryplayhead.com`	REST API base URL.
`PLAYHEAD_API_KEY`	—	sk_live_…. On the remote transport the client's own bearer token wins.
`PLAYHEAD_MCP_CACHE_DIR`	`~/.cache/playhead`	Disk cache, 7 days. A second look at the same window is free.
`PLAYHEAD_MCP_IMAGE_DELIVERY`	`auto`	auto, same-turn or next-turn — guards a one-turn image delay in some clients.
`MCP_TRANSPORT`	`stdio`	stdio or http.
`PLAYHEAD_MCP_REQUIRE_AUTH`	`false`	Reject unauthenticated remote calls.
`PLAYHEAD_MCP_MAX_RESULT_BYTES`	`950000`	Byte budget for one tool result. Too low costs coverage; above the client's real cap costs the whole result.

Questions

What is an MCP server?: Model Context Protocol is a standard for giving an AI agent tools it can call. An MCP server publishes a set of tools with typed arguments; the agent decides when to call them from the question it was asked. Playhead publishes five.
Why do only two contact sheets come back at a time?: An MCP client caps a single tool result — Claude's ceiling is 1 MB — and a result over the cap is dropped whole rather than truncated. One sheet is around 370 KB of base64, so two per call is the physical ceiling. Everything beyond comes back as a link plus the exact follow-up call, which costs no context.
How does the agent decide which detail level to use?: From the question. Surveying a long video and reading one frame of animation are different jobs, so the tool description tells it to start at standard, use overview for anything long, and raise the level only when a question demands it — on a short window.
Can I run the MCP server myself?: Yes. npx -y @playhead/mcp runs it over stdio against our API, and --http --port=8787 runs the HTTP transport. Both still call the hosted engine, so an API key or an OAuth token is still what pays for the work.