Claude API YouTube Transcripts via mcp_servers

The Claude API can fetch YouTube transcripts by itself if you hand it an MCP server in the request. Anthropic's MCP connector makes the Messages API dial out to a remote server, discover its tools, and call them mid-completion — no tool-execution loop on your side. I verified the block below against youtube2text.org's hosted MCP server today.

The request

The MCP connector is a beta feature, so it needs the anthropic-beta: mcp-client-2025-11-20 header, and it takes two halves that must reference each other: the mcp_servers entry declares the connection, and an mcp_toolset entry in tools grants access to it by name. Omit the toolset and the API rejects the request with a validation error.

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 16000,
    "mcp_servers": [{
      "type": "url",
      "url": "https://youtube2text.org/mcp",
      "name": "youtube2text",
      "authorization_token": "YOUR_API_KEY"
    }],
    "tools": [{"type": "mcp_toolset", "mcp_server_name": "youtube2text"}],
    "messages": [{
      "role": "user",
      "content": "Summarize https://www.youtube.com/watch?v=dQw4w9WgXcQ in five bullets."
    }]
  }'

Two keys are in play and they are not interchangeable. x-api-key in the header is your Anthropic key. authorization_token inside mcp_servers is your youtube2text key — it gets forwarded to the transcript server as a bearer token. Get one via Google sign-in at youtube2text.org/app/keys, or pull the shared demo key from GET https://youtube2text.org/api/demo-key (5 videos/month per IP).

What comes back

The response content array interleaves the tool activity with the answer: an mcp_tool_use block showing Claude calling transcribe_video with the URL it extracted from your prompt, an mcp_tool_result block carrying {title, content, contentSize, videoId, pubDate, truncated}, then a text block with the actual summary. Anthropic runs the whole tool round trip server-side — your code makes one HTTP request and reads the final message.

Because the connector is beta, treat it accordingly: the header is mandatory, and the request shape has already changed once (older writeups show mcp_servers without the mcp_toolset entry — that form predates the current header). Pin the beta string and check the response for mcp_tool_result blocks before assuming the transcript arrived.

The no-code path

Not building against the API? Two lines: in claude.ai go to Settings → Connectors → Add custom connector, paste https://youtube2text.org/mcp, complete the Google sign-in, click Allow. The server speaks OAuth 2.1 with dynamic client registration and PKCE, so claude.ai handles the entire handshake — details and what to do with it in free YouTube transcripts in Claude.

Claude Code users get the same tool with:

claude mcp add --transport http youtube2text https://youtube2text.org/mcp

then /mcp inside a session to sign in.

When to use which

Use the mcp_servers block when you're building a product on the Messages API and want transcript access inside an existing agent loop. Use the REST endpoint directly when you just need the text — piping a transcript through Claude to extract it back out is an expensive identity function. And if your stack is OpenAI-side, the Responses API takes the same MCP server with a nearly identical block.

Usage is metered against your youtube2text plan: free covers 5 videos a month, basic is $5.99/50, pro $9.99/500, unlimited $19.99. Keys at youtube2text.org/app/keys.