MCP server pretvara API u nekoliko imenovanih alata koje agent poziva usred razgovora, a dug posao se uklapa u taj model kada alat vrati identifikator na koji agent čeka u ograničenim intervalima. Zalijepite link do podcasta, zatražite sažetak na francuskom i ne napišete nijedan red koda.
Agent za pisanje koda može koristiti VocalStack API kao i svaki program: pročitati API referencu, napisati nekoliko linija koda uz SDK i pokrenuti ih. To je pravi put za nešto što će raditi bez agenta.
MCP (Model Context Protocol) je za drugi slučaj: razgovarate s asistentom i želite da nešto odmah transkribuje, bez koda. MCP server objavljuje kratak spisak imenovanih alata, a svaki ima opis i JSON šemu za svoje argumente. Agent pročita spisak jednom i pozove alat po imenu kada se zahtjev poklopi s njim. „Transkribuj ovaj podcast i reci mi šta su govorili o cijenama“ postaje tri poziva alata, a agent nikada ne vidi HTTP rutu.
Serveri dolaze u dvije vrste. Lokalni server radi kao podproces klijenta i komunicira preko stdio-a, što je način na koji rade većina servera za datotečni sistem i baze podataka. Udaljeni server stoji iza URL-a i govori Streamable HTTP, transport koji je zamijenio stariji HTTP-plus-SSE (server-sent events) transport u reviziji specifikacije iz marta 2025. Klijent šalje svaki zahtjev, a server odgovara na istoj vezi; sve što mora reći prije konačnog rezultata šalje se unaprijed kao stream. Svaki klijent napisan prema aktuelnoj specifikaciji može koristiti bilo koju vrstu.
VocalStack server je udaljene vrste, na adresi {{api}}/v1/mcp, a korištenje košta koliko košta API. Potrebna vam je samo adresa.
Otvorite oblast Developers na kontrolnoj ploči, na adresi {{app}}/developers. Prvi tab, Connect an AI agent, prikazuje URL servera i snippet za podešavanje za svakog klijenta. Tri isječka ispod odgovaraju onima koji su tamo prikazani.
Pokrenite ovo u terminalu:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Dodajte ovo u .cursor/mcp.json u vašem projektu ili u ~/.cursor/mcp.json za svaki projekat:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Svaki klijent koji podržava Streamable HTTP može dodati server ovom adresom. Ovo je generički oblik koji kontrolna ploča prikazuje:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Za početak vam ne treba API ključ. Kada se klijent prvi put poveže, prijavite se svojim VocalStack računom u pregledniku, a klijent zadržava token. Kontrolna ploča to kaže u jednoj rečenici: „Prvi put ćete se prijaviti svojim VocalStack računom. Ključ nije potreban.“
Ovo je MCP specifikacija za autorizaciju u djelu, a ne VocalStack trik. Udaljeni server odgovara na neautentifikovani zahtjev statusom 401 koji upućuje na njegove metapodatke zaštićenog resursa: mali JSON dokument koji navodi server za autorizaciju i opsege (scopes) koje server traži. Klijent to pročita, u pregledniku izvrši standardni OAuth 2.1 tok i vraća se s tokenom izdatim samo za taj server. Svaki udaljeni MCP server koji slijedi specifikaciju prijavljuje vas na isti način, zbog čega gornji klijenti to mogu bez ikakvog znanja o VocalStacku.
API ključ također radi, za klijent koji radi na serveru ili u skripti. Pošaljite ga kao Authorization: Bearer vs_key_..., isto zaglavlje koje prima REST API. Ključevi se kreiraju pod Developers → API keys. Dva alata za transkripciju trebaju dozvole Write i Stream audio. Druga zvuči čudno za datoteku, ali alati prolaze kroz istu tačku kreiranja kao svaka transkripcija, uključujući i live, a ta tačka provjerava obje. Alati za čitanje trebaju Read; list_voices treba samo važeće vjerodajnice.
Kada se prijavite, agent vidi devet alata. Rijetko ćete ih sami imenovati, ali njihovo poznavanje objašnjava šta agent radi dalje.
Svaki alat prima i vraća camelCase JSON, sa istim nazivima polja kao tipovi /v1 poruka; identifikator transkripcije je njen transcriptionId.
transcribe_url pokreće transkripciju zvuka ili videa na javnom URL-u: link do datoteke, epizode podcasta ili YouTube videa. Prijenosi uživo se ne prihvataju. Opcioni argumenti su name, spokenLanguage (izostavite ga da bi se jezik detektovao), speakerLabels (auto, on ili off) i startS/endS za transkripciju samo dijela zvuka.transcribe_file radi isto za datoteku koju agent ima, poslanu kao fileBase64 uz filename. Dekodirana veličina ograničena je na 10 MiB, otprilike deset minuta MP3 zapisa od 128 kbps; za sve veće, dajte agentu link.Oba odmah vraćaju transcriptionId, state: "queued" i next savjet koji imenuje alat za čekanje. Transkripcije koje kreira agent počinju kao privatne, bez linka za dijeljenje.
Agent ne može strpljivije pratiti prijenos uživo od vas; neprestano bi zvao alat za čekanje dok neko ne oduzme laptop. Završeni snimak ima kraj, i upravo na njega čeka sljedeći par alata.
Poziv alata je jedan HTTP zahtjev, a HTTP zahtjevi nisu namijenjeni da traju sat vremena. Klijenti odustanu od njih, proksiji ih zatvore, a model koji je blokiran na jednom alatu ne može ništa drugo. Zato je obrazac za svaki dugi posao iza MCP-a isti kao i kod REST API-ja: pokrenuti posao i dobiti identifikator, čekati na njega ograničeno vrijeme i ponovo pozvati ako nije gotov. Stanje nosi identifikator, a ne veza.
wait_for_transcription čeka dok posao ne bude done ili failed, ili dok ne istekne timeoutS (podrazumijevano 50 sekundi, najviše 60, što poziv drži ispod timeouta koje primjenjuje većina klijenata i proksija). Ako rezultat kaže timedOut: true, posao još radi i agent ponovo poziva alat. Dok alat čeka, server šalje MCP obavijesti o napretku, ako ih klijent traži: procenat i fazu, poput „dohvatanje 3.1 / 8.0 MB“ ili „transkribovanje 01:25 od 02:00“.get_transcription vraća status i, kada je gotovo, tekst. format: "text" daje jedan red po segmentu u obliku [mm:ss] Speaker 1: ...; "segments" daje vremenski označene redove s start, end, speaker i speakerName; includeWords: true dodaje vremenske oznake riječi. Rezultati se stranicuju (offset, limit, podrazumijevano 500 segmenata) uz nextOffset kada ih ostaje više.Stranicenje postoji zbog modela, a ne zbog mreže. Sve što alat vrati ubacuje se u kontekstni prozor agenta, gdje se takmiči s vašim razgovorom i troši tokene pri svakom sljedećem krugu. Sastanak od dva sata su desetine hiljada riječi; kada bi se sve vratilo odjednom, pitanje koje ste postavili bi ispalo iz konteksta. Dobri MCP alati vraćaju stranicu i kursor i prepuštaju agentu da odluči koliko mu treba.
Prekid veze ili timeout nikada ne otkazuje posao, jer posao živi na serveru, a ne u MCP zahtjevu. Kada je gotov, posao je još jedan unos u vašoj biblioteci, a sljedeći alati ga tretiraju kao svaki drugi.
list_transcriptions prikazuje transkripcije računa, od najnovije, sa statusom i trajanjem; lifecycle je active, archived ili all.search_transcriptions pretražuje šta je rečeno kroz sve transkripcije, na bilo kojem jeziku, i vraća odgovarajuće redove, svaki sa svojom transkripcijom i sekundom u kojoj je izgovoren. transcriptionId sužava pretragu na jednu transkripciju; lang dodaje prijevod svakog pogotka.Pronalaženje reda je jeftinija polovina posla. Dva alata dalje utvrđuju šta je cijeli snimak rekao.
get_summary vraća AI naslov i sažetak završene transkripcije, opcionalno preveden uz lang. state: "pending" znači da se sažetak još piše (obično je spreman nekoliko sekundi nakon završetka posla), pa agent pita ponovo.translate_transcription vraća završen transkript na drugom jeziku, kao tekst ili vremenske segmente, stranicen kao i get_transcription. Prijevodi se čuvaju, pa ponovno traženje ne ponavlja posao.list_voices prikazuje glasove koji mogu čitati transkript na nekom jeziku: id, naziv, pol i akcenat kada su poznati, ocjenu kvaliteta i da li je podrazumijevani ili jedan od vaših kloniranih glasova. Opisuje glasove; ne čini da neki progovori (više o tome šta server ne radi u nastavku).Evo kako alati rade zajedno u praksi.
Kada se server doda, razgovor u Claude Code izgleda ovako. Zalijepite link do podcasta i zatražite glavne tačke na francuskom.
Agent poziva transcribe_url:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Dobija transcriptionId i state: "queued", i prati next savjet:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Epizoda od pedeset minuta transkribuje se mnogo puta brže nego što se reproducira, ali ne unutar jednog čekanja. Prvo čekanje vraća timedOut: true s napretkom od, recimo, 61 posto, pa agent još jednom poziva alat i dobija state: "done".
Sada agent poziva get_summary s lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Ako je sažetak i dalje pending, agent čeka nekoliko sekundi; inače vam predaje naslov i sažetak na francuskom. Pitajte „o čemu su govorili u vezi s cijenama?“ i on poziva search_transcriptions s query: "pricing" i istim transcriptionId, pa citira odgovarajuće redove s vremenskim oznakama. Zatražite cijelu stvar na francuskom i poziva translate_transcription.
Nekoliko poziva alata, bez koda, i transkripcija u vašoj biblioteci. Svaki od tih poziva prošao je kroz iste kapije kao REST zahtjev, a upravo te kapije određuju račun i limite.
MCP server je API kroz drugi ulaz: isti limiti, isti račun.
POST /v1/transcriptions: primjenjuju se brzina kreiranja paketa (10, 100 ili prilagođen broj transkripcija pokrenutih po satu), ograničenje istovremenih transkripcija (1, 5 ili neograničeno) i njegov kredit. Kredit od $5 pri registraciji pokriva prvu sesiju, bez kartice.isError: true sa kodom greške REST API-ja, rečenicom na osnovu koje model može djelovati, te poljima retryable i retryAfterS. insufficient_credit nosi topUpUrl; rate_limited kaže koliko treba čekati. Ovo je važnije nego što zvuči: model čita tekst greške, pa rečenica na osnovu koje može djelovati slijepu ulicu pretvara u sljedeći poziv alata./v1/mcp zahtjev: agent u petlji dobija HTTP 429 s Retry-After prije nego što se ijedan alat pokrene.idempotencyKey: ponovna upotreba ključa završenog poziva ponavlja prvi rezultat, a ponovna upotreba s drugim argumentima se odbija, pa agent koji sam ponavlja pokušaje nikada ne pokreće drugi posao. Svaki alat koji troši novac trebao bi ovo nuditi; agenti ponavljaju pokušaje mnogo slobodnije nego ljudi.To su granice onoga što server radi. Dvije stvari su namjerno van njih.
Server nema alat koji pretvara proizvoljan tekst u govor, i nijedan nije planiran. VocalStack čita transkripte i njihove prijevode, standardnim ili kloniranim glasom, i ništa drugo. list_voices agentu kaže koji glasovi mogu čitati transkript na nekom jeziku, a ne kako natjerati glas da kaže nešto novo.
Alati za transkripciju također odbijaju prijenose uživo. YouTube prijenos uživo ili radijski stream treba transkripciju uživo, pokrenutu s kontrolne ploče ili preko POST /v1/transcriptions/live u API referenci. Završen YouTube video je datoteka, i transcribe_url ga prihvata.
Ako radije sami pišete kod, transkribovanje datoteke pomoću API-ja prolazi kroz iste korake kao HTTP pozivi, a tutorial za transkripciju u realnom vremenu obrađuje WebSocket.