Claude API YouTube Transcripts via mcp_servers

L'API Claude può recuperare trascrizioni YouTube da sola se le dai un server MCP nella richiesta. Il connettore MCP di Anthropic fa sì che l'API Messages esegua una chiamata a un server remoto, scopra i suoi strumenti e li chiami durante il completamento — nessun loop di esecuzione degli strumenti dalla tua parte. Ho verificato il blocco sottostante rispetto al server MCP ospitato di youtube2text.org oggi.

La richiesta

Il connettore MCP è una funzione beta, quindi ha bisogno dell'intestazione anthropic-beta: mcp-client-2025-11-20, e accetta due metà che devono fare riferimento l'una all'altra: la voce mcp_servers dichiara la connessione, e una voce mcp_toolset in tools concede l'accesso ad essa per nome. Ometti il toolset e l'API rifiuta la richiesta con un errore di validazione.

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

Due chiavi sono in gioco e non sono intercambiabili. x-api-key nell'intestazione è la tua chiave Anthropic. authorization_token dentro mcp_servers è la tua chiave youtube2text — viene inoltrata al server di trascrizione come token bearer. Ottienine una tramite accesso a Google su youtube2text.org/app/keys, o estrai la chiave demo condivisa da GET https://youtube2text.org/api/demo-key (5 video/mese per IP).

Cosa torna indietro

L'array content della risposta intercala l'attività dello strumento con la risposta: un blocco mcp_tool_use che mostra Claude che chiama transcribe_video con l'URL che ha estratto dal tuo prompt, un blocco mcp_tool_result che porta {title, content, contentSize, videoId, pubDate, truncated}, quindi un blocco text con il riassunto vero e proprio. Anthropic esegue l'intero giro di strumenti dal lato server — il tuo codice effettua una sola richiesta HTTP e legge il messaggio finale.

Poiché il connettore è beta, trattalo di conseguenza: l'intestazione è obbligatoria e la forma della richiesta è già cambiata una volta (le descrizioni precedenti mostrano mcp_servers senza la voce mcp_toolset — quel modulo precede l'intestazione attuale). Blocca la stringa beta e controlla la risposta per i blocchi mcp_tool_result prima di assumere che la trascrizione sia arrivata.

Il percorso senza codice

Non stai costruendo contro l'API? Due righe: su claude.ai vai a Impostazioni → Connettori → Aggiungi connettore personalizzato, incolla https://youtube2text.org/mcp, completa l'accesso a Google, fai clic su Consenti. Il server parla OAuth 2.1 con registrazione del client dinamica e PKCE, quindi claude.ai gestisce l'intero handshake — dettagli e cosa farne in trascrizioni YouTube gratuite in Claude.

Gli utenti di Claude Code ottengono lo stesso strumento con:

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

quindi /mcp dentro una sessione per accedere.

Quando usare quale

Usa il blocco mcp_servers quando stai costruendo un prodotto sull'API Messages e vuoi l'accesso alla trascrizione dentro un loop di agente esistente. Usa l'endpoint REST direttamente quando hai solo bisogno del testo — passare una trascrizione attraverso Claude per estrarla di nuovo è una costosa funzione identità. E se il tuo stack è dal lato OpenAI, l'API Responses accetta lo stesso server MCP con un blocco quasi identico.

L'utilizzo viene misurato in base al tuo piano youtube2text: il livello gratuito copre 5 video al mese, il livello base è $ 5,99/50, pro $ 9,99/500, illimitato $ 19,99. Chiavi su youtube2text.org/app/keys.