MCP server mení API na niekoľko pomenovaných nástrojov, ktoré agent volá počas rozhovoru, a dlhá úloha sa za ním dá zvládnuť, keď nástroj vráti identifikátor, na ktorý agent čaká v ohraničených krokoch. Vložte odkaz na podcast, požiadajte o podstatu vo francúzštine a nepíšete ani riadok kódu.
Kódujúci agent môže používať API VocalStack tak, ako ktorýkoľvek program: prečítať si referenciu API, napísať pár riadkov so SDK a spustiť ich. To je správna cesta pre niečo, čo bude bežať bez agenta.
MCP (Model Context Protocol) je určený pre druhý prípad: rozprávate sa s asistentom a chcete, aby niečo hneď prepísal, bez kódu. MCP server zverejní krátky zoznam pomenovaných nástrojov, z ktorých každý má popis a JSON schému svojich argumentov. Agent si zoznam prečíta raz a keď sa požiadavka zhoduje s nástrojom, zavolá ho podľa mena. „Prepíš tento podcast a povedz mi, čo hovorili o cenách“ sa zmení na tri volania nástrojov a agent nikdy neuvidí HTTP trasu.
Servery sú dvoch druhov. Lokálny server beží ako podproces klienta a komunikuje cez stdio, a takto fungujú väčšina serverov pre súborový systém a databázy. Vzdialený server je dostupný za URL a hovorí cez Streamable HTTP, transport, ktorý v revízii špecifikácie z marca 2025 nahradil starší transport HTTP-plus-SSE (server-sent events). Klient odošle každú požiadavku a server odpovedá na tom istom spojení; čokoľvek, čo musí povedať pred konečným výsledkom, sa streamuje pred ním. Ktorýkoľvek klient napísaný podľa aktuálnej špecifikácie dokáže použiť oba druhy.
Server VocalStack je vzdialeného typu, na adrese {{api}}/v1/mcp, a jeho používanie stojí rovnako ako API. Potrebujete len URL.
Otvorte oblasť Developers na nástenke VocalStack na adrese {{app}}/developers. Prvá karta, Connect an AI agent, zobrazuje URL servera a inštalačný úryvok pre každého klienta. Tri úryvky nižšie zodpovedajú tým, ktoré sú tam zobrazené.
Spustite toto vo svojom termináli:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Pridajte toto do .cursor/mcp.json vo svojom projekte alebo do ~/.cursor/mcp.json pre každý projekt:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Ktorýkoľvek klient, ktorý podporuje Streamable HTTP, môže pridať server touto URL. Toto je všeobecný tvar, ktorý zobrazuje nástenka:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Na začiatok API kľúč nepotrebujete. Pri prvom pripojení klienta sa v prehliadači prihlásite svojím účtom VocalStack a klient si token uchová. Nástenka to vyjadruje jedným riadkom: „Pri prvom použití sa prihlásite svojím účtom VocalStack. Kľúč nie je potrebný.“
Toto je činnosť špecifikácie autorizácie MCP, nie trik VocalStack. Vzdialený server na neautorizovanú požiadavku odpovie 401 s odkazom na svoje metadáta chráneného zdroja: malý JSON dokument, ktorý uvádza autorizačný server a rozsahy, ktoré server vyžaduje. Klient ich prečíta, v prehliadači spustí štandardný tok OAuth 2.1 a vráti sa s tokenom vydaným len pre tento server. Každý vzdialený MCP server, ktorý dodržiava špecifikáciu, vás prihlási rovnako, a preto to uvedení klienti dokážu bez toho, aby čokoľvek vedeli o VocalStack.
Funguje aj API kľúč, a to pre klienta bežiaceho na serveri alebo v skripte. Posielajte ho ako Authorization: Bearer vs_key_..., rovnakou hlavičkou, akú prijíma REST API. Kľúče sa vytvárajú v sekcii Developers → API keys. Dva nástroje na prepis potrebujú oprávnenia Write a Stream audio. Druhé znie pri súbore zvláštne, no nástroje prechádzajú cez to isté miesto vytvárania ako každý prepis, aj živé, a toto miesto kontroluje obe. Nástroje na čítanie potrebujú Read; list_voices potrebuje len platné overenie.
Keď ste prihlásení, agent vidí deväť nástrojov. Len zriedka ich budete pomenúvať sami, no ak ich poznáte, pochopíte, čo agent urobí ďalej.
Každý nástroj prijíma a vracia JSON v camelCase s rovnakými názvami polí ako typy /v1 vo wire formáte; identifikátorom prepisu je jeho transcriptionId.
transcribe_url spustí prepis zvuku alebo videa na verejnej URL: odkaz na súbor, epizódu podcastu, video na YouTube. Živé streamy sa neprijímajú. Voliteľné argumenty: name, spokenLanguage (vynechajte ho, ak chcete jazyk zistiť automaticky), speakerLabels (auto, on alebo off) a startS/endS, ak chcete prepísať len časť zvuku.transcribe_file robí to isté pre súbor, ktorý má agent k dispozícii, odoslaný ako fileBase64 s jeho filename. Dekódovaná veľkosť je obmedzená na 10 MiB, zhruba desať minút MP3 s 128 kbps; pri väčších dajte agentovi odkaz.Oba nástroje okamžite vrátia transcriptionId, state: "queued" a nápovedu next s menom nástroja na čakanie. Prepisy vytvorené agentom začínajú ako súkromné, bez zdieľacieho odkazu.
Agent nevydrží pri živom vysielaní o nič trpezlivejšie než vy; neustále by volal nástroj na čakanie, kým by mu niekto nevzal notebook. Dokončená nahrávka má koniec a práve na ten čakajú nasledujúce dva nástroje.
Volanie nástroja je jeden HTTP požiadavok a HTTP požiadavky nie sú určené na to, aby trvali hodinu. Klienti ich vzdajú, proxy ich zatvoria a model, ktorý čaká na jeden nástroj, nemôže robiť nič iné. Vzor pre každú dlhú úlohu za MCP je preto rovnaký, aký používa aj REST API: spustiť úlohu a dostať identifikátor, počkať na ňu ohraničený čas a zavolať znova, ak ešte nie je hotová. Stav nesie identifikátor, nie spojenie.
wait_for_transcription čaká, kým úloha nebude done alebo failed, alebo kým neuplynie timeoutS (predvolene 50 sekúnd, najviac 60, čo udrží volanie pod časovými limitmi, ktoré uplatňuje väčšina klientov a proxy). Ak výsledok hovorí timedOut: true, úloha stále beží a agent nástroj zavolá znova. Kým nástroj čaká, server posiela notifikácie o priebehu MCP, ak o ne klient požiadal: percento a fázu, napríklad „sťahuje sa 3.1 / 8.0 MB“ alebo „prepisuje sa 01:25 z 02:00“.get_transcription vráti stav a po dokončení aj text. format: "text" dá jeden riadok na segment vo tvare [mm:ss] Speaker 1: ...; "segments" dá časované riadky s start, end, speaker a speakerName; includeWords: true pridá časovanie slov. Výsledky sa stránkujú (offset, limit, predvolene 500 segmentov) a keď zostáva viac, obsahujú nextOffset.Stránkovanie je tu kvôli modelu, nie kvôli sieti. Všetko, čo nástroj vráti, sa vloží do kontextového okna agenta, kde súperí s vaším rozhovorom a pri každom ďalšom kole stojí tokeny. Dvojhodinové stretnutie má desiatky tisíc slov; keby sa všetko vrátilo naraz, otázka, ktorú ste položili, by z kontextu vypadla. Dobré nástroje MCP vrátia stránku a kurzor a nechajú agenta rozhodnúť, koľko potrebuje.
Odpojenie ani časový limit úlohu nikdy nezruší, pretože úloha žije na serveri, nie v požiadavke MCP. Keď je hotová, je ďalšou položkou vo vašej knižnici a ďalšie nástroje s ňou zaobchádzajú ako s akoukoľvek inou.
list_transcriptions vypíše prepisy účtu od najnovšieho so stavom a dĺžkou; lifecycle je active, archived alebo all.search_transcriptions vyhľadá, čo sa povedalo vo všetkých prepisoch, v ľubovoľnom jazyku, a vráti zodpovedajúce riadky, každý s jeho prepisom a sekundou, v ktorej zaznel. transcriptionId hľadanie zúži na jeden prepis; lang pridá preklad každého nálezu.Nájsť riadok je len lacnejšia polovica. Dva ďalšie nástroje zistia, čo bolo povedané v celku.
get_summary vráti názov a zhrnutie dokončeného prepisu vytvorené umelou inteligenciou, voliteľne preložené pomocou lang. state: "pending" znamená, že zhrnutie sa ešte píše (zvyčajne je hotové pár sekúnd po dokončení úlohy), a agent sa opýta znova.translate_transcription vráti dokončený prepis v inom jazyku, ako text alebo časované segmenty, stránkovaný ako get_transcription. Preklady sa ukladajú, takže opätovné požiadanie nezopakuje prácu.list_voices vypíše hlasy, ktoré dokážu prečítať prepis v jazyku: id, názov, pohlavie a prízvuk, ak sú známe, hodnotenie kvality a to, či ide o predvolený hlas alebo jeden z vašich klonovaných hlasov. Hlasy opisuje; nerobí, aby niektorý hovoril (viac o tom, čo server nerobí, nižšie).Takto sa nástroje v praxi spájajú.
Keď je server pridaný, rozhovor v Claude Code vyzerá takto. Vložíte odkaz na podcast a požiadate o podstatu vo francúzštine.
Agent zavolá transcribe_url:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Dostane späť transcriptionId a state: "queued" a riadi sa nápovedou next:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Päťdesiatminútová epizóda sa prepíše mnohonásobne rýchlejšie, než sa prehráva, ale nie v rámci jedného čakania. Prvé čakanie vráti timedOut: true s priebehom na, povedzme, 61 percent, takže agent nástroj zavolá ešte raz a dostane state: "done".
Agent teraz zavolá get_summary s lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Ak je zhrnutie stále pending, agent počká pár sekúnd; inak vám odovzdá názov a zhrnutie vo francúzštine. Opýtajte sa „Kde hovorili o cenách?“ a agent zavolá search_transcriptions s query: "pricing" a rovnakým transcriptionId a zacituje zodpovedajúce riadky s ich časovými značkami. Ak si želáte celé vo francúzštine, zavolá translate_transcription.
Pár volaní nástrojov, žiadny kód a prepis vo vašej knižnici. Každé z týchto volaní prešlo rovnakými bránami ako požiadavka REST a práve tie brány určujú účet a limity.
Server MCP je API cez iné vchodové dvere: rovnaké limity, rovnaký účet.
POST /v1/transcriptions: platí rýchlosť vytvárania plánu (10, 100 alebo vlastný počet prepisov spustených za hodinu), jeho limit súbežných prepisov (1, 5 alebo neobmedzený) a jeho kredit. Registračný kredit $5 pokryje prvú reláciu, karta nie je potrebná.isError: true s chybovým kódom REST API, vetou, s ktorou môže model niečo urobiť, a poľami retryable a retryAfterS. insufficient_credit nesie topUpUrl; rate_limited hovorí, ako dlho čakať. Toto je dôležitejšie, než to znie: model číta text chyby, takže veta, s ktorou môže niečo urobiť, mení slepú uličku na ďalšie volanie nástroja./v1/mcp: slučkujúci agent dostane HTTP 429 s Retry-After skôr, než sa spustí akýkoľvek nástroj.idempotencyKey: opätovné použitie kľúča dokončeného volania zopakuje prvý výsledok a opätovné použitie s inými argumentmi sa odmietne, takže agent, ktorý sa sám opakuje, nikdy nespustí druhú úlohu. Každý nástroj, ktorý míňa peniaze, by to mal ponúkať; agenti sa opakujú oveľa voľnejšie než ľudia.Toto sú hranice toho, čo server robí. Dve veci ležia úmyselne mimo nich.
Server nemá nástroj, ktorý by ľubovoľný text premenil na reč, a žiadny sa neplánuje. VocalStack hovorí prepisy a ich preklady, štandardným alebo klonovaným hlasom, a nič iné. list_voices agentovi povie, ktoré hlasy dokážu prečítať prepis v jazyku, nie ako prinútiť hlas povedať niečo nové.
Nástroje na prepis tiež odmietajú živé streamy. Živý stream na YouTube alebo rádiový stream potrebuje živý prepis, spustený z nástenky alebo cez POST /v1/transcriptions/live v referencii API. Dokončené video na YouTube je súbor a transcribe_url ho prijme.
Ak radšej napíšete kód sami, prepis súboru pomocou API prejde rovnaké kroky ako volania HTTP a návod pre prepis v reálnom čase pokrýva WebSocket.