← All guides

A YouTube MCP server for AI agents

Written by the VidWords Team · August 18, 2026 · Updated August 18, 2026 · Report a correction

Your assistant cannot watch a video. Point it at an MCP server and it can read one — and cite the exact moment it got the answer from.

The short answer

• One endpoint. POST https://vidwords.com/mcp is a hosted Model Context Protocol server. Point Claude, Claude Code or Cursor at it and the assistant gains nine tools for reading YouTube videos — no integration code, no scraping, no proxy pool.
• One header for auth. Authorization: Basic <your-api-token> — the same token as the REST API, spending the same credits under the same plan limits. Free accounts get one too.
• The flagship tool is search_transcript, not get_transcript. Both cost the same. Search returns only the moments that answer the question, each with a clickable timestamp; a full transcript of a two-hour video mostly fills the context window with material nobody asked about.
• It reads the picture, not only the captions. analyze_video looks at slides, charts and demos, and ask_video drops any citation it cannot match to a recorded frame or a real transcript segment.

Works with

Anything that speaks MCP over Streamable HTTP and can send a custom header. The first three have a full walkthrough; Codex is configured further down.

Logos are simplified marks for identification only; each product belongs to its own vendor and none of them endorse VidWords.

Why "a transcript" is the wrong unit to hand an agent

A language model cannot watch a video. That single limitation is why every "paste a YouTube link into ChatGPT" workflow disappoints — the model receives a URL, not the thing the URL points at.

The obvious fix is to give it the transcript. That works, and it is what most transcript APIs sell. But it quietly creates a second problem: a transcript is a wall of undifferentiated text with no addresses in it. An assistant handed 18,000 words can summarise them, but when you ask "where did they say that?" it has nothing to point at, so it either guesses a timestamp or hedges.

The useful unit for an agent is not a transcript. It is a grounded, linkable answer about a video — a claim with a timestamp attached that the person reading it can click and check in one second. That is what this server is built to return, and it is why search_transcript is the flagship tool rather than a convenience wrapper around get_transcript.

The endpoint

The whole configuration is a URL and a header:

POST https://vidwords.com/mcp
Authorization: Basic <your-api-token>

Get a token by creating a free account and copying it from your profile. Two things trip people up on the first call:

• Verify your email first. Until you click the verification link, every call returns 403 with {"error":"email_unverified"}. This is the single most common first-call failure on a new account.
• It is Basic, not Bearer. The token is used as-is; you do not base64-encode a user:pass pair yourself.

The nine tools

The one habit worth forming: prefer search_transcript

Both transcript tools cost one credit per video, so there is no billing reason to choose. The reason is context. Ask an assistant "what did this two-hour interview say about pricing?" and get_transcript returns roughly 20,000 words, of which perhaps 300 are about pricing. Those 300 words now compete for attention with 19,700 words that are not, and the answer gets worse, slower and more expensive to generate.

search_transcript returns the matching stretches with the surrounding context and a deep link per match. The assistant answers from the relevant material and hands you a timestamp you can click. Reach for get_transcript when you genuinely want the whole text — an export, a diff, a corpus — not when you have a question.

What it reads that a transcript API does not

Everything above operates on captions, which is where most YouTube tooling stops. Three of the nine tools do something different: they read the video's frames.

analyze_video starts a frame-level analysis — slides, charts, code samples, product demos, on-screen text that is never spoken aloud. Analysis takes minutes, so the tool returns an analysisId at once and get_analysis polls it. A video that has been analysed before comes back ready immediately rather than being charged twice.

ask_video then answers questions against that stored analysis, and this is the part worth understanding before you trust it. Every citation is checked before you see it: a visual claim has to match a frame that was actually recorded, and a spoken claim has to land on a real transcript segment. Anything that fails the check is dropped. When nothing survives, the answer says the evidence is insufficient instead of producing a confident guess.

That behaviour is deliberate and it is occasionally annoying — a refusal is a worse demo than a fluent answer. It is also the only version of this feature that is safe to put in front of an agent, because an agent will repeat whatever it is told without the scepticism a human reader applies. If you want to see the output before wiring anything up, the demo page is one real, unedited analysis of Apple's 76-minute WWDC 2026 keynote, published exactly as the tool produced it.

What it costs

Credits are the same pool the REST API and the website draw on — one credit is one transcript. The free plan includes monthly credits and 10 Watch minutes, so you can wire the server up and use it before paying anything. Frame analysis draws Watch minutes rather than credits, and a run that is refused before it starts costs nothing at all.

account exists so an agent can check the balance and tell you what a batch will cost before it starts, rather than failing halfway through a 200-video job. It is free to call; a well-behaved agent calls it first. Full numbers are on the pricing page.

Rate limits

30 requests per 10 seconds — deliberately looser than the REST API's 5. The reason is that an MCP request is not an MCP operation: the server is stateless, so a client re-runs initialize before every call, and a single agent turn routinely spends three or more requests (initialize → tools/list → tools/call) to do one unit of work. At the REST budget a normal conversation would start returning 429s on its second question.

analyze_video carries its own tighter ceiling of 10 starts per minute, shared with the REST route so you cannot double your budget by alternating transports.

Set it up in your client

Three walkthroughs, each with the exact config and how to confirm the tools actually loaded:

• Claude Code — one claude mcp add command.
• Claude Desktop — a block in claude_desktop_config.json.
• Cursor — a block in .cursor/mcp.json.
• Codex CLI — a block in ~/.codex/config.toml, below.

Codex CLI

Codex configures MCP servers in ~/.codex/config.toml (or .codex/config.toml for a single trusted project). Give it the URL and the header:

# ~/.codex/config.toml
[mcp_servers.vidwords]
url = "https://vidwords.com/mcp"
env_http_headers = { "Authorization" = "VIDWORDS_MCP_AUTH" }

then export the value the variable names:

export VIDWORDS_MCP_AUTH="Basic YOUR_API_TOKEN"

Do not reach for bearer_token_env_var here. It is the obvious-looking field and it sends Authorization: Bearer <value>, but this server authenticates with Basic. env_http_headers is the escape hatch for exactly this case — a server whose scheme is not Bearer — and it keeps the token in the environment rather than in a file you might commit.

Any other MCP-compatible client works too, provided it can send a custom header. The full tool reference lives in the API documentation.

Honest limits

• Header auth only — there is no OAuth flow. Clients that only accept remote MCP servers behind OAuth will not take this URL as-is. Claude Code, Claude Desktop and Cursor all send custom headers, which is why those three are documented.
• The server is stateless by design. There are no resumable SSE streams and no session to delete; every tool answers in one shot. GET and DELETE return a JSON-RPC error rather than an HTML 404, so a client that probes them gets something its own layer can read.
• list_channel_videos needs the Starter plan or higher. The other five free tools work on any plan.
• RapidAPI tokens are refused here. That identity is metered per call on RapidAPI's side and has no account behind it, neither of which survives a tool-calling session. Use a VidWords API token.
• Captions have to exist. For a video with no caption track at all, a signed-in account can transcribe from audio instead — priced by length, quoted before you spend.

Get a free API token →