MCP serveris pārvērš API par dažiem nosauktiem rīkiem, ko aģents izsauc sarunas laikā, un garu darbu var ievietot aiz viena no tiem, ja rīks atdod rokturi, uz kuru aģents gaida ierobežotos gājienos. Ielīmējiet podkāsta saiti, lūdziet kopsavilkumu franču valodā, un kods nav jāraksta.
Kodēšanas aģents var izmantot VocalStack API tāpat kā jebkura programma: izlasīt API atsauci, uzrakstīt dažas rindas, izmantojot SDK, un tās palaist. Tas ir pareizais ceļš, ja kods darbosies bez aģenta.
MCP (Model Context Protocol) ir paredzēts citam gadījumam: jūs sarunājaties ar asistentu un vēlaties, lai tas kaut ko tagad transkribē, bez koda. MCP serveris publicē īsu nosaukto rīku sarakstu, un katram ir apraksts un argumentu JSON shēma. Aģents sarakstu nolasa vienreiz un izsauc rīku pēc nosaukuma, kad pieprasījums ar to sakrīt. „Transkribē šo podkāstu un pastāsti, ko viņi teica par cenām” kļūst par trim rīku izsaukumiem, un aģents HTTP maršrutu nekad neredz.
Serveri ir divu veidu. Lokālais serveris darbojas kā klienta apakšprocess un sazinās caur stdio, un tā darbojas lielākā daļa failu sistēmu un datubāzu serveru. Attālais serveris atrodas aiz URL un runā ar Streamable HTTP, transportu, kas 2025. gada marta specifikācijas versijā aizstāja vecāko HTTP plus SSE (server-sent events) transportu. Klients nosūta katru pieprasījumu, un serveris atbild tajā pašā savienojumā; viss, ko tas vēlas pateikt pirms gala rezultāta, tiek straumēts priekšā. Jebkurš klients, kas rakstīts pret pašreizējo specifikāciju, var izmantot abus veidus.
VocalStack serveris ir attālais veids, un tas atrodas {{api}}/v1/mcp, un tā izmantošana maksā tikpat, cik maksā API. Vajag tikai URL.
Atveriet vadības paneļa Izstrādātāju sadaļu pie {{app}}/developers. Pirmajā cilnē Connect an AI agent ir redzams servera URL un iestatīšanas fragments katram klientam. Zemāk esošie trīs fragmenti atbilst tiem, kas redzami tur.
Palaidiet šo savā termināļā:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Pievienojiet šo failam .cursor/mcp.json savā projektā vai failam ~/.cursor/mcp.json, lai tas attiektos uz visiem projektiem:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Jebkurš klients, kas atbalsta Streamable HTTP, var pievienot serveri ar šo URL. Šī ir vispārīgā forma, ko rāda vadības panelis:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Lai sāktu, API atslēga nav vajadzīga. Pirmajā klienta savienojuma reizē jūs pieteicaties savā VocalStack kontā pārlūkprogrammā, un klients glabā marķieri. Vadības panelis to pasaka vienā rindā: „Pirmajā reizē pieteiksieties ar savu VocalStack kontu. Atslēga nav vajadzīga.”
Tā ir MCP autorizācijas specifikācija darbībā, nevis VocalStack triks. Attālais serveris uz neautentificētu pieprasījumu atbild ar 401, kas norāda uz tā aizsargātā resursa metadatiem: īsu JSON dokumentu, kurā nosaukts autorizācijas serveris un tam nepieciešamie tvērumi. Klients to nolasa, pārlūkprogrammā palaiž standarta OAuth 2.1 plūsmu un atgriežas ar marķieri, kas izdots tikai šim serverim. Jebkurš attālais MCP serveris, kas ievēro specifikāciju, pieteic jūs tādā pašā veidā, tāpēc iepriekš minētie klienti to var darīt, nezinot neko par VocalStack.
API atslēga arī darbojas klientam, kas darbojas serverī vai skriptā. Sūtiet to kā Authorization: Bearer vs_key_..., tādu pašu galvenes lauku, ko pieņem REST API. Atslēgas tiek izveidotas sadaļā Developers → API keys. Abiem transkribēšanas rīkiem nepieciešamas atļaujas Write un Stream audio. Otrā šķiet dīvaina failam, bet rīki iet caur to pašu izveides punktu kā katra transkripcija, arī tiešraides, un šis punkts pārbauda abas. Lasīšanas rīkiem nepieciešama Read; list_voices pietiek ar derīgu pilnvarojumu.
Kad esat pieteicies, aģents redz deviņus rīkus. Jūs tos reti nosauksiet paši, bet, zinot tos, var saprast, ko aģents dara tālāk.
Katrs rīks pieņem un atgriež camelCase JSON ar tādiem pašiem lauku nosaukumiem kā /v1 datu tipi; transkripcijas rokturis ir tās transcriptionId.
transcribe_url sāk audio vai video transkribēšanu publiskā URL: failu saitē, podkāsta epizodē vai YouTube video. Tiešraides straumes netiek pieņemtas. Neobligātie argumenti: name, spokenLanguage (izlaidiet, lai noteiktu valodu), speakerLabels (auto, on vai off) un startS/endS, lai transkribētu tikai daļu no audio.transcribe_file dara to pašu failam, ko aģents glabā, nosūtot to kā fileBase64 ar filename. Atkodētais izmērs ir ierobežots līdz 10 MiB, aptuveni desmit minūtēm 128 kbps MP3; lielākam failam dodiet aģentam saiti.Abi uzreiz atgriež transcriptionId, state: "queued" un next norādi ar gaidīšanas rīka nosaukumu. Aģenta izveidotās transkripcijas sākas privātas, bez kopīgošanas saites.
Aģents tiešraides pārraidi nevar noklausīties pacietīgāk nekā jūs; tas turpinātu izsaukt gaidīšanas rīku, līdz kāds paņemtu klēpjdatoru. Pabeigtam ierakstam ir beigas, un uz to gaida nākamais rīku pāris.
Rīka izsaukums ir viens HTTP pieprasījums, un HTTP pieprasījumiem nav paredzēts ilgt stundu. Klienti no tiem atkāpjas, starpniekserveri tos aizver, un modelis, kas bloķēts uz viena rīka, nevar darīt neko citu. Tāpēc jebkura gara darba modelis aiz MCP ir tāds pats, kādu izmanto arī REST API: sākt darbu un saņemt rokturi, gaidīt uz to ierobežotu laiku un izsaukt vēlreiz, ja darbs nav pabeigts. Stāvokli nes rokturis, nevis savienojums.
wait_for_transcription gaida, līdz darbs ir done vai failed, vai līdz timeoutS beigām (noklusējums 50 sekundes, maksimums 60, kas notur izsaukumu zem laika ierobežojumiem, ko piemēro vairums klientu un starpniekserveru). Ja rezultātā ir timedOut: true, darbs vēl notiek, un aģents izsauc rīku vēlreiz. Kamēr rīks gaida, serveris, ja klients to pieprasījis, sūta MCP progresa paziņojumus: procentus un fāzi, piemēram, „ielādē 3.1 / 8.0 MB” vai „transkribē 01:25 no 02:00”.get_transcription atgriež statusu un, kad darbs pabeigts, tekstu. format: "text" dod vienu rindu katram segmentam kā [mm:ss] Speaker 1: ...; "segments" dod laikā norādītas rindas ar start, end, speaker un speakerName; includeWords: true pievieno vārdu laikus. Rezultāti tiek lapoti (offset, limit, noklusējums 500 segmenti) ar nextOffset, ja vēl ir palikušas.Lapošana ir domāta modelim, nevis tīklam. Viss, ko rīks atgriež, tiek ielīmēts aģenta konteksta logā, kur tas konkurē ar jūsu sarunu un katrā nākamajā gājienā maksā žetonus. Divu stundu sapulce ir desmitiem tūkstošu vārdu; ja tas viss tiktu atgriezts uzreiz, jautājums, ko uzdevāt, izspiestos no konteksta. Labi MCP rīki atgriež lapu un kursoru un ļauj aģentam izlemt, cik tam vajag.
Savienojuma pārtraukums vai laika ierobežojums nekad neatceļ darbu, jo darbs dzīvo serverī, nevis MCP pieprasījumā. Kad tas pabeigts, darbs ir vēl viens ieraksts jūsu bibliotēkā, un nākamie rīki to apstrādā kā jebkuru citu.
list_transcriptions uzskaita konta transkripcijas, jaunākās pirmās, ar statusu un ilgumu; lifecycle ir active, archived vai all.search_transcriptions meklē, kas ir teikts visās transkripcijās jebkurā valodā, un atgriež atbilstošās rindas, katru ar tās transkripciju un sekundi, kad tas tika teikts. transcriptionId sašaurina meklēšanu līdz vienai transkripcijai; lang pievieno katra trāpījuma tulkojumu.Rindas atrašana ir vieglākā puse. Vēl divi rīki noskaidro, ko teikts visā ierakstā.
get_summary atgriež pabeigtas transkripcijas AI nosaukumu un kopsavilkumu, pēc izvēles tulkotu ar lang. state: "pending" nozīmē, ka kopsavilkums vēl tiek rakstīts (parasti tas ir gatavs sekunžu laikā pēc darba pabeigšanas), un aģents jautā vēlreiz.translate_transcription atgriež pabeigtu transkriptu citā valodā kā tekstu vai laikā norādītus segmentus, lapotu kā get_transcription. Tulkojumi tiek saglabāti, tāpēc, jautājot vēlreiz, darbs netiek atkārtots.list_voices uzskaita balsis, kas var nolasīt transkriptu valodā: id, nosaukumu, dzimumu un akcentu, ja tie zināmi, kvalitātes vērtējumu un to, vai balss ir noklusējuma balss vai viena no jūsu klonētajām balsīm. Tas apraksta balsis; tas neliek kādai runāt (vairāk par to, ko serveris nedara, zemāk).Tālāk redzams, kā rīki praksē savienojas.
Kad serveris ir pievienots, saruna programmā Claude Code notiek šādi. Jūs ielīmējat podkāsta saiti un lūdzat kopsavilkumu franču valodā.
Aģents izsauc transcribe_url:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Tas saņem transcriptionId un state: "queued" un seko next norādei:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Piecdesmit minūšu epizode tiek transkribēta daudzkārt ātrāk, nekā tā skan, bet ne vienā gaidīšanas reizē. Pirmā gaidīšana atgriež timedOut: true ar progresu, piemēram, 61 procentu, tāpēc aģents izsauc rīku vēlreiz un saņem state: "done".
Tagad aģents izsauc get_summary ar lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Ja kopsavilkums joprojām ir pending, aģents dažas sekundes gaida; citādi tas jums iedod nosaukumu un kopsavilkumu franču valodā. Ja jautājat „kur viņi runāja par cenām?”, tas izsauc search_transcriptions ar query: "pricing" un to pašu transcriptionId un citē atbilstošās rindas ar to laikzīmēm. Ja pieprasāt visu franču valodā, tas izsauc translate_transcription.
Dažas rīku izsaukumi, bez koda un transkripcija jūsu bibliotēkā. Katrs no šiem izsaukumiem gāja caur tiem pašiem vārtiem kā REST pieprasījums, un šie vārti nosaka rēķinu un ierobežojumus.
MCP serveris ir tas pats API, tikai caur citām durvīm: tie paši ierobežojumi, tas pats rēķins.
POST /v1/transcriptions: piemēro plāna izveides ātrumu (10, 100 vai pielāgotu skaitu transkripciju, kas sāktas stundā), tā vienlaicīgo transkripciju ierobežojumu (1, 5 vai neierobežotu) un tā kredītu. $5 reģistrācijas kredīts sedz pirmo sesiju, kartes nav vajadzīgas.isError: true ar REST API kļūdas kodu, teikumu, pēc kura modelis var rīkoties, un laukiem retryable un retryAfterS. insufficient_credit satur topUpUrl; rate_limited norāda, cik ilgi gaidīt. Tas ir svarīgāk, nekā šķiet: modelis lasa kļūdas tekstu, tāpēc teikums, pēc kura var rīkoties, strupceļu pārvērš nākamajā rīka izsaukumā./v1/mcp pieprasījumu: cilpā iestrēgušais aģents saņem HTTP 429 ar Retry-After, pirms jebkurš rīks ir palaists.idempotencyKey: pabeigta izsaukuma atslēgas atkārtota izmantošana atkārto pirmo rezultātu, bet atslēgas atkārtota izmantošana ar citiem argumentiem tiek noraidīta, tāpēc aģents, kas pats atkārtoti mēģina, nekad nesāk otru darbu. Katram rīkam, kas tērē naudu, to vajadzētu piedāvāt; aģenti atkārto daudz brīvāk nekā cilvēki.Tās ir servera darbības robežas. Divas lietas apzināti atrodas ārpus tām.
Serverim nav rīka, kas patvaļīgu tekstu pārvērstu runā, un tāds netiek plānots. VocalStack runā transkriptus un to tulkojumus standarta vai klonētā balsī, un neko citu. list_voices pasaka aģentam, kuras balsis var nolasīt transkriptu valodā, nevis to, kā likt balsij pateikt ko jaunu.
Transkribēšanas rīki arī noraida tiešraides straumes. YouTube tiešraidei vai radio straumei nepieciešama tiešraides transkripcija, kas sākta no vadības paneļa vai caur POST /v1/transcriptions/live API atsaucē. Pabeigts YouTube video ir fails, un to pieņem transcribe_url.
Ja labāk gribat rakstīt kodu paši, faila transkribēšana ar API iziet tos pašus soļus kā HTTP izsaukumi, un reāllaika apmācība apskata WebSocket.