MCP сервері API-ді агент сөйлесу барысында шақыратын бірнеше аталған құралға айналдырады, ал құрал агент күтетін тұтқа қайтарса, ұзақ жұмыс шектеулі кезеңдермен күтіледі. Подкаст сілтемесін қойыңыз, француз тілінде мазмұнын сұраңыз — ешқандай код жазылмайды.
Код жазатын агент VocalStack API-ін кез келген бағдарлама сияқты пайдалана алады: API анықтамасын оқып, SDK-ге қарсы бірнеше жол жазып, оларды іске қосыңыз. Бұл агентсіз жұмыс істейтін нәрсе үшін дұрыс жол.
MCP (Model Context Protocol) — басқа жағдайға арналған: сіз көмекшімен сөйлесіп жатырсыз және оның қазір код жазбай-ақ бір нәрсені транскрипциялауын қалайсыз. MCP сервері аталған құралдардың қысқа тізімін жариялайды, әрқайсысында сипаттама және аргументтеріне арналған JSON схемасы бар. Агент тізімді бір рет оқиды және сұрау сәйкес келгенде құралды атымен шақырады. «Осы подкастты транскрипциялап, бағалар туралы не айтқанын айтыңыз» үш құрал шақыруына айналады, ал агент HTTP маршрутын ешқашан көрмейді.
Серверлердің екі түрі бар. Жергілікті сервер клиенттің ішкі процесі ретінде іске қосылады және stdio арқылы сөйлеседі — файл жүйесі мен дерекқор серверлерінің көбі осылай жұмыс істейді. Қашықтағы сервер URL арқылы қолжетімді болады және Streamable HTTP протоколымен жұмыс істейді; бұл спецификацияның 2025 жылғы наурыздағы нұсқасында ескі HTTP-plus-SSE (server-sent events) тасымалдаушысын ауыстырған тасымалдау. Клиент әрбір сұрауды жібереді, ал сервер жауапты сол байланыс арқылы береді; соңғы нәтижеден бұрын айтатын нәрселері алдын ала ағынмен жіберіледі. Ағымдағы спецификацияға сай жазылған кез келген клиент екі түрінің кез келгенін пайдалана алады.
VocalStack серверi — қашықтағы түрі, мекенжайы {{api}}/v1/mcp, ал оны пайдалану API-дің құнымен бірдей. Сізге тек URL керек.
Басқару тақтасының Developers бөліміне {{app}}/developers мекенжайынан кіріңіз. Бірінші қойынша, Connect an AI agent, сервер URL-ін және әр клиентке арналған орнату үзіндісін көрсетеді. Төмендегі үш үзінді сол жерде көрсетілгендермен сәйкес келеді.
Терминалда осыны іске қосыңыз:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Осыны жобаңыздағы .cursor/mcp.json файлына немесе барлық жобалар үшін ~/.cursor/mcp.json файлына қосыңыз:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Streamable HTTP-ті қолдайтын кез келген клиент серверді осы URL арқылы қоса алады. Бұл басқару тақтасы көрсететін жалпы форма:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Бастау үшін API кілті қажет емес. Клиент алғаш қосылғанда, браузерде VocalStack аккаунтыңызбен кіресіз, ал клиент токенді сақтайды. Басқару тақтасы мұны бір жолмен айтады: «Алғашқы рет VocalStack аккаунтыңызбен кіресіз. Кілт қажет емес.»
Бұл VocalStack айласы емес, MCP авторизация спецификациясының жұмысы. Қашықтағы сервер аутентификацияланбаған сұрауға 401 жауабын береді, ол қорғалған ресурс метадеректеріне сілтеме жасайды: авторизация серверін және серверге қажет scope-тарды атайтын шағын JSON құжат. Клиент соны оқиды, браузеріңізде стандартты OAuth 2.1 ағынын іске қосады және тек сол сервер үшін берілген токенмен оралады. Спецификацияны ұстанатын кез келген қашықтағы MCP сервері сізді осылай кіргізеді, сондықтан жоғарыдағы клиенттер VocalStack туралы ештеңе білмей-ақ осыны жасай алады.
API кілті де жұмыс істейді — серверде немесе скриптте жұмыс істейтін клиент үшін. Оны Authorization: Bearer vs_key_... тақырыбымен жіберіңіз, бұл REST API қабылдайтын тақырыппен бірдей. Кілттер Developers → API keys бөлімінде жасалады. Екі транскрипциялау құралына Write және Stream audio рұқсаттары керек. Екіншісі файл үшін біртүрлі естілуі мүмкін, бірақ құралдар әр транскрипцияның, оның ішінде тікелей эфирлердің де, өтетін бірдей жасау нүктесі арқылы өтеді, ал сол нүкте екеуін де тексереді. Оқу құралдарына Read керек; list_voices тек жарамды рұқсат деректерін талап етеді.
Кіргеніңізден кейін агент тоғыз құралды көреді. Оларды өзіңіз сирек атайсыз, бірақ оларды білу агенттің кейін не істейтінін түсіндіреді.
Әр құрал camelCase JSON қабылдайды және қайтарады, өріс атаулары /v1 wire типтеріндегідей; транскрипцияның тұтқасы — оның transcriptionId-і.
transcribe_url ашық URL бойынша аудио немесе бейнені транскрипциялауды бастайды: файл сілтемесі, подкаст эпизоды, YouTube бейнесі. Тікелей ағындар қабылданбайды. Қосымша аргументтер: name, spokenLanguage (тілді анықтау үшін оны алып тастаңыз), speakerLabels (auto, on немесе off) және аудионың бір бөлігін ғана транскрипциялау үшін startS/endS.transcribe_file агенттегі файлға дәл солай жасайды, оны filename-мен бірге fileBase64 ретінде жібереді. Декодталған көлем 10 MiB-пен шектеледі, бұл шамамен 128 kbps MP3-тің он минуты; одан үлкен нәрсе үшін агентке сілтеме беріңіз.Екеуі де бірден transcriptionId, state: "queued" және күту құралын атайтын next кеңесімен қайтарады. Агент жасаған транскрипциялар жеке басталады, бөлісу сілтемесіз.
Агент тікелей трансляцияны сізден артық сабырмен отыра алмайды; ол ноутбукты біреу алып кеткенше күту құралын шақыра берер еді. Аяқталған жазбаның соңы бар, келесі құралдар жүпі сол соңын күтеді.
Құрал шақыруы — бір HTTP сұрауы, ал HTTP сұрауларының бір сағатқа созылуы көзделмеген. Клиенттер оларды тастайды, прокси-серверлер жабады, ал бір құралға тоқтап қалған модель басқа ешнәрсе істей алмайды. Сондықтан MCP-дің артындағы кез келген ұзақ жұмыстың үлгісі REST API-дегі сияқты: жұмысты бастап тұтқа алыңыз, оны шектеулі уақыт күтіңіз, ал ол аяқталмаса, қайта шақырыңыз. Күйді тұтқа сақтайды, қосылым емес.
wait_for_transcription жұмыс done немесе failed күйіне жеткенше немесе timeoutS өткенше бөгеледі (әдепкі 50 секунд, ең көбі 60, бұл шақыруды көпшілік клиенттер мен прокси-серверлер қоятын уақыт шектерінен төмен ұстайды). Нәтижеде timedOut: true болса, жұмыс әлі жүріп жатыр, ал агент құралды қайта шақырады. Құрал күткен кезде, егер клиент сұраған болса, сервер MCP прогресс хабарламаларын жібереді: пайыз және «3.1 / 8.0 MB жүктелуде» немесе «02:00-нің 01:25 транскрипцияланады» сияқты фаза.get_transcription күйді қайтарады, ал аяқталғанда мәтінді. format: "text" әр сегментке бір жолды [mm:ss] Speaker 1: ... түрінде береді; "segments" уақыт белгісі бар жолдарды start, end, speaker және speakerName өрістерімен береді; includeWords: true сөз уақыттарын қосады. Нәтижелер беттерге бөлінеді (offset, limit, әдепкі 500 сегмент), әрі көбірек қалса, nextOffset беріледі.Беттерге бөлу желі үшін емес, модель үшін жасалған. Құралдың қайтаратынының бәрі агенттің контекст терезесіне қойылады, онда ол сөйлесуіңізбен бәсекеге түседі және әрбір кейінгі айналымда токен шығындайды. Екі сағаттық кездесу — ондаған мың сөз; оның бәрін бір рет қайтару сұрағыңызды контекстен ысырып тастар еді. Жақсы MCP құралдары бетті және курсорды қайтарады және агентке қанша керектігін өзі шешуге мүмкіндік береді.
Байланыс үзілу немесе уақыт бітуі жұмысты ешқашан тоқтатпайды, себебі жұмыс MCP сұрауында емес, серверде өмір сүреді. Аяқталғаннан кейін жұмыс кітапханаңыздағы тағы бір жазба болады, ал келесі құралдар оны басқалары сияқты қарайды.
list_transcriptions аккаунттың транскрипцияларын, ең жаңасы бірінші, күйі мен ұзақтығымен тізеді; lifecycle — active, archived немесе all.search_transcriptions барлық транскрипцияларда, кез келген тілде айтылғандарды іздейді және сәйкес жолдарды қайтарады, әрқайсысы өзінің транскрипциясымен және айтылған секундымен бірге. transcriptionId іздеуді бір транскрипциямен шектейді; lang әр табылған нәтиженің аудармасын қосады.Жолды табу — жеңіл жартысы. Тағы екі құрал бүкіл айтылғанды анықтайды.
get_summary аяқталған транскрипцияның AI атауы мен қысқаша мазмұнын қайтарады, қаласаңыз lang арқылы аударылған. state: "pending" қысқаша мазмұн әлі жазылып жатқанын білдіреді (әдетте жұмыс аяқталғаннан кейін секундтар ішінде дайын болады), және агент қайта сұрайды.translate_transcription аяқталған транскриптті басқа тілде, мәтін немесе уақытты сегменттер түрінде қайтарады, get_transcription сияқты беттерге бөлінеді. Аудармалар сақталады, сондықтан қайта сұрау жұмысты қайталамайды.list_voices тілде транскриптті оқи алатын дауыстарды тізеді: id, атауы, белгілі болғанда жынысы мен акценті, сапа бағасы, және ол әдепкі ме әлде сіздің клондалған дауыстарыңыздың бірі ме. Ол дауыстарды сипаттайды; бірін сөйлетпейді (сервер не істемейтіні туралы төменде көбірек).Міне, құралдар іс жүзінде қалай тізбектеледі.
Сервер қосылғаннан кейін Claude Code-тағы сөйлесу мынадай жүреді. Подкаст сілтемесін қойып, француз тілінде мазмұнын сұрайсыз.
Агент transcribe_url құралын шақырады:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Ол transcriptionId және state: "queued" алады, және next кеңесін орындайды:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Елу минуттық эпизод ойналатыннан бірнеше есе жылдам транскрипцияланады, бірақ бір күту ішінде емес. Бірінші күту timedOut: true қайтарады, прогресс мысалы 61 пайыз, сондықтан агент құралды тағы бір рет шақырады және state: "done" алады.
Енді агент lang: "fr" параметрімен get_summary құралын шақырады:
{ "transcriptionId": "4f1c...", "lang": "fr" }
Қысқаша мазмұн әлі pending болса, агент бірнеше секунд күтеді; әйтпесе сізге француз тілінде атауы мен қысқаша мазмұнын береді. «Бағалар туралы қайда сөйлесті?» деп сұраңыз, ол query: "pricing" және сол transcriptionId параметрлерімен search_transcriptions құралын шақырады, және сәйкес жолдарды уақыт белгілерімен келтіреді. Бүкіл нәрсені француз тілінде сұрасаңыз, ол translate_transcription құралын шақырады.
Бірнеше құрал шақыруы, код жоқ, және кітапханаңызда транскрипция. Бұл шақырулардың әрқайсысы REST сұрауымен бірдей қақпалардан өтті, ал сол қақпалар шотты және шектеулерді белгілейді.
MCP сервері — басқа кіреберіс арқылы берілетін API: бірдей шектеулер, бірдей шот.
POST /v1/transcriptions сияқты бірдей жасау нүктесі арқылы өтеді: тарифтің жасау жылдамдығы (сағатына басталған транскрипциялар саны: 10, 100 немесе теңшелген сан), бір уақыттағы транскрипциялар шегі (1, 5 немесе шексіз) және оның кредиті — барлығы қолданылады. $5 тіркелу кредиті алғашқы сессияға жетеді, карта қажет емес.isError: true қайтарады, REST API қате кодымен, модельдің әрекет ете алатын сөйлемімен, және retryable мен retryAfterS өрістерімен. insufficient_credit topUpUrl береді; rate_limited қанша күту керегін айтады. Бұл естілгеннен маңыздырақ: модель қате мәтінін оқиды, сондықтан модель әрекет ете алатын сөйлем тұйық жолды келесі құрал шақыруына айналдырады./v1/mcp сұрауының өзіне де қолданылады: айналып жүрген агент кез келген құрал іске қосылғанға дейін Retry-After бар HTTP 429 алады.idempotencyKey қабылдайды: аяқталған шақырудың кілтін қайта пайдалану бірінші нәтижені қайталайды, ал оны басқа аргументтермен қайта пайдалануға тыйым салынады, сондықтан өз бетінше қайталайтын агент екінші жұмысты ешқашан бастамайды. Ақша жұмсайтын кез келген құрал мұны ұсынуы керек; агенттер адамдарға қарағанда әлдеқайда еркін қайталайды.Міне, сервер не істейтінінің шекаралары. Екі нәрсе әдейі осының сыртында қалады.
Серверде кез келген мәтінді сөйлеуге айналдыратын құрал жоқ, және ондай жоспарланбаған. VocalStack транскрипттерді және олардың аудармаларын стандартты немесе клондалған дауыспен айтады, басқа ешнәрсе емес. list_voices агентке тілде транскриптті қай дауыстар оқи алатынын айтады, дауысқа жаңа нәрсені қалай айтқызуды емес.
Транскрипциялау құралдары тікелей ағындарды да қабылдамайды. YouTube тікелей эфирі немесе радио ағыны тікелей транскрипцияны қажет етеді, оны басқару тақтасынан немесе API анықтамасындағы POST /v1/transcriptions/live арқылы бастауға болады. Аяқталған YouTube бейнесі — файл, және оны transcribe_url қабылдайды.
Егер кодты өзіңіз жазғыңыз келсе, API арқылы файлды транскрипциялау мақаласы дәл сол қадамдарды HTTP шақырулары ретінде түсіндіреді, ал нақты уақыттағы оқулық WebSocket-ті қамтиды.