Seva ya MCP hubadilisha API kuwa zana chache zenye majina ambazo wakala huziita katikati ya mazungumzo, na kazi ndefu hutoshea nyuma ya zana moja pale zana inaporudisha kishikio ambacho wakala husubiri kwa zamu zenye mipaka. Bandika kiungo cha podikasti, uliza muhtasari kwa Kifaransa, na hakuna msimbo utakaoandikwa.
Wakala wa kuandika msimbo unaweza kutumia API ya VocalStack kama programu yoyote inavyofanya: soma marejeleo ya API, andika mistari michache kwa kutumia SDK, kisha uiendeshe. Hiyo ndiyo njia sahihi kwa kitu kitakachofanya kazi bila wakala.
MCP (Itifaki ya Muktadha wa Modeli) ni kwa kisa kingine: unazungumza na msaidizi na unataka anukuu kitu sasa hivi, bila msimbo. Seva ya MCP huchapisha orodha fupi ya zana zenye majina, kila moja ikiwa na maelezo na schema ya JSON ya hoja zake. Wakala husoma orodha mara moja na kuita zana kwa jina pale ombi linapolingana nayo. "Nukuu podikasti hii kisha uniambie walichosema kuhusu bei" inakuwa miito mitatu ya zana, na wakala hauoni njia ya HTTP kamwe.
Seva ni za aina mbili. Seva ya ndani huendeshwa kama mchakato mdogo wa kiteja na huwasiliana kupitia stdio, ndivyo seva nyingi za mifumo ya faili na hifadhidata zinavyofanya kazi. Seva ya mbali iko nyuma ya URL na huzungumza Streamable HTTP, usafirishaji uliochukua nafasi ya usafirishaji wa zamani wa HTTP-plus-SSE (matukio yanayotumwa na seva) katika toleo la Machi 2025 la vipimo. Kiteja hutuma kila ombi, nayo seva hujibu kwenye muunganisho uleule; chochote inachotaka kusema kabla ya matokeo ya mwisho hutumwa mbele yake kwa mtiririko. Kiteja chochote kilichoandikwa kulingana na vipimo vya sasa kinaweza kutumia aina yoyote kati ya hizi.
Seva ya VocalStack ni ya aina ya mbali, katika {{api}}/v1/mcp, na kuitumia kunagharimu kile ambacho API inagharimu. Unachohitaji ni URL tu.
Fungua eneo la Developers la Dashibodi kupitia {{app}}/developers. Kichupo cha kwanza, Connect an AI agent, kinaonyesha URL ya seva na kipande cha usanidi kwa kila kiteja. Vipande vitatu vilivyo hapa chini vinafanana na vile vinavyoonyeshwa hapo.
Endesha hii kwenye terminal yako:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Ongeza hii kwenye .cursor/mcp.json katika mradi wako, au kwenye ~/.cursor/mcp.json kwa kila mradi:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Kiteja chochote kinachounga mkono Streamable HTTP kinaweza kuongeza seva kwa URL hii. Hii ndiyo muundo wa jumla ambao Dashibodi inaonyesha:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Hauhitaji ufunguo wa API ili kuanza. Mara ya kwanza kiteja kinapounganika, unaingia kwa akaunti yako ya VocalStack kwenye kivinjari, nacho kiteja kinahifadhi tokeni. Dashibodi inaliweka kwa mstari mmoja: "Utaingia kwa akaunti yako ya VocalStack mara ya kwanza. Hakuna ufunguo unaohitajika."
Hii ni vipimo vya idhini vya MCP vinavyofanya kazi, si hila ya VocalStack. Seva ya mbali hujibu ombi lisilothibitishwa kwa 401 inayoelekeza kwenye metadata yake ya rasilimali iliyolindwa: hati ndogo ya JSON inayotaja seva ya idhini na wigo ambao seva inauhitaji. Kiteja hukisoma, huendesha mtiririko wa kawaida wa OAuth 2.1 kwenye kivinjari chako, na kurudi na tokeni iliyotolewa kwa seva hiyo peke yake. Seva yoyote ya mbali ya MCP inayofuata vipimo humwingiza mtumiaji kwa njia hiyo hiyo, ndiyo maana viteja vilivyo hapo juu vinaweza kufanya hivyo bila kujua chochote kuhusu VocalStack.
Ufunguo wa API pia unafanya kazi, kwa kiteja kinachoendeshwa kwenye seva au kwenye script. Utume kama Authorization: Bearer vs_key_..., kichwa kile kile ambacho REST API inakipokea. Funguo huundwa chini ya Developers → API keys. Zana mbili za unukuzi zinahitaji ruhusa za Write na Stream audio. Ya pili inasikika ajabu kwa faili, lakini zana hizo zinapitia sehemu ile ile ya kuanzisha kila unukuzi, za moja kwa moja zikijumuishwa, na sehemu hiyo huangalia zote mbili. Zana za kusoma zinahitaji Read; list_voices inahitaji tu kitambulisho halali.
Ukishaingia, wakala anaona zana tisa. Mara chache utazitaja mwenyewe, lakini kuzijua kunaeleza wakala anachofanya baadaye.
Kila zana hupokea na kurudisha JSON ya camelCase, yenye majina ya sehemu yale yale ya aina za /v1; kishikio cha unukuzi ni transcriptionId yake.
transcribe_url huanzisha unukuzi wa sauti au video kwenye URL ya umma: kiungo cha faili, kipindi cha podikasti, video ya YouTube. Matangazo ya moja kwa moja hayakubaliwi. Hoja za hiari: name, spokenLanguage (iache ili kutambua lugha), speakerLabels (auto, on au off) na startS/endS ili kunukuu sehemu ya sauti pekee.transcribe_file hufanya hivyo hivyo kwa faili ambalo wakala analo, linalotumwa kama fileBase64 pamoja na filename yake. Ukubwa baada ya kufumbuliwa umewekewa kikomo cha 10 MiB, takriban dakika kumi za MP3 ya 128 kbps; kwa kitu kikubwa zaidi, mpe wakala kiungo.Zote mbili hurudisha papo hapo transcriptionId, state: "queued" na kidokezo cha next kinachotaja zana ya kusubiri. Unukuzi unaoundwa na wakala huanza kuwa wa faragha, bila kiungo cha kushiriki.
Wakala hawezi kukaa kusikiliza matangazo ya moja kwa moja kwa subira zaidi yako; angeendelea kuita zana ya kusubiri hadi mtu achukue kompyuta yake ndogo. Rekodi iliyokamilika ina mwisho, na hicho ndicho jozi inayofuata ya zana inachosubiri.
Mwito wa zana ni ombi moja la HTTP, na maombi ya HTTP hayakusudiwi kudumu saa moja. Viteja huyakatisha tamaa, proksi huyafunga, na modeli iliyozuiwa na zana moja haiwezi kufanya kitu kingine. Kwa hiyo mfumo wa kazi yoyote ndefu nyuma ya MCP ni ule ule ambao REST API nayo hutumia: anzisha kazi na upate kishikio, subiri kwa muda wenye mipaka, kisha piga tena kama haijakamilika. Kishikio, si muunganisho, ndicho kinachobeba hali.
wait_for_transcription husubiri hadi kazi iwe done au failed, au hadi timeoutS ipite (chaguo-msingi sekunde 50, kiwango cha juu 60, ambacho huweka mwito chini ya muda wa kuisha ambao viteja vingi na proksi hutumia). Matokeo yakisema timedOut: true, kazi bado inaendelea na wakala huita zana tena. Zana inapongoja, seva hutuma arifa za maendeleo za MCP iwapo kiteja kiliziomba: asilimia na hatua kama "inapakua 3.1 / 8.0 MB" au "inanukuu 01:25 kati ya 02:00".get_transcription hurudisha hali na, ikishakamilika, maandishi. format: "text" hutoa mstari mmoja kwa kila sehemu kama [mm:ss] Speaker 1: ...; "segments" hutoa mistari yenye muda ikiwa na start, end, speaker na speakerName; includeWords: true huongeza muda wa kila neno. Matokeo hugawanywa kurasa (offset, limit, chaguo-msingi sehemu 500) yenye nextOffset pale yanapobaki zaidi.Ugawaji wa kurasa upo kwa ajili ya modeli, si kwa ajili ya mtandao. Kila kitu zana inachorudisha hubandikwa kwenye dirisha la muktadha la wakala, ambako kinashindana na mazungumzo yako na kugharimu tokeni kila zamu inayofuata. Mkutano wa saa mbili ni makumi ya maelfu ya maneno; kurudisha yote kwa mara moja kungeisukuma swali lako nje ya muktadha. Zana nzuri za MCP hurudisha ukurasa na kielekezi, na kumwachia wakala aamue anahitaji kiasi gani.
Kukatika kwa muunganisho au kuisha kwa muda hakuwahi kughairi kazi, kwa sababu kazi huishi kwenye seva, si kwenye ombi la MCP. Ikishakamilika, kazi ni ingizo jingine kwenye maktaba yako, na zana zinazofuata zinaishughulikia kama nyingine yoyote.
list_transcriptions huorodhesha unukuzi wa akaunti, mpya zaidi kwanza, pamoja na hali na muda; lifecycle ni active, archived au all.search_transcriptions hutafuta kilichosemwa katika unukuzi wote, kwa lugha yoyote, na kurudisha mistari inayolingana, kila moja ikiwa na unukuzi wake na sekunde ilipotamkwa. transcriptionId hupunguza utafutaji hadi unukuzi mmoja; lang huongeza tafsiri ya kila matokeo.Kupata mstari ni nusu rahisi. Zana mbili zaidi zinabaini kile ambacho kilichosemwa kwa jumla.
get_summary hurudisha kichwa cha AI na muhtasari wa unukuzi uliokamilika, ukiwa tayari kutafsiriwa kwa lang. state: "pending" inamaanisha muhtasari bado unaandikwa (kwa kawaida uko tayari ndani ya sekunde chache kazi inapomalizika), na wakala huuliza tena.translate_transcription hurudisha nakala iliyokamilika kwa lugha nyingine, kama maandishi au sehemu zenye muda, zikigawanywa kurasa kama get_transcription. Tafsiri huhifadhiwa, kwa hiyo kuuliza tena hakurudii kazi.list_voices huorodhesha sauti zinazoweza kusoma nakala kwa lugha: kitambulisho, jina, jinsia na lafudhi pale zinapojulikana, ukadiriaji wa ubora, na kama ndiyo chaguo-msingi au mojawapo ya sauti zako zilizonakiliwa. Inaeleza sauti; haizifanyi kuzungumza (zaidi hapa chini kuhusu kile seva isichokifanya).Hivi ndivyo zana zinavyofuatana kivitendo.
Seva ikishaongezwa, mazungumzo katika Claude Code yanaenda hivi. Unabandika kiungo cha podikasti na kuomba muhtasari wake kwa Kifaransa.
Wakala anaita transcribe_url:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Anapata transcriptionId na state: "queued", kisha anafuata kidokezo cha next:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Kipindi cha dakika hamsini hunukuliwa mara nyingi haraka kuliko kinavyochezwa, lakini si ndani ya subira moja. Subira ya kwanza hurudisha timedOut: true na maendeleo ya, tuseme, asilimia 61, kwa hiyo wakala anaita zana mara moja zaidi na kupata state: "done".
Sasa wakala anaita get_summary kwa lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Muhtasari ukiwa bado pending, wakala anasubiri sekunde chache; vinginevyo anakupa kichwa na muhtasari kwa Kifaransa. Uliza "walizungumzia wapi kuhusu bei?" nayo itaita search_transcriptions kwa query: "pricing" na transcriptionId hiyo hiyo, kisha kunukuu mistari inayolingana pamoja na alama zake za muda. Ukiomba yote kwa Kifaransa, inaita translate_transcription.
Miito michache ya zana, bila msimbo, na unukuzi mmoja kwenye maktaba yako. Kila mwito huo ulipitia milango ile ile kama ombi la REST, na milango hiyo ndiyo inayoweka bili na mipaka.
Seva ya MCP ni API kupitia mlango mwingine: mipaka ile ile, bili ile ile.
POST /v1/transcriptions: kasi ya kuanzisha ya mpango (10, 100 au idadi maalum ya unukuzi unaoanzishwa kwa saa), kikomo cha unukuzi wa wakati mmoja (1, 5 au bila kikomo) na salio lake vyote vinatumika. Salio la kujisajili la $5 linagharamia kikao cha kwanza, bila kadi inayohitajika.isError: true pamoja na msimbo wa hitilafu wa REST API, sentensi ambayo modeli inaweza kuitendea kazi, na sehemu retryable na retryAfterS. insufficient_credit hubeba topUpUrl; rate_limited inasema muda wa kusubiri. Hili ni muhimu kuliko linavyosikika: modeli husoma maandishi ya hitilafu, kwa hiyo sentensi inayoweza kuitendea kazi hugeuza njia iliyofungwa kuwa mwito unaofuata wa zana./v1/mcp lenyewe: wakala anayezunguka hupata HTTP 429 yenye Retry-After kabla zana yoyote haijaendeshwa.idempotencyKey: kutumia tena ufunguo wa mwito uliokamilika hurudia matokeo ya kwanza, na kuutumia tena pamoja na hoja tofauti kunakataliwa, kwa hiyo wakala anayejaribu tena peke yake hanzishi kazi ya pili kamwe. Zana yoyote inayotumia pesa inapaswa kutoa hili; mawakala hujaribu tena kwa uhuru zaidi kuliko watu.Hayo ndiyo mipaka ya kile seva inachofanya. Mambo mawili yako nje yake kwa makusudi.
Seva haina zana inayogeuza maandishi yoyote kuwa usemi, na hakuna iliyopangwa. VocalStack husema nakala na tafsiri zake, kwa sauti ya kawaida au iliyonakiliwa, na si kitu kingine. list_voices humwambia wakala sauti zipi zinaweza kusoma nakala kwa lugha, si jinsi ya kumfanya sauti aseme kitu kipya.
Zana za unukuzi pia zinakataa matangazo ya moja kwa moja. Matangazo ya moja kwa moja ya YouTube au ya redio yanahitaji unukuzi wa moja kwa moja, unaoanzishwa kutoka Dashibodi au kupitia POST /v1/transcriptions/live katika marejeleo ya API. Video iliyokamilika ya YouTube ni faili, na transcribe_url inaipokea.
Ikiwa ungependa kuandika msimbo mwenyewe, kunukuu faili kwa API kunapitia hatua zile zile kama miito ya HTTP, na somo la wakati halisi linashughulikia WebSocket.