MCP serveris paverčia API keliais vardintais įrankiais, kuriuos agentas kviečia pokalbio metu, o ilgas darbas telpa už vieno, kai įrankis grąžina rankeną, kurios agentas laukia ribotais ėjimais. Įklijuokite podkasto nuorodą, paprašykite esmės prancūzų kalba – ir jokio kodo rašyti nereikės.
Kodavimo agentas gali naudoti VocalStack API kaip bet kuri programa: perskaityti API nuorodą, parašyti kelias eilutes su SDK ir jas paleisti. Tai tinkamas kelias tam, kas veiks ir be agento.
MCP (Model Context Protocol) skirtas kitam atvejui: kai kalbate su asistentu ir norite, kad jis tuoj pat ką nors transkribuotų, be kodo. MCP serveris pateikia trumpą vardintų įrankių sąrašą, kiekvienas su aprašymu ir JSON schema jo argumentams. Agentas sąrašą perskaito vieną kartą ir kreipiasi į įrankį pagal pavadinimą, kai užklausa su juo sutampa. „Transkribuok šį podkastą ir pasakyk, ką jie kalbėjo apie kainas“ tampa trimis įrankių iškvietimais, o agentas HTTP maršruto niekada nemato.
Serveriai būna dviejų rūšių. Vietinis serveris veikia kaip kliento subprocesas ir bendrauja per stdio – taip veikia dauguma failų sistemos ir duomenų bazių serverių. Nuotolinis serveris veikia už URL ir kalba Streamable HTTP protokolu – transportu, kuris 2025 m. kovo mėn. specifikacijos revizija pakeitė senesnį HTTP-plus-SSE (server-sent events) transportą. Klientas siunčia kiekvieną užklausą, o serveris atsako tuo pačiu ryšiu; viskas, ką jis turi pasakyti prieš galutinį rezultatą, siunčiama srautu anksčiau. Bet kuris klientas, parašytas pagal dabartinę specifikaciją, gali naudoti bet kurią rūšį.
VocalStack serveris yra nuotolinės rūšies, adresu {{api}}/v1/mcp, ir jo naudojimas kainuoja tiek, kiek kainuoja API. Jums reikia tik URL.
Atidarykite valdymo skydelio Developers sritį: {{app}}/developers. Pirmame skirtuke Connect an AI agent rodomas serverio URL ir paruoštas nustatymo fragmentas kiekvienam klientui. Trys žemiau pateikti fragmentai atitinka tuos, kurie rodomi ten.
Paleiskite šią komandą savo terminale:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Pridėkite tai prie .cursor/mcp.json savo projekte arba prie ~/.cursor/mcp.json, kad galiotų visiems projektams:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Bet kuris klientas, palaikantis Streamable HTTP, gali pridėti serverį naudodamas šį URL. Tai bendroji forma, kurią rodo valdymo skydelis:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
API rakto nereikia, kad pradėtumėte. Pirmą kartą klientui prisijungus, prisijungiate prie savo VocalStack paskyros naršyklėje, o klientas išsaugo prieigos žetoną. Valdymo skydelis tai pasako vienoje eilutėje: "You'll sign in with your VocalStack account the first time. No key needed."
Tai veikia MCP autorizacijos specifikacija, o ne VocalStack gudrybė. Nuotolinis serveris į neautorizuotą užklausą atsako 401 kodu, nurodančiu į jo apsaugoto išteklių metaduomenis: mažą JSON dokumentą, kuriame nurodomas autorizacijos serveris ir serverio reikalaujami leidimai (scopes). Klientas jį perskaito, naršyklėje atlieka standartinį OAuth 2.1 srautą ir grįžta su žetonu, išduotu tik tam serveriui. Bet kuris MCP nuotolinis serveris, laikantis specifikacijos, prisijungia jus taip pat, todėl minėti klientai gali tai padaryti nieko nežinodami apie VocalStack.
API raktas taip pat veikia, skirtas klientui, veikiančiam serveryje ar skripte. Siųskite jį kaip Authorization: Bearer vs_key_... – tą pačią antraštę, kurią priima REST API. Raktai kuriami skiltyje Developers → API keys. Abu transkribavimo įrankiai reikalauja leidimų Write ir Stream audio. Antrasis skamba keistai failui, bet įrankiai eina per tą patį transkribavimo kūrimo tašką kaip ir kiekvienas transkribavimas, įskaitant tiesioginius, o tas taškas tikrina abu. Skaitymo įrankiams reikalingas Read; list_voices reikia tik galiojančio prisijungimo duomenų.
Prisijungus agentas mato devynis įrankius. Patys jų retai minėsite, bet žinojimas, ką jie daro, paaiškina, ką agentas darys toliau.
Kiekvienas įrankis priima ir grąžina camelCase JSON su tais pačiais laukų pavadinimais kaip /v1 wire tipai; transkribavimo rankena yra jo transcriptionId.
transcribe_url pradeda transkribuoti garso ar vaizdo įrašą viešame URL: failo nuorodą, podkasto epizodą, YouTube vaizdo įrašą. Tiesioginiai srautai nepriimami. Papildomi argumentai: name, spokenLanguage (praleiskite, kad kalba būtų aptikta automatiškai), speakerLabels (auto, on arba off) ir startS/endS, kad būtų transkribuota tik dalis garso.transcribe_file daro tą patį failui, kurį agentas turi, siunčiamam kaip fileBase64 su filename. Dekoduotas dydis ribojamas 10 MiB – maždaug dešimt minučių 128 kbps MP3; didesniam failui duokite agentui nuorodą.Abu grąžina iš karto su transcriptionId, state: "queued" ir next nuoroda, nurodančia laukimo įrankį. Agento sukurtos transkripcijos pradedamos privačios, be bendrinimo nuorodos.
Agentas negali kantriau laukti tiesioginės transliacijos, nei galite jūs; jis kartotų laukimo įrankio iškvietimus, kol kas nors atimtų nešiojamąjį kompiuterį. Baigtas įrašas turi pabaigą – į ją ir laukia kita įrankių pora.
HTTP užklausa yra vienas iškvietimas, o HTTP užklausos nėra skirtos trukti valandą. Klientai jų nebelaukia, tarpiniai serveriai jas nutraukia, o modelis, įstrigęs ties vienu įrankio iškvietimu, negali daryti nieko kito. Todėl bet kuriam ilgam darbui per MCP taikomas tas pats modelis, kurį naudoja ir REST API: pradėti darbą ir gauti rankeną, laukti jo ribotą laiką ir kviesti dar kartą, jei dar nebaigta. Būseną neša rankena, o ne ryšys.
wait_for_transcription blokuoja, kol darbas bus done arba failed, arba kol praeis timeoutS (numatytoji 50 sekundžių, didžiausia 60, kad iškvietimas tilptų į daugumos klientų ir tarpinių serverių taikomus laiko limitus). Jei rezultate timedOut: true, darbas vis dar vyksta, ir agentas kviečia įrankį dar kartą. Kol įrankis laukia, serveris siunčia MCP progreso pranešimus, jei klientas to prašė: procentą ir etapą, pavyzdžiui „fetching 3.1 / 8.0 MB“ arba „transcribing 01:25 of 02:00“.get_transcription grąžina būseną, o baigus – tekstą. format: "text" pateikia po vieną eilutę kiekvienam segmentui kaip [mm:ss] Speaker 1: ...; "segments" pateikia laiko žymėtas eilutes su start, end, speaker ir speakerName; includeWords: true prideda žodžių laikus. Rezultatai dalijami puslapiais (offset, limit, numatytoji 500 segmentų) su nextOffset, kai lieka daugiau.Puslapiavimas skirtas modeliui, ne tinklui. Viskas, ką grąžina įrankis, įklijuojama į agento konteksto langą, kur konkuruoja su jūsų pokalbiu ir kainuoja žetonų kiekviename vėlesniame ėjime. Dviejų valandų susitikimas – dešimtys tūkstančių žodžių; grąžinus viską iš karto, jūsų klausimas iš konteksto būtų išstumtas. Geri MCP įrankiai grąžina puslapį ir žymeklį bei leidžia agentui nuspręsti, kiek jo reikia.
Atsijungimas ar laiko limitas niekada nenutraukia darbo, nes darbas gyvena serveryje, o ne MCP užklausoje. Baigtas darbas tampa dar vienu jūsų bibliotekos įrašu, ir kiti įrankiai su juo elgiasi kaip su bet kuriuo kitu.
list_transcriptions išvardija paskyros transkripcijas, naujausias pirmas, su būsena ir trukme; lifecycle yra active, archived arba all.search_transcriptions ieško, kas buvo pasakyta visose transkripcijose, bet kuria kalba, ir grąžina atitinkančias eilutes, kiekvieną su jos transkripcija ir sekunde, kada tai buvo pasakyta. transcriptionId susiaurina paiešką iki vienos transkripcijos; lang prideda kiekvieno rezultato vertimą.Rasti eilutę – pigi pusė. Dar du įrankiai išsiaiškina, ką visa tai pasakė.
get_summary grąžina baigtos transkripcijos AI pavadinimą ir santrauką, pasirinktinai išverstą su lang. state: "pending" reiškia, kad santrauka dar rašoma (paprastai ji būna paruošta vos per kelias sekundes po darbo pabaigos), ir agentas klausia dar kartą.translate_transcription grąžina baigtą nuorašą kita kalba, kaip tekstą arba laiko žymėtus segmentus, puslapiuojamus kaip get_transcription. Vertimai saugomi, todėl klausti dar kartą nekartoja darbo.list_voices išvardija balsus, kurie gali perskaityti nuorašą tam tikra kalba: id, pavadinimą, lytį ir akcentą, kai jie žinomi, kokybės įvertinimą ir ar tai numatytasis balsas, ar vienas iš jūsų klonuotų balsų. Jis aprašo balsus; jis nepriverčia jo kalbėti (daugiau apie tai, ko serveris nedaro, žemiau).Štai kaip įrankiai veikia kartu praktikoje.
Kai serveris pridėtas, pokalbis Claude Code vyksta taip. Įklijuojate podkasto nuorodą ir prašote esmės prancūzų kalba.
Agentas iškviečia transcribe_url:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Jis gauna transcriptionId ir state: "queued" ir seka next nuorodą:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Penkiasdešimties minučių epizodas transkribuojamas daug kartų greičiau, nei jis groja, bet ne per vieną laukimą. Pirmasis laukimas grąžina timedOut: true su progresu, tarkime, 61 procentas, todėl agentas kviečia įrankį dar kartą ir gauna state: "done".
Dabar agentas kviečia get_summary su lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Jei santrauka vis dar pending, agentas palaukia kelias sekundes; priešingu atveju jis pateikia pavadinimą ir santrauką prancūzų kalba. Paklausus „kur jie kalbėjo apie kainas?“, jis kviečia search_transcriptions su query: "pricing" ir ta pačia transcriptionId, ir cituoja atitinkančias eilutes su laiko žymomis. Paprašius viso teksto prancūzų kalba, jis kviečia translate_transcription.
Keletas įrankių iškvietimų, jokio kodo ir transkripcija jūsų bibliotekoje. Kiekvienas iš šių iškvietimų perėjo per tuos pačius vartus kaip REST užklausa, o tie vartai nustato sąskaitą ir ribas.
MCP serveris yra ta pati API, tik per kitas duris: tos pačios ribos, ta pati sąskaita.
POST /v1/transcriptions: taikomas plano kūrimo greitis (10, 100 arba pasirinktinis skaičius transkripcijų per valandą), jo vienu metu vykstančių transkripcijų riba (1, 5 arba neribota) ir jo kreditas. $5 registracijos kreditas padengia pirmą sesiją, be kortelės.isError: true su REST API klaidos kodu, sakiniu, kurį modelis gali įvykdyti, ir laukais retryable ir retryAfterS. insufficient_credit pateikia topUpUrl; rate_limited nurodo, kiek laukti. Tai svarbiau, nei atrodo: modelis skaito klaidos tekstą, ir sakinys, kurį jis gali įvykdyti, paverčia akligatvį kitu įrankio iškvietimu./v1/mcp užklausai: ciklinantis agentas gauna HTTP 429 su Retry-After dar prieš įrankio paleidimą.idempotencyKey: pakartojus baigto iškvietimo raktą, pakartojamas pirmasis rezultatas, o pakartojus su kitais argumentais – atmetama, todėl agentas, kuris bando savarankiškai, niekada nepradeda antro darbo. Bet kuris įrankis, kuris išleidžia pinigus, turėtų tai siūlyti; agentai kartoja bandymus daug laisviau nei žmonės.Tai ribos to, ką serveris daro. Du dalykai tyčia už jų.
Serveris neturi įrankio, kuris paverstų bet kokį tekstą kalba, ir toks nėra planuojamas. VocalStack kalba nuorašus ir jų vertimus standartiniu ar klonuotu balsu ir nieko kito. list_voices pasako agentui, kurie balsai gali perskaityti nuorašą tam tikra kalba, o ne kaip priversti balsą pasakyti ką nors naujo.
Transkribavimo įrankiai taip pat atmeta tiesioginius srautus. YouTube tiesioginiam srautui ar radijo srautui reikia tiesioginės transkripcijos, pradėtos iš valdymo skydelio arba per POST /v1/transcriptions/live API nuorodoje. Baigtas YouTube vaizdo įrašas yra failas, ir jį priima transcribe_url.
Jei norite patys rašyti kodą, failo transkribavimas su API aprašo tuos pačius veiksmus kaip HTTP iškvietimus, o realiojo laiko pamoka aprašo WebSocket.