Ginagawang ilang pinangalanang tool ang isang MCP server ng API na tinatawag ng agent habang may usapan, at kasya rito ang mahabang job kapag ang tool ay nagbibigay ng handle na hinihintay ng agent sa mga limitadong turn. I-paste ang link ng podcast, humingi ng buod sa French, at walang code na isusulat.
Maaaring gamitin ng coding agent ang VocalStack API tulad ng anumang program: basahin ang API reference, magsulat ng ilang linya gamit ang SDK, at patakbuhin ang mga ito. Ito ang tamang daan para sa bagay na tatakbo nang hindi kasama ang agent.
Para naman sa kabilang kaso ang MCP (ang Model Context Protocol): nakikipag-usap ka sa isang assistant at gusto mong i-transcribe ang isang bagay ngayon din, nang walang code. Naglalathala ang MCP server ng maikling listahan ng mga pinangalanang tool, bawat isa ay may paglalarawan at JSON schema para sa mga argument nito. Binabasa ng agent ang listahan nang minsan lang at tinatawag ang isang tool sa pangalan nito kapag tumutugma dito ang isang request. Ang "I-transcribe ang podcast na ito at sabihin mo sa akin ang sinabi nila tungkol sa pricing" ay nagiging tatlong tool call, at hindi kailanman nakikita ng agent ang isang HTTP route.
May dalawang uri ang server. Ang local server ay tumatakbo bilang subprocess ng client at nakikipag-usap sa pamamagitan ng stdio, na siyang paraan ng karamihan sa file-system at database server. Ang remote server naman ay nasa likod ng URL at gumagamit ng Streamable HTTP, ang transport na pumalit sa mas lumang HTTP-plus-SSE (server-sent events) transport sa binagong spec noong Marso 2025. Nagpo-post ang client ng bawat request, at sumasagot ang server sa parehong connection; anumang kailangan nitong sabihin bago ang huling resulta ay ipinapadala nang streaming bago iyon. Anumang client na isinulat ayon sa kasalukuyang spec ay kayang gumamit ng alinman sa dalawa.
Remote na uri ang server ng VocalStack, sa {{api}}/v1/mcp, at ang paggamit nito ay kapareho ng gastos ng API. URL lang ang kailangan mo.
Buksan ang Developers area ng Dashboard sa {{app}}/developers. Makikita sa unang tab, Connect an AI agent, ang server URL at isang setup snippet para sa bawat client. Tugma ang tatlong snippet sa ibaba sa mga nakikita roon.
Patakbuhin ito sa iyong terminal:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Idagdag ito sa .cursor/mcp.json sa iyong project, o sa ~/.cursor/mcp.json para sa bawat project:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Maaaring idagdag ng anumang client na sumusuporta sa Streamable HTTP ang server gamit ang URL na ito. Ito ang generic na anyo na ipinapakita ng Dashboard:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Hindi mo kailangan ng API key para magsimula. Sa unang pagkonekta ng client, mag-sign in ka gamit ang iyong VocalStack account sa browser, at itinatago ng client ang token. Isang linya ang ginagamit ng Dashboard para dito: "Mag-sign in ka gamit ang iyong VocalStack account sa unang pagkakataon. Hindi kailangan ng key."
Ito ang authorization spec ng MCP na gumagana, hindi isang trick ng VocalStack. Sumasagot ang remote server sa unauthenticated na request ng 401 na tumuturo sa protected-resource metadata nito: isang maliit na JSON document na nagpapangalan sa authorization server at sa mga scope na kailangan ng server. Binabasa ito ng client, nagpapatakbo ng karaniwang OAuth 2.1 flow sa iyong browser, at bumabalik na may token na inisyu para sa server na iyon lamang. Anumang remote MCP server na sumusunod sa spec ay nagpa-sign in sa iyo sa parehong paraan, kaya nagagawa ito ng mga client sa itaas nang hindi alam ang anuman tungkol sa VocalStack.
Gumagana rin ang API key, para sa client na tumatakbo sa server o sa script. Ipadala ito bilang Authorization: Bearer vs_key_..., ang parehong header na tinatanggap ng REST API. Ginagawa ang mga key sa ilalim ng Developers → API keys. Kailangan ng dalawang transcribe tool ang mga permission na Write at Stream audio. Kakaiba pakinggan ang ikalawa para sa isang file, pero dumadaan ang mga tool sa parehong creation point ng bawat transcription, kasama ang mga live, at sinusuri ng point na iyon ang dalawa. Kailangan ng mga reading tool ang Read; kailangan lang ng list_voices ng balidong credential.
Kapag naka-sign in ka na, makikita ng agent ang siyam na tool. Bihira mo itong pangalanan mismo, pero makatutulong ang pag-alam sa mga ito para maintindihan kung ano ang susunod na gagawin ng agent.
Bawat tool ay tumatanggap at nagbabalik ng camelCase JSON, na may parehong field name ng mga /v1 wire type; ang handle ng isang transcription ay ang transcriptionId nito.
transcribe_url sinisimulan ang pag-transcribe ng audio o video sa isang public URL: isang file link, isang episode ng podcast, isang YouTube video. Hindi tinatanggap ang mga live stream. Mga opsyonal na argument: name, spokenLanguage (alisin ito para awtomatikong matukoy ang wika), speakerLabels (auto, on o off) at startS/endS para i-transcribe lamang ang bahagi ng audio.transcribe_file ginagawa ang parehong bagay para sa file na hawak ng agent, ipinapadala bilang fileBase64 kasama ang filename nito. Hanggang 10 MiB lamang ang laki pagkatapos i-decode, humigit-kumulang sampung minuto ng 128 kbps MP3; para sa mas malaki, bigyan ang agent ng link.Parehong agad na nagbabalik ang dalawa ng transcriptionId, state: "queued" at isang next hint na nagpapangalan sa wait tool. Nagsisimulang pribado ang mga transcription na ginawa ng agent, walang share link.
Hindi kayang magtiis ng agent sa isang live broadcast nang mas matiyaga kaysa sa iyo; patuloy nitong tatawagin ang wait tool hanggang may kumuha ng laptop mo. May katapusan ang tapos nang recording, at iyon ang hinihintay ng susunod na dalawang tool.
Isang HTTP request ang bawat tool call, at hindi dapat tumagal nang isang oras ang mga HTTP request. Sumusuko ang mga client sa mga ito, isinasara ng mga proxy, at ang model na naka-block sa isang tool ay wala nang magagawa pa. Kaya ang pattern para sa anumang mahabang job sa likod ng MCP ay ang pareho ring ginagamit ng REST API: simulan ang job at kumuha ng handle, maghintay dito sa limitadong oras, at tumawag muli kung hindi pa tapos. Ang handle, hindi ang connection, ang nagdadala ng state.
wait_for_transcription naghihintay hanggang ang job ay done o failed, o hanggang lumipas ang timeoutS (default na 50 segundo, pinakamataas na 60, para manatili ang tawag sa ilalim ng mga timeout na ipinapataw ng karamihan sa client at proxy). Kapag sinabi ng resulta na timedOut: true, tumatakbo pa rin ang job at tinatawag muli ng agent ang tool. Habang naghihintay ang tool, nagpapadala ang server ng MCP progress notification kung hiniling ito ng client: isang porsyento at isang yugto gaya ng "fetching 3.1 / 8.0 MB" o "transcribing 01:25 of 02:00".get_transcription nagbabalik ng status at, kapag tapos na, ng teksto. Ang format: "text" ay nagbibigay ng isang linya bawat segment bilang [mm:ss] Speaker 1: ...; ang "segments" ay nagbibigay ng mga linyang may oras na may start, end, speaker at speakerName; ang includeWords: true ay nagdaragdag ng word timing. Hinahati sa pahina ang mga resulta (offset, limit, default na 500 segment) at may nextOffset kapag may natitira pa.Para sa model ang paghahati sa pahina, hindi para sa network. Lahat ng ibinabalik ng tool ay idinidikit sa context window ng agent, kung saan nakikipagkompetensya ito sa usapan ninyo at nagkakagastos ng token sa bawat susunod na turn. Ang dalawang oras na meeting ay libo-libong salita; kung ibabalik lahat nang sabay, maitutulak palabas ng context ang tanong na itinanong mo. Ang mahusay na MCP tool ay nagbabalik ng isang pahina at isang cursor, at hinahayaan ang agent na magpasya kung gaano karami ang kailangan nito.
Hindi kailanman kinakansela ng pagkaputol ng connection o ng timeout ang job, dahil nasa server ang job, hindi sa MCP request. Kapag tapos na ito, isa na itong entry sa library mo, at tinatrato ito ng mga susunod na tool na gaya ng iba.
list_transcriptions inililista ang mga transcription ng account, pinakabago muna, kasama ang state at tagal; ang lifecycle ay active, archived o all.search_transcriptions naghahanap sa lahat ng sinabi sa bawat transcription, sa anumang wika, at nagbabalik ng mga tugmang linya, bawat isa kasama ang transcription nito at ang segundong sinabi ito. Ang transcriptionId ay nagpapaliit sa paghahanap sa isang transcription; ang lang ay nagdaragdag ng salin ng bawat resulta.Mas mura ang paghahanap ng isang linya, ang kalahati lang ng gawain. May dalawa pang tool na tumutukoy kung ano ang sinabi sa kabuuan.
get_summary nagbabalik ng AI title at buod ng isang tapos nang transcription, opsyonal na isinalin gamit ang lang. Ang state: "pending" ay nangangahulugang isinusulat pa ang buod (kadalasang handa ito sa loob ng ilang segundo pagkatapos matapos ang job), at magtatanong ulit ang agent.translate_transcription nagbabalik ng tapos nang transcript sa ibang wika, bilang teksto o mga segment na may oras, hinahati sa pahina tulad ng get_transcription. Naka-store ang mga pagsasalin, kaya hindi inuulit ang trabaho kapag muling humingi.list_voices inililista ang mga boses na kayang magbasa ng transcript sa isang wika: id, pangalan, kasarian at accent kapag alam, rating ng kalidad, at kung default ito o isa sa iyong mga cloned na boses. Naglalarawan ito ng mga boses; hindi nito pinapasalita ang isa (mas marami pa sa ibaba tungkol sa hindi kayang gawin ng server).Ganito nagkakabit-kabit ang mga tool sa aktwal na paggamit.
Kapag naidagdag na ang server, ganito ang takbo ng usapan sa Claude Code. I-paste mo ang link ng podcast at humingi ng buod sa French.
Tinatawag ng agent ang transcribe_url:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Nakakakuha ito ng transcriptionId at state: "queued", at sinusunod ang next hint:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Ang episode na limampung minuto ay natatapos sa transcribe nang maraming beses na mas mabilis kaysa sa haba nito, pero hindi sa iisang paghihintay. Ibinabalik ng unang paghihintay ang timedOut: true na may progress na, halimbawa, 61 porsyento, kaya tinatawag ng agent ang tool minsan pa at nakukuha ang state: "done".
Ngayon tinatawag ng agent ang get_summary na may lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Kapag pending pa rin ang buod, maghihintay ng ilang segundo ang agent; kung hindi, ibibigay nito sa iyo ang title at buod sa French. Itanong ang "saan sila nag-usap tungkol sa pricing?" at tatawagin nito ang search_transcriptions na may query: "pricing" at ang parehong transcriptionId, at sisipiin ang mga tugmang linya kasama ang kanilang timestamp. Humingi ng buong nilalaman sa French at tatawagin nito ang translate_transcription.
Ilang tool call lang, walang code, at isang transcription sa iyong library. Dumaan ang bawat tawag na iyon sa parehong gate ng isang REST request, at ang mga gate na iyon ang nagtatakda ng bayarin at mga limitasyon.
Ang MCP server ay ang API sa ibang pintuan: parehong limitasyon, parehong bayarin.
POST /v1/transcriptions: sakop ng mga ito ang creation rate ng plan (10, 100 o isang custom na bilang ng transcription na sinimulan kada oras), ang cap nito sa sabay-sabay na transcription (1, 5 o unlimited), at ang credit nito. Sakop ng $5 na signup credit ang unang session, hindi kailangan ng card.isError: true kasama ang error code ng REST API, isang pangungusap na kayang kumilos ang model, at mga field na retryable at retryAfterS. Dala ng insufficient_credit ang topUpUrl; sinasabi ng rate_limited kung gaano katagal maghihintay. Mas mahalaga ito kaysa sa tunog: binabasa ng model ang teksto ng error, kaya ang pangungusap na kayang kumilos nito ay nagiging susunod na tool call sa halip na patay na dulo./v1/mcp request: makakatanggap ang agent na umiikot ng HTTP 429 na may Retry-After bago tumakbo ang anumang tool.idempotencyKey: kapag ginamit muli ang key ng natapos nang tawag, ibinabalik nito ang unang resulta, at kapag ginamit ito kasama ang ibang argument, tinatanggihan ito, kaya hindi kailanman nagsisimula ng pangalawang job ang agent na kusang nagre-retry. Dapat mag-alok nito ang sinumang tool na gumagastos ng pera; mas malaya mag-retry ang mga agent kaysa sa tao.Ito ang mga hangganan ng ginagawa ng server. May dalawang bagay na sadyang nasa labas ng mga ito.
Walang tool ang server na nagpapalit ng anumang teksto sa pananalita, at wala ring plano para dito. Binibigkas ng VocalStack ang mga transcript at ang kanilang mga salin, sa stock o cloned na boses, at wala nang iba. Sinasabi ng list_voices sa agent kung aling mga boses ang kayang magbasa ng transcript sa isang wika, hindi kung paano pasasalitain ang boses ng bagong sasabihin.
Tinatanggihan din ng mga transcribe tool ang mga live stream. Ang YouTube live stream o radio stream ay nangangailangan ng live na transcription, na sinimulan mula sa Dashboard o sa pamamagitan ng POST /v1/transcriptions/live sa API reference. Ang tapos nang YouTube video ay file, at tinatanggap ito ng transcribe_url.
Kung mas gusto mong isulat ang code mismo, dadaanan ng pag-transcribe ng file gamit ang API ang parehong hakbang bilang mga HTTP call, at sasaklawin ng real-time tutorial ang WebSocket.