’n MCP-bediener verander ’n API in ’n paar benoemde gereedskapstukke wat ’n agent middel-gesprek aanroep, en ’n lang taak pas daarby wanneer die gereedskap ’n handvatsel teruggee waarop die agent in begrensde beurte wag. Plak ’n podcast-skakel, vra vir die kern in Frans, en geen kode word geskryf nie.
’n Kodeeragent kan die VocalStack-API gebruik soos enige program: lees die API-verwysing, skryf ’n paar reëls teen die SDK en laat dit loop. Dit is die regte pad vir iets wat sonder die agent sal loop.
MCP (die Model Context Protocol) is vir die ander geval: jy praat met ’n assistent en wil hê dit moet nou iets transkribeer, sonder kode. ’n MCP-bediener publiseer ’n kort lys benoemde gereedskapstukke, elk met ’n beskrywing en ’n JSON-skema vir sy argumente. Die agent lees die lys een keer en roep ’n gereedskapstuk volgens naam aan wanneer ’n versoek daarby pas. "Transkribeer hierdie podcast en vertel my wat hulle oor pryse gesê het" word drie gereedskapsoproepe, en die agent sien nooit ’n HTTP-roete nie.
Bedieners kom in twee soorte. ’n Plaaslike bediener loop as ’n subproses van die kliënt en praat oor stdio, soos die meeste lêerstelsel- en databasisbedieners werk. ’n Afstandbediener sit agter ’n URL en praat Streamable HTTP, die vervoer wat die ouer HTTP-plus-SSE-vervoer (server-sent events) in die Maart 2025-hersiening van die spesifikasie vervang het. Die kliënt plaas elke versoek, en die bediener antwoord op dieselfde verbinding; enigiets wat dit moet sê voor die finale resultaat, word vooraf gestroom. Enige kliënt wat teen die huidige spesifikasie geskryf is, kan albei soorte gebruik.
VocalStack se bediener is die afstandsoort, by {{api}}/v1/mcp, en om dit te gebruik kos wat die API kos. Al wat jy nodig het, is die URL.
Maak die dashboard se Developers-area oop by {{app}}/developers. Die eerste oortjie, Connect an AI agent, wys die bediener-URL en ’n opstellingsfragment vir elke kliënt. Die drie fragmente hieronder stem ooreen met dié wat daar gewys word.
Voer dit in jou terminaal uit:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Voeg dit by .cursor/mcp.json in jou projek, of by ~/.cursor/mcp.json vir elke projek:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Enige kliënt wat Streamable HTTP ondersteun, kan die bediener met hierdie URL byvoeg. Dit is die generiese vorm wat die dashboard wys:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Jy het nie ’n API-sleutel nodig om te begin nie. Die eerste keer as die kliënt koppel, meld jy aan met jou VocalStack-rekening in die blaaier, en die kliënt hou die token. Die dashboard sê dit in een reël: "You'll sign in with your VocalStack account the first time. No key needed."
Dit is MCP se magtigingsspesifikasie aan die werk, nie ’n VocalStack-kunsgreep nie. ’n Afstandbediener antwoord ’n onbekragtigde versoek met ’n 401 wat na sy metadata vir beskermde hulpbronne wys: ’n klein JSON-dokument wat die magtigingsbediener en die omvang (scopes) noem wat die bediener vereis. Die kliënt lees dit, loop ’n standaard OAuth 2.1-vloei in jou blaaier, en kom terug met ’n token wat net vir daardie bediener uitgereik is. Enige afstand-MCP-bediener wat die spesifikasie volg, meld jou op dieselfde manier aan, en daarom kan die kliënte hierbo dit doen sonder om iets van VocalStack te weet.
’n API-sleutel werk ook, vir ’n kliënt wat op ’n bediener of in ’n skrip loop. Stuur dit as Authorization: Bearer vs_key_..., dieselfde kopstuk wat die REST-API gebruik. Sleutels word onder Developers → API keys geskep. Die twee transkribeer-gereedskapstukke het die Write- en Stream audio-regte nodig. Die tweede klink vreemd vir ’n lêer, maar die gereedskap gaan deur dieselfde skeppingspunt as elke transkripsie, insluitend regstreekse een, en daardie punt kontroleer albei. Die leesgereedskap benodig Read; list_voices benodig net ’n geldige magtiging.
Sodra jy aangemeld is, sien die agent nege gereedskapstukke. Jy sal hulle selde self noem, maar as jy hulle ken, verstaan jy wat die agent daarna doen.
Elke gereedskapstuk neem camelCase-JSON en gee dit terug, met dieselfde veldname as die /v1-draadtipes; ’n transkripsie se handvatsel is sy transcriptionId.
transcribe_url begin met die transkribeer van oudio of video by ’n openbare URL: ’n lêerskakel, ’n podcast-episode, ’n YouTube-video. Regstreekse strome word nie aanvaar nie. Opsionele argumente: name, spokenLanguage (laat dit weg om die taal te laat opspoor), speakerLabels (auto, on of off) en startS/endS om net ’n deel van die oudio te transkribeer.transcribe_file doen dieselfde vir ’n lêer wat die agent hou, gestuur as fileBase64 met sy filename. Die gedekodeerde grootte is beperk tot 10 MiB, ongeveer tien minute 128 kbps-MP3; vir enigiets groter, gee die agent ’n skakel.Albei gee dadelik die transcriptionId, state: "queued" en ’n next-wenk wat die wagtoel noem, terug. Transkripsies wat deur die agent geskep word, begin privaat, sonder ’n deelskakel.
’n Agent kan nie geduldiger by ’n regstreekse uitsending sit as wat jy kan nie; dit sou die wagtoel aanhou roep totdat iemand die skootrekenaar wegneem. ’n Voltooide opname het ’n einde, en dit is waarvoor die volgende paar gereedskapstukke wag.
’n Gereedskapsoproep is een HTTP-versoek, en HTTP-versoeke is nie bedoel om ’n uur te duur nie. Kliënte gee op daarvoor, proxies sluit dit, en ’n model wat op een gereedskapstuk vasgekeer is, kan niks anders doen nie. Die patroon vir enige lang taak agter MCP is dus dieselfde een wat die REST-API gebruik: begin die taak en kry ’n handvatsel, wag daarop vir ’n begrensde tyd, en roep weer as dit nie klaar is nie. Die handvatsel, nie die verbinding nie, dra die toestand.
wait_for_transcription hou aan totdat die taak done of failed is, of totdat timeoutS verbygaan (standaard 50 sekondes, maksimum 60, wat die oproep onder die tydlimiete hou wat die meeste kliënte en proxies toepas). As die resultaat timedOut: true sê, loop die taak nog en roep die agent die gereedskap weer. Terwyl die gereedskap wag, stuur die bediener MCP-vorderingskennisgewings as die kliënt daarom gevra het: ’n persentasie en ’n fase soos "fetching 3.1 / 8.0 MB" of "transcribing 01:25 of 02:00".get_transcription gee die status terug en, wanneer dit klaar is, die teks. format: "text" gee een reël per segment as [mm:ss] Speaker 1: ...; "segments" gee getydmerkte reëls met start, end, speaker en speakerName; includeWords: true voeg woordtydsberekeninge by. Resultate word in bladsye verdeel (offset, limit, standaard 500 segmente) met ’n nextOffset wanneer meer oor is.Die bladsyverdeling is daar vir die model, nie vir die netwerk nie. Alles wat ’n gereedskapstuk teruggee, word in die agent se konteksvenster geplak, waar dit met jou gesprek meeding en op elke latere beurt tokens kos. ’n Vergadering van twee uur is tienduisende woorde; as dit alles op een slag teruggegee word, sal die vraag wat jy gevra het uit die konteks gedruk word. Goeie MCP-gereedskapstukke gee een bladsy en ’n kursor terug en laat die agent besluit hoeveel dit nodig het.
’n Ontkoppeling of ’n tydsoorskryding kanselleer nooit die taak nie, want die taak leef op die bediener, nie in die MCP-versoek nie. Sodra dit klaar is, is die taak nog ’n inskrywing in jou biblioteek, en die volgende gereedskapstukke hanteer dit soos enige ander.
list_transcriptions lys die rekening se transkripsies, nuutste eerste, met status en duur; lifecycle is active, archived of all.search_transcriptions soek wat gesê is oor elke transkripsie, in enige taal, en gee die passende reëls terug, elk met sy transkripsie en die sekonde waarin dit gesê is. transcriptionId beperk die soektog tot een transkripsie; lang voeg ’n vertaling van elke treffer by.Om ’n reël te vind is die goedkoop helfte. Twee gereedskapstukke werk uit wat die hele ding gesê het.
get_summary gee die KI-titel en opsomming van ’n voltooide transkripsie terug, opsioneel vertaal met lang. state: "pending" beteken die opsomming word nog geskryf (dit is gewoonlik binne sekondes nadat die taak klaar is gereed), en die agent vra weer.translate_transcription gee ’n voltooide transkripsie in ’n ander taal terug, as teks of getydmerkte segmente, in bladsye soos get_transcription. Vertalings word gestoor, so as jy weer vra, word die werk nie herhaal nie.list_voices lys die stemme wat ’n transkripsie in ’n taal kan voorlees: id, naam, geslag en aksent wanneer bekend, ’n gehalte-gradering, en of dit die standaard is of een van jou gekloonde stemme. Dit beskryf stemme; dit laat nie een praat nie (meer hieronder oor wat die bediener nie doen nie).Hier is hoe die gereedskapstukke in die praktyk aanmekaar koppel.
Sodra die bediener bygevoeg is, verloop ’n gesprek in Claude Code so. Jy plak ’n podcast-skakel en vra vir die kern in Frans.
Die agent roep transcribe_url aan:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Dit kry ’n transcriptionId en state: "queued" terug, en volg die next-wenk:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
’n Episode van vyftig minute word baie keer vinniger getranskribeer as wat dit speel, maar nie binne een wag nie. Die eerste wag gee timedOut: true terug met vordering van, sê nou maar, 61 persent, so die agent roep die gereedskap nog een keer en kry state: "done".
Nou roep die agent get_summary met lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
As die opsomming nog pending is, wag die agent ’n paar sekondes; anders gee dit jou ’n titel en opsomming in Frans. Vra "waar het hulle oor pryse gepraat?" en dit roep search_transcriptions met query: "pricing" en dieselfde transcriptionId, en haal die passende reëls met hul tydstempels aan. Vra vir die hele ding in Frans en dit roep translate_transcription aan.
’n Handjie gereedskapsoproepe, geen kode nie, en ’n transkripsie in jou biblioteek. Elkeen van daardie oproepe het dieselfde hekke as ’n REST-versoek deurgegaan, en daardie hekke bepaal die rekening en die limiete.
Die MCP-bediener is die API deur ’n ander voordeur: dieselfde limiete, dieselfde rekening.
POST /v1/transcriptions: die plan se skeppingstempo (10, 100 of ’n pasgemaakte aantal transkripsies wat per uur begin word), sy limiet vir gelyktydige transkripsies (1, 5 of onbeperk) en sy krediet is almal van toepassing. Die $5-registrasiekrediet dek ’n eerste sessie, geen kaart nodig nie.isError: true terug met die REST-API se foutkode, ’n sin waarop die model kan optree, en die velde retryable en retryAfterS. insufficient_credit dra ’n topUpUrl; rate_limited sê hoe lank om te wag. Dit is belangriker as wat dit klink: ’n model lees die foutteks, so ’n sin waarop dit kan optree, verander ’n doodloopstraat in die volgende gereedskapsoproep./v1/mcp-versoek self: ’n lusagent kry ’n HTTP 429 met Retry-After voordat enige gereedskap loop.idempotencyKey: die sleutel van ’n voltooide oproep weer te gebruik, herhaal die eerste resultaat, en dit weer met ander argumente te gebruik word geweier, so ’n agent wat op sy eie weer probeer, begin nooit ’n tweede taak nie. Enige gereedskapstuk wat geld uitgee, behoort dit aan te bied; agente probeer baie vryer weer as mense.Dit is die grense van wat die bediener doen. Twee dinge val opsetlik buite hulle.
Die bediener het geen gereedskapstuk wat willekeurige teks in spraak omskakel nie, en geen is beplan nie. VocalStack praat transkripsies en hul vertalings, in ’n standaard- of gekloonde stem, en niks anders nie. list_voices vertel ’n agent watter stemme ’n transkripsie in ’n taal kan voorlees, nie hoe om ’n stem iets nuuts te laat sê nie.
Die transkribeer-gereedskap weier ook regstreekse strome. ’n YouTube-regstreekse stroom of ’n radiostroom benodig ’n regstreekse transkripsie, begin vanaf die dashboard of deur POST /v1/transcriptions/live in die API-verwysing. ’n Voltooide YouTube-video is ’n lêer, en transcribe_url neem dit.
As jy die kode liewer self wil skryf, loop ’n lêer met die API transkribeer dieselfde stappe as HTTP-oproepe deur, en die regstydse tutoriaal dek die WebSocket.