Strežnik MCP spremeni API v nekaj poimenovanih orodij, ki jih agent kliče med pogovorom, dolgo opravilo pa se da skriti za enim takim orodjem, če mu orodje vrne ročico, na katero agent v omejenih korakih čaka. Prilepite povezavo do podcasta, prosite za bistvo v francoščini in ne napišete nobene kode.
Programersko orodje z umetno inteligenco lahko uporablja API VocalStack tako kot vsak drug program: prebere referenco API, napiše nekaj vrstic s SDK in jih požene. To je prava pot za nekaj, kar bo teklo brez agenta.
MCP (Model Context Protocol) je za drugi primer: pogovarjate se z asistentom in želite, da zdaj nekaj prepiše, brez kode. Strežnik MCP objavi kratek seznam poimenovanih orodij, vsako z opisom in shemo JSON za argumente. Agent seznam prebere enkrat in orodje pokliče po imenu, kadar se zahteva ujema z njim. »Prepiši ta podcast in mi povej, kaj so rekli o cenah« se spremeni v tri klice orodij, agent pa nikoli ne vidi poti HTTP.
Strežniki so dveh vrst. Lokalni strežnik teče kot podproces odjemalca in komunicira prek stdio, kar je način, kako delujeta večina strežnikov za datotečni sistem in podatkovne baze. Oddaljeni strežnik je za naslovom URL in govori Streamable HTTP, prenosni protokol, ki je v revziji specifikacije iz marca 2025 nadomestil starejši prenos HTTP-plus-SSE (server-sent events). Odjemalec pošlje vsako zahtevo, strežnik pa odgovori po isti povezavi; vse, kar mora povedati pred končnim rezultatom, se pošlje pred njim, v toku. Vsak odjemalec, napisan za trenutno specifikacijo, lahko uporablja obe vrsti.
Strežnik VocalStack je oddaljene vrste, na naslovu {{api}}/v1/mcp, in uporaba stane toliko kot API. Potrebujete le naslov URL.
Odprite območje Developers na nadzorni plošči na {{app}}/developers. Prvi zavihek, Connect an AI agent, prikazuje naslov strežnika in odlomek za nastavitev za vsakega odjemalca. Trije odlomki spodaj ustrezajo tistim, ki so prikazani tam.
V terminalu zaženite:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Dodajte to v .cursor/mcp.json v svojem projektu ali v ~/.cursor/mcp.json za vse projekte:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Strežnik lahko doda vsak odjemalec, ki podpira Streamable HTTP, s tem naslovom URL. Tako je splošna oblika, ki jo prikazuje nadzorna plošča:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Za začetek ne potrebujete ključa API. Ob prvi povezavi odjemalca se v brskalniku prijavite s svojim računom VocalStack, odjemalec pa token shrani. Nadzorna plošča to pove v eni vrstici: »Prvič se boste prijavili s svojim računom VocalStack. Ključ ni potreben.«
To ni trik VocalStack, temveč specifikacija avtorizacije MCP v delu. Oddaljeni strežnik na neavtorizirano zahtevo odgovori s 401, ki kaže na njegove metapodatke zaščitenega vira: majhen dokument JSON, ki navaja strežnik za avtorizacijo in področja, ki jih strežnik zahteva. Odjemalec ga prebere, v brskalniku zažene standardni tok OAuth 2.1 in se vrne s tokenom, izdanim samo za ta strežnik. Vsak oddaljeni strežnik MCP, ki sledi specifikaciji, vas prijavi enako, zato lahko zgornji odjemalci to naredijo, ne da bi kaj vedeli o VocalStack.
Deluje tudi ključ API, za odjemalca, ki teče na strežniku ali v skripti. Pošljite ga kot Authorization: Bearer vs_key_..., z isto glavo, ki jo sprejema REST API. Ključe ustvarite pod Developers → API keys. Obe orodji za prepis potrebujeta dovoljenji Write in Stream audio. Drugo se za datoteko sliši nenavadno, a orodji gresta prek iste točke ustvarjanja kot vsak prepis, vključno z živimi prepisi, in ta točka preverja obe. Orodja za branje potrebujejo Read; list_voices potrebuje le veljavno poverilnico.
Ko ste prijavljeni, agent vidi devet orodij. Redko jih boste poimenovali sami, a če jih poznate, boste razumeli, kaj agent naredi naslednje.
Vsako orodje sprejema in vrača JSON v camelCase z istimi imeni polj kot tipi /v1 v prenosu; ročica prepisa je njegov transcriptionId.
transcribe_url začne prepisovati zvok ali video na javnem naslovu URL: povezavo do datoteke, epizodo podcasta, videoposnetek na YouTubu. Živih tokov ne sprejema. Neobvezni argumenti: name, spokenLanguage (izpustite ga, da se jezik zazna samodejno), speakerLabels (auto, on ali off) ter startS/endS, s katerima prepišete samo del zvoka.transcribe_file naredi enako za datoteko, ki jo ima agent, poslano kot fileBase64 z filename. Dekodirana velikost je omejena na 10 MiB, približno deset minut MP3 s 128 kb/s; za večje datoteke agentu dajte povezavo.Obe orodji takoj vrneta transcriptionId, state: "queued" in namig next, ki poimenuje orodje za čakanje. Prepisi, ustvarjeni z agentom, se začnejo zasebno, brez povezave za deljenje.
Agent ne more prenašati prenosa v živo bolj potrpežljivo, kot ga lahko vi; orodje za čakanje bi klical, dokler nekdo ne bi vzel prenosnika. Dokončan posnetek ima konec, in prav tega čakata naslednji par orodij.
Klic orodja je en zahtevek HTTP, zahtevki HTTP pa niso namenjeni trajanju ene ure. Odjemalci jih opustijo, posredniki jih zaprejo, model, ki je blokiran na enem orodju, pa ne more narediti ničesar drugega. Zato je vzorec za vsako dolgo opravilo za MCP enak kot pri REST API: zaženete opravilo in dobite ročico, na njo čakate omejen čas in klicete znova, če še ni končano. Stanje nosi ročica, ne povezava.
wait_for_transcription čaka, dokler opravilo ni done ali failed, ali dokler ne poteče timeoutS (privzeto 50 sekund, največ 60, kar klic ohrani pod časovnimi omejitvami, ki jih uporablja večina odjemalcev in posrednikov). Če rezultat pravi timedOut: true, opravilo še teče in agent orodje pokliče znova. Medtem ko orodje čaka, strežnik pošilja obvestila o napredku MCP, če jih je odjemalec zahteval: odstotek in fazo, na primer »pridobivanje 3.1 / 8.0 MB« ali »prepisovanje 01:25 od 02:00«.get_transcription vrne stanje in, ko je končano, besedilo. format: "text" da eno vrstico na segment v obliki [mm:ss] Speaker 1: ...; "segments" da časovno označene vrstice s start, end, speaker in speakerName; includeWords: true doda časovne oznake besed. Rezultati so razdeljeni na strani (offset, limit, privzeto 500 segmentov), s nextOffset, kadar jih je še več.Razdelitev na strani je za model, ne za omrežje. Vse, kar orodje vrne, se prilepi v kontekstno okno agenta, kjer tekmuje z vašim pogovorom in stane žetone pri vsakem naslednjem koraku. Dvourno srečanje je na desetine tisoč besed; če bi vse vrnili naenkrat, bi vprašanje, ki ste ga postavili, potisnilo iz konteksta. Dobra orodja MCP vrnejo stran in kazalec ter agentu prepustijo, koliko potrebuje.
Prekinitev povezave ali časovna omejitev opravila nikoli ne prekliče, saj opravilo živi na strežniku, ne v zahtevku MCP. Ko je končano, je opravilo še en vnos v vaši knjižnici, naslednja orodja pa z njim ravnajo kot z vsakim drugim.
list_transcriptions našteje prepise računa, najnovejše najprej, s stanjem in trajanjem; lifecycle je active, archived ali all.search_transcriptions išče, kar je bilo rečeno, po vseh prepisih, v kateremkoli jeziku, in vrne ustrezne vrstice, vsako s svojim prepisom in sekundo, v kateri je bilo izrečeno. transcriptionId zoži iskanje na en prepis; lang doda prevod vsakega zadetka.Najti vrstico je cenejši del. Še dve orodji ugotovita, kaj je bilo rečeno v celoti.
get_summary vrne naslov in povzetek, ki ju pripravi umetna inteligenca, za končan prepis, po želji prevedena z lang. state: "pending" pomeni, da se povzetek še piše (ponavadi je pripravljen v nekaj sekundah po koncu opravila), agent pa vpraša znova.translate_transcription vrne končan prepis v drugem jeziku, kot besedilo ali časovno označene segmente, razdeljen na strani kot get_transcription. Prevodi se shranijo, zato ponovno vprašanje ne ponovi dela.list_voices našteje glasove, ki lahko preberejo prepis v jeziku: id, ime, spol in naglas, kadar je znan, oceno kakovosti ter to, ali je privzeti ali eden vaših kloniranih glasov. Opisuje glasove; ne naredi, da bi kateri koli govoril (več spodaj o tem, česa strežnik ne zmore).Tako se orodja v praksi povezujejo med seboj.
Ko je strežnik dodan, pogovor v Claude Code poteka takole. Prilepite povezavo do podcasta in prosite za bistvo v francoščini.
Agent pokliče transcribe_url:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Dobi nazaj transcriptionId in state: "queued" ter sledi namigu next:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Epizoda s petdesetimi minutami se prepiše veliko hitreje, kot se predvaja, vendar ne znotraj enega čakanja. Prvo čakanje vrne timedOut: true z napredkom, na primer, pri 61 odstotkih, zato agent orodje pokliče še enkrat in dobi state: "done".
Zdaj agent pokliče get_summary z lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Če je povzetek še vedno pending, agent počaka nekaj sekund; sicer vam predloži naslov in povzetek v francoščini. Vprašajte »kje so govorili o cenah?« in pokliče search_transcriptions z query: "pricing" in istim transcriptionId, ter navede ustrezne vrstice z njihovimi časovnimi oznakami. Če prosite za vse v francoščini, pokliče translate_transcription.
Peščica klicev orodij, brez kode, in prepis v vaši knjižnici. Vsak od teh klicev je šel skozi ista vrata kot zahtevek REST, in prav ta vrata določajo račun in omejitve.
Strežnik MCP je API prek drugih vrat: enake omejitve, enak račun.
POST /v1/transcriptions: veljajo hitrost ustvarjanja paketa (10, 100 ali število prepisov na uro po meri), največ sočasnih prepisov (1, 5 ali neomejeno) in njegovo dobroimetje. Dobroimetje $5 ob registraciji pokrije prvo sejo, kartica ni potrebna.isError: true s kodo napake REST API, stavkom, na katerega lahko model ukrepa, ter poljema retryable in retryAfterS. insufficient_credit nosi topUpUrl; rate_limited pove, koliko je treba počakati. To je pomembneje, kot se sliši: model bere besedilo napake, zato stavek, na katerega lahko ukrepa, slepo ulico spremeni v naslednji klic orodja./v1/mcp: zanka agent dobi HTTP 429 z Retry-After, še preden se zažene katero koli orodje.idempotencyKey: ponovna uporaba ključa končanega klica ponovi prvi rezultat, ponovna uporaba z drugačnimi argumenti pa je zavrnjena, tako da agent, ki sam poskuša znova, nikoli ne začne drugega opravila. Vsako orodje, ki porablja denar, bi to moralo ponuditi; agenti poskušajo znova bistveno bolj brezskrbno kot ljudje.To so robovi tistega, kar strežnik počne. Dve stvari pa sta namenoma zunaj tega.
Strežnik nima orodja, ki bi poljubno besedilo spremenilo v govor, in tudi ni načrtovano. VocalStack bere prepise in njihove prevode, z standardnim ali kloniranim glasom, nič drugega. list_voices pove agentu, kateri glasovi lahko preberejo prepis v jeziku, ne pa kako narediti, da glas reče nekaj novega.
Orodja za prepis tudi zavrnejo žive tokove. Živi tok na YouTubu ali radijski tok potrebuje prepis v živo, zagnan z nadzorne plošče ali prek POST /v1/transcriptions/live v referenci API. Končan videoposnetek na YouTubu je datoteka, in transcribe_url jo sprejme.
Če raje sami napišete kodo, prepisovanje datoteke z API prikaže enake korake kot klici HTTP, vadnica za prepis v realnem času pa obravnava WebSocket.