Transcripciones de YouTube en la Claude API vía mcp_servers

La Claude API puede obtener transcripciones de YouTube por sí sola si le entregas un servidor MCP en la petición. El conector MCP de Anthropic hace que la Messages API se conecte a un servidor remoto, descubra sus herramientas y las llame en mitad de la generación — sin bucle de ejecución de herramientas de tu lado. Verifiqué el bloque de abajo contra el servidor MCP alojado de youtube2text.org hoy mismo.

La petición

El conector MCP es una funcionalidad beta, así que necesita la cabecera anthropic-beta: mcp-client-2025-11-20, y consta de dos mitades que deben referenciarse mutuamente: la entrada mcp_servers declara la conexión, y una entrada mcp_toolset en tools concede acceso a ella por nombre. Omite el toolset y la API rechaza la petición con un error de validación.

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."
    }]
  }'

Hay dos claves en juego y no son intercambiables. x-api-key en la cabecera es tu clave de Anthropic. authorization_token dentro de mcp_servers es tu clave de youtube2text — se reenvía al servidor de transcripciones como token bearer. Consigue una con inicio de sesión de Google en youtube2text.org/app/keys, o toma la clave de demostración compartida de GET https://youtube2text.org/api/demo-key (5 videos al mes por IP).

Qué recibes de vuelta

El array content de la respuesta intercala la actividad de la herramienta con la respuesta: un bloque mcp_tool_use que muestra a Claude llamando a transcribe_video con la URL que extrajo de tu prompt, un bloque mcp_tool_result que trae {title, content, contentSize, videoId, pubDate, truncated}, y luego un bloque text con el resumen en sí. Anthropic ejecuta todo el viaje de ida y vuelta de la herramienta del lado del servidor — tu código hace una petición HTTP y lee el mensaje final.

Como el conector es beta, trátalo en consecuencia: la cabecera es obligatoria, y la forma de la petición ya cambió una vez (artículos antiguos muestran mcp_servers sin la entrada mcp_toolset — esa forma es anterior a la cabecera actual). Fija la cadena beta y comprueba que la respuesta contiene bloques mcp_tool_result antes de asumir que la transcripción llegó.

La ruta sin código

¿No estás construyendo contra la API? Dos líneas: en claude.ai ve a Configuración → Conectores → Añadir conector personalizado, pega https://youtube2text.org/mcp, completa el inicio de sesión de Google, haz clic en Permitir. El servidor habla OAuth 2.1 con registro dinámico de clientes y PKCE, así que claude.ai gestiona todo el handshake — detalles y qué hacer con ello en transcripciones de YouTube gratis en Claude.

Los usuarios de Claude Code obtienen la misma herramienta con:

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

y luego /mcp dentro de una sesión para iniciar sesión.

Cuándo usar cada uno

Usa el bloque mcp_servers cuando construyes un producto sobre la Messages API y quieres acceso a transcripciones dentro de un bucle de agente existente. Usa el endpoint REST directamente cuando solo necesitas el texto — pasar una transcripción a través de Claude para volver a extraerla es una función identidad muy cara. Y si tu stack está del lado de OpenAI, la Responses API acepta el mismo servidor MCP con un bloque casi idéntico.

El uso se contabiliza contra tu plan de youtube2text: el gratuito cubre 5 videos al mes, el básico es $5.99/50, el pro $9.99/500, el ilimitado $19.99. Claves en youtube2text.org/app/keys.