MCP-server muudab API mõneks nimega tööriistaks, mida agent kutsub vestluse ajal, ja pikk töö mahub sinna ära, kui tööriist annab tagasi käepideme, mida agent ootab piiratud ajavahemikes. Kleebi podcasti link, palu lühikokkuvõtet prantsuse keeles ja koodi ei pea kirjutama.
Koodiabiline agent saab VocalStacki API-d kasutada nagu iga teine programm: loeb läbi API viite, kirjutab SDK-ga paar rida koodi ja käivitab need. Kui midagi peab töötama ilma agendita, on see õige tee.
MCP (Model Context Protocol) on mõeldud teiseks juhuks: sa suhtled assistendiga ja tahad, et ta transkribeeriks midagi kohe, ilma koodita. MCP-server avaldab lühikese nimekirja nimega tööriistu, igaühel kirjeldus ja argumentide JSON-skeem. Agent loeb nimekirja korra ning kutsub tööriista nime järgi, kui päring sobib. „Transkribeeri see podcast ja ütle, mida nad hindade kohta rääkisid“ muutub kolmeks tööriistakutsungiks, ja agent ei näe kunagi HTTP-marsruuti.
Servereid on kahte liiki. Kohalik server töötab kliendi alamprotsessina ja suhtleb stdio kaudu, nii toimivad enamik failisüsteemi- ja andmebaasiservereid. Kaugserver asub URL-i taga ja räägib Streamable HTTP-d, transporti, mis asendas vanema HTTP-plus-SSE (server-sent events) transpordi spetsifikatsiooni 2025. aasta märtsi versioonis. Klient saadab iga päringu ning server vastab samas ühenduses; kõik, mida server peab enne lõpptulemust ütlema, voogesitatakse selle ette. Iga praeguse spetsifikatsiooniga kirjutatud klient oskab kasutada kumbagi liiki.
VocalStacki server on kaugserveri tüüpi, aadressil {{api}}/v1/mcp, ja selle kasutamine maksab sama, mis API kasutamine. Vaja on ainult URL-i.
Ava Dashboardi arendajate ala aadressil {{app}}/developers. Esimene sakk Connect an AI agent näitab serveri URL-i ja seadistuskatkendit iga kliendi jaoks. Allolevad kolm katkendit vastavad sellele, mis seal kuvatakse.
Käivita see oma terminalis:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Lisa see oma projekti kausta faili .cursor/mcp.json või kõigi projektide jaoks faili ~/.cursor/mcp.json:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Iga klient, mis toetab Streamable HTTP-d, saab serveri lisada selle URL-iga. See on üldine vorm, mida Dashboard kuvab:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Alustamiseks pole API-võtit vaja. Kliendi esimesel ühendumisel logid brauseris sisse oma VocalStacki kontoga ja klient hoiab tokenit alles. Dashboard ütleb selle ühe reaga: „Logid esimesel korral sisse oma VocalStacki kontoga. Võtit pole vaja.“
See on MCP autoriseerimisspetsifikatsiooni töö, mitte VocalStacki nipp. Kaugserver vastab autentimata päringule 401-vastusega, mis viitab tema kaitstud ressursi metaandmetele: väikesele JSON-dokumendile, mis nimetab autoriseerimisserveri ja serveri nõutavad skoobid. Klient loeb selle, käivitab brauseris standardse OAuth 2.1 voo ja tuleb tagasi tokeniga, mis on välja antud ainult sellele serverile. Iga MCP-kaugserver, mis järgib spetsifikatsiooni, lubab sul sisse logida samamoodi, ja sellepärast saavad ülaltoodud kliendid seda teha, teadmata VocalStacki kohta midagi.
API-võti töötab samuti kliendi puhul, mis jookseb serveris või skriptis. Saada see päisega Authorization: Bearer vs_key_..., sama päisega, mida võtab vastu REST API. Võtmed luuakse jaotises Developers → API keys. Kaks transkribeerimistööriista vajavad õigusi Write ja Stream audio. Teine kõlab failide puhul kummaliselt, aga tööriistad läbivad samad loomispunkti nagu iga transkriptsioon, sealhulgas otsepõhised, ja see punkt kontrollib mõlemat. Lugemistööriistad vajavad Read-õigust; list_voices vajab ainult kehtivat volitust.
Kui oled sisse logitud, näeb agent üheksat tööriista. Sa nimetad neid harva ise, aga nende tundmine selgitab, mida agent järgmiseks teeb.
Iga tööriist võtab ja tagastab camelCase JSON-i, kus väljanimed on samad, mis /v1 andmetüüpides; transkriptsiooni käepide on tema transcriptionId.
transcribe_url alustab helifaili või video transkribeerimist avalikul URL-il: faililink, podcasti episood, YouTube'i video. Otseülekandeid ei võeta vastu. Valikulised argumendid: name, spokenLanguage (jäta välja, et keel tuvastataks), speakerLabels (auto, on või off) ning startS/endS, et transkribeerida ainult osa helist.transcribe_file teeb sama faili puhul, mille agent on enda käes, saadetud kujul fileBase64 koos nimega filename. Dekodeeritud suurus on piiratud 10 MiB-ga, umbes kümme minutit 128 kbps MP3-d; suuremate failide puhul anna agendile link.Mõlemad tagastavad kohe transcriptionId, state: "queued" ja vihje next, mis nimetab ootetööriista. Agendi loodud transkriptsioonid algavad privaatsena, ilma jagamislingita.
Agent ei suuda otseülekannet kannatlikumalt oodata kui sina; ta kutsuks ootetööriista, kuni keegi võtaks sülearvuti ära. Lõppenud salvestisel on lõpp, ja just seda järgmine tööriistapaar ootab.
Tööriistakutse on üks HTTP-päring ja HTTP-päringud ei ole mõeldud tundideks kestma. Kliendid annavad need alla, proksid sulgevad need ja mudel, mis ootab ühte tööriista, ei saa midagi muud teha. Seega on MCP taga iga pikaajalise töö muster sama, mida kasutab ka REST API: alusta tööd ja saa käepide, oota seda piiratud aja jooksul ning kutsu uuesti, kui ei ole valmis. Olekut kannab käepide, mitte ühendus.
wait_for_transcription ootab, kuni töö on done või failed, või kuni timeoutS möödub (vaikimisi 50 sekundit, maksimum 60, mis hoiab kutse enamike klientide ja proksite ajalimiitide all). Kui tulemus ütleb timedOut: true, töötab töö veel ja agent kutsub tööriista uuesti. Kui klient seda palus, saadab server ootamise ajal MCP-edenemisteavitusi: protsendi ja faasi, näiteks „laadib alla 3,1 / 8,0 MB“ või „transkribeerib 01:25 / 02:00“.get_transcription tagastab oleku ja pärast valmimist teksti. format: "text" annab ühe rea segmendi kohta kujul [mm:ss] Speaker 1: ...; "segments" annab ajastatud read väljadega start, end, speaker ja speakerName; includeWords: true lisab sõnade ajastused. Tulemused on lehtedeks jaotatud (offset, limit, vaikimisi 500 segmenti), ja kui jääb veel, on olemas nextOffset.Lehtedeks jaotus on mudeli, mitte võrgu jaoks. Kõik, mida tööriist tagastab, kleebitakse agendi kontekstiaknasse, kus see konkureerib sinu vestlusega ja maksab tokeneid igal järgneval pöördel. Kahetunnine koosolek on kümneid tuhandeid sõnu; kui tagastada see kõik korraga, lükkaks see sinu küsimuse kontekstist välja. Head MCP-tööriistad tagastavad lehe ja kursori ning jätavad agendi otsustada, kui palju tal vaja on.
Ühenduse katkemine või ajalimiit ei tühista tööd, sest töö elab serveris, mitte MCP-päringus. Kui see on valmis, on see üks kirje sinu teegis ja järgmised tööriistad käsitlevad seda nagu iga teist.
list_transcriptions loetleb konto transkriptsioonid uuemast vanemani, koos oleku ja kestusega; lifecycle on active, archived või all.search_transcriptions otsib kõigi transkriptsioonide hulgast, mida öeldi, mis tahes keeles, ja tagastab sobivad read, igaühega transkriptsiooni ja sekundi, millal see öeldi. transcriptionId piirab otsingu ühele transkriptsioonile; lang lisab iga tabamuse tõlke.Rea leidmine on odavam pool. Kaks tööriista veel selgitavad välja, mida kogu jutt ütles.
get_summary tagastab lõppenud transkriptsiooni AI pealkirja ja kokkuvõtte, soovi korral tõlgituna parameetriga lang. state: "pending" tähendab, et kokkuvõtet alles kirjutatakse (see on tavaliselt valmis sekunditega pärast töö lõppu), ja agent küsib uuesti.translate_transcription tagastab valmis transkripti teises keeles, kas tekstina või ajastatud segmentidena, lehtedeks jaotatuna nagu get_transcription. Tõlked salvestatakse, nii et uuesti küsimine ei korda tööd.list_voices loetleb hääled, mis suudavad lugeda transkripti antud keeles: ID, nime, soo ja aktsendi, kui need on teada, kvaliteedihinnangu ning selle, kas hääl on vaikimisi või üks sinu kloonitud häältest. See kirjeldab hääli; ta ei pane kedagi rääkima (allpool lisaks, mida server ei tee).Siin on, kuidas tööriistad praktikas koos töötavad.
Kui server on lisatud, käib vestlus Claude Codes nii. Kleebid podcasti lingi ja palud lühikokkuvõtet prantsuse keeles.
Agent kutsub transcribe_url:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Ta saab tagasi transcriptionId ja state: "queued" ning järgib vihjet next:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Viiekümne minuti pikkust episoodi transkribeeritakse mitu korda kiiremini, kui see mängib, aga mitte ühe ootamise jooksul. Esimene ootamine tagastab timedOut: true ja edenemise, näiteks 61 protsenti, nii et agent kutsub tööriista veel korra ja saab state: "done".
Nüüd kutsub agent get_summary parameetriga lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Kui kokkuvõte on ikka pending, ootab agent mõned sekundid; muidu annab ta sulle pealkirja ja kokkuvõtte prantsuse keeles. Küsi „kus nad hinnast rääkisid?“ ja ta kutsub search_transcriptions parameetriga query: "pricing" ja sama transcriptionId, ning tsiteerib sobivaid ridu koos ajatemplitega. Küsi kogu teksti prantsuse keeles ja ta kutsub translate_transcription.
Mõni tööriistakutse, ilma koodita, ja transkriptsioon sinu teegis. Iga nendest kutsetest läbis samad väravad mis REST-päring ning need väravad määravad arve ja piirangud.
MCP-server on API teisest uksest: samad piirangud, sama arve.
POST /v1/transcriptions: kehtivad paketi loomiskiirus (tunnis alustatud 10, 100 või kohandatud arv transkriptsioone), samaaegsete transkribeerimiste piirang (1, 5 või piiramatu) ja krediit. $5 registreerimiskrediit katab esimese seansi, kaarti pole vaja.isError: true koos REST API veakoodiga, lausega, millega mudel saab midagi peale hakata, ning väljadega retryable ja retryAfterS. insufficient_credit kannab topUpUrl-i; rate_limited ütleb, kui kaua oodata. See on tähtsam, kui tundub: mudel loeb veateksti, ja lause, millega ta saab midagi peale hakata, muudab umbtee järgmiseks tööriistakutseks./v1/mcp endale: tsükliv agent saab HTTP 429 koos päisega Retry-After enne, kui ükski tööriist käivitub.idempotencyKey-i: lõpetatud kutse võtme taaskasutamine taasesitab esimese tulemuse ning võtme kasutamine teiste argumentidega lükatakse tagasi, nii et agent, mis proovib ise uuesti, ei alusta kunagi teist tööd. Iga tööriist, mis raha kulutab, peaks seda pakkuma; agendid proovivad uuesti palju vabamalt kui inimesed.Need on serveri piirid. Kaks asja jäävad nende taha tahtlikult.
Serveril pole tööriista, mis teeb suvalise teksti kõneks, ega seda ka ei plaanita. VocalStack räägib transkripte ja nende tõlkeid valmis- või kloonitud häälega ning mitte midagi muud. list_voices ütleb agendile, millised hääled suudavad transkripti antud keeles lugeda, mitte seda, kuidas panna hääl midagi uut ütlema.
Transkribeerimistööriistad keelduvad ka otseülekannetest. YouTube'i otseülekanne või raadiovoog nõuab reaalajas transkribeerimist, mis käivitatakse Dashboardist või kaudu POST /v1/transcriptions/live API viites. Lõppenud YouTube'i video on fail ja transcribe_url võtab selle vastu.
Kui eelistad koodi ise kirjutada, käib failitranskribeerimine API-ga samad sammud läbi HTTP-päringutena ja reaalajas õpetus käsitleb WebSocketi.