MCP serveri API-ni agentin söhbət zamanı çağıra biləcəyi bir neçə adlı alətə çevirir. Alət agentə məhdud addımlarla gözləyə biləcəyi bir tutacaq qaytardıqda, uzun iş də bu quruluşa sığır. Podkast linkini yapışdırın, fransız dilində xülasə istəyin — heç bir kod yazılmır.
Kodlaşdırma agenti VocalStack API-dən hər hansı proqram kimi istifadə edə bilər: API istinadını oxuyub SDK ilə bir neçə sətir yazır və onu işə salır. Agentin iştirakı olmadan işləyəcək bir şey üçün bu, doğru yoldur.
MCP (Model Context Protocol) başqa bir hal üçündür: asistanla danışırsınız və ondan indi, kod olmadan bir şeyi transkripsiya etməsini istəyirsiniz. MCP serveri qısa bir alət siyahısı dərc edir: hər alətin adı, təsviri və arqumentləri üçün JSON sxemi var. Agent siyahını bir dəfə oxuyur və sorğu uyğun gəldikdə aləti adı ilə çağırır. "Bu podkastı transkripsiya et və qiymətlər haqqında nə dedilər de" sorğusu üç alət çağırışına çevrilir və agent heç vaxt HTTP marşrutunu görmür.
Serverlər iki növdə olur. Yerli server müştərinin alt prosesi kimi işləyir və stdio üzərindən əlaqə qurur; əksər fayl sistemi və verilənlər bazası serverləri belə işləyir. Uzaq server bir URL arxasında yerləşir və Streamable HTTP ilə işləyir — bu, MCP spesifikasiyasının 2025-ci ilin mart revizyasında köhnə HTTP-plus-SSE (server-sent events) nəqliyyatını əvəz edən nəqliyyatdır. Müştəri hər sorğunu göndərir, server isə eyni əlaqə üzərindən cavab verir; son nəticədən əvvəl deyəcəyi hər şey ondan qabaq axın şəklində göndərilir. Cari spesifikasiyaya uyğun yazılmış hər müştəri hər iki növdən istifadə edə bilər.
VocalStack-in serveri uzaq növdəndir, {{api}}/v1/mcp ünvanındadır və ondan istifadə API-nin qiymətinə başa gəlir. Lazım olan tək şey URL-dir.
İdarə panelindəki Developers sahəsini {{app}}/developers ünvanında açın. Birinci tab, Connect an AI agent, serverin URL-ni və hər müştəri üçün quraşdırma parçasını göstərir. Aşağıdakı üç parça orada göstərilənlərlə üst-üstə düşür.
Terminalınızda bunu işə salın:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Layihənizdə .cursor/mcp.json faylına, və ya bütün layihələr üçün ~/.cursor/mcp.json faylına bunu əlavə edin:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Streamable HTTP-ni dəstəkləyən istənilən müştəri serveri bu URL ilə əlavə edə bilər. Bu, İdarə panelinin göstərdiyi ümumi formadır:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Başlamaq üçün API açarına ehtiyacınız yoxdur. Müştəri ilk dəfə qoşulduqda, brauzerdə VocalStack hesabınızla daxil olursunuz və müştəri tokeni saxlayır. İdarə paneli bunu bir cümlədə belə deyir: "You'll sign in with your VocalStack account the first time. No key needed."
Bu, VocalStack-ə məxsus hiylə deyil, MCP-nin avtorizasiya spesifikasiyasının işidir. Uzaq server avtorizasiyasız sorğuya 401 cavabı verir və bu cavab qorunan resurs metadatasına işarə edir: serverin tələb etdiyi icazə sahələrini (scopes) və avtorizasiya serverini adlandıran kiçik bir JSON sənədinə. Müştəri onu oxuyur, brauzerdə standart OAuth 2.1 axınını işə salır və yalnız həmin server üçün verilmiş tokenlə geri qayıdır. Yuxarıdakı müştərilər VocalStack haqqında heç nə bilmədən bunu məhz buna görə edə bilir: spesifikasiyaya uyğun hər uzaq MCP serveri sizi eyni şəkildə tanıyır.
API açarı da işləyir — serverdə və ya skriptdə işləyən müştəri üçün. Onu Authorization: Bearer vs_key_... kimi göndərin; REST API-nin qəbul etdiyi eyni başlıqdır. Açarlar Developers → API keys bölməsində yaradılır. İki transkripsiya aləti Write və Stream audio icazələrini tələb edir. İkincisi fayl üçün qəribə görünür, amma bu alətlər hər transkripsiya kimi, canlı olanlar da daxil olmaqla, eyni yaradılma nöqtəsindən keçir və həmin nöqtə hər ikisini yoxlayır. Oxuma alətləri Read tələb edir; list_voices isə yalnız etibarlı etimadnamə tələb edir.
Daxil olduqdan sonra agent doqquz alət görür. Onları özünüz nadir hallarda adla çağıracaqsınız, amma onların nə olduğunu bilmək agentin sonra nə etdiyini izah edir.
Hər alət camelCase JSON qəbul edir və qaytarır, /v1 wire tiplərindəki eyni sahə adları ilə; transkripsiyanın tutacağı onun transcriptionId-sidir.
transcribe_url audio və ya videonu açıq URL-də transkripsiya etməyə başlayır: fayl linki, podkast epizodu, YouTube videosu. Canlı axınlar qəbul olunmur. İstəyə bağlı arqumentlər: name, spokenLanguage (dili aşkarlamaq üçün onu buraxın), speakerLabels (auto, on və ya off) və yalnız hissəsini transkripsiya etmək üçün startS/endS.transcribe_file eyni işi agentin saxladığı fayl üçün görür; filename ilə birlikdə fileBase64 kimi göndərilir. Deşifrə olunmuş ölçü 10 MiB ilə məhdudlaşdırılır, bu, təxminən on dəqiqəlik 128 kbps MP3-ə bərabərdir; daha böyük olanlar üçün agentə link verin.Hər ikisi dərhal qaytarır: transcriptionId, state: "queued" və gözləmə alətinin adını göstərən next işarəsi ilə. Agentin yaratdığı transkripsiyalar paylaşım keçidi olmadan, məxfi olaraq başlayır.
Agent canlı yayımı sizdən daha səbirli izləyə bilməz; kimsə noutbuku əlinizdən alana qədər gözləmə alətini çağırmağa davam edərdi. Bitmiş yazının sonu var və növbəti cüt alət məhz ona qədər gözləyir.
Alət çağırışı bir HTTP sorğusudur, HTTP sorğularının isə bir saat sürməsi nəzərdə tutulmayıb. Müştərilər onlardan imtina edir, proksilər əlaqəni bağlayır və bir alətdə bloklanmış model başqa heç nə edə bilmir. Buna görə MCP arxasında hər uzun iş üçün nümunə REST API-də də istifadə olunan nümunədir: işi başladın və bir tutacaq alın, onu məhdud müddət ərzində gözləyin və hələ bitməyibsə yenidən çağırın. Vəziyyəti bağlantı deyil, tutacaq daşıyır.
wait_for_transcription done və ya failed olana qədər bloklanır, ya da timeoutS keçənə qədər (defolt 50 saniyə, maksimum 60; bu, əksər müştərilərin və proksilərin tətbiq etdiyi vaxt limitlərinin altında qalır). Nəticədə timedOut: true varsa, iş hələ işləyir və agent aləti yenidən çağırır. Alət gözlədiyi müddətdə, müştəri bunu istəyibsə, server MCP proqres bildirişləri göndərir: faiz və "fetching 3.1 / 8.0 MB" və ya "transcribing 01:25 of 02:00" kimi mərhələ.get_transcription statusu və bitdikdə mətni qaytarır. format: "text" hər seqment üçün bir sətir verir: [mm:ss] Speaker 1: ...; "segments" start, end, speaker və speakerName ilə vaxtlanmış sətirlər verir; includeWords: true söz vaxtlarını əlavə edir. Nəticələr səhifələnir (offset, limit, defolt 500 seqment) və daha qalırsa nextOffset ilə.Səhifələmə şəbəkə üçün yox, model üçündür. Alətin qaytardığı hər şey agentin kontekst pəncərəsinə yapışdırılır, orada sizin söhbətinizlə yarışır və sonrakı hər növbədə tokenlərə pul ödəyir. İki saatlıq görüş on minlərlə sözdür; hamısını bir dəfəyə qaytarmaq verdiyiniz sualı kontekstdən kənara itələyərdi. Yaxşı MCP alətləri bir səhifə və bir kursor qaytarır və nə qədər lazım olduğuna agentin özünün qərar verməsinə imkan verir.
Əlaqənin kəsilməsi və ya vaxt aşımı işi heç vaxt dayandırmır, çünki iş MCP sorğusunda yox, serverdə yaşayır. Bitdikdən sonra iş kitabxananızda bir element olur və növbəti alətlər onu hər hansı digər transkripsiya kimi qəbul edir.
list_transcriptions hesabın transkripsiyalarını ən yenidən başlayaraq, vəziyyəti və müddəti ilə siyahıya alır; lifecycle active, archived və ya all-dır.search_transcriptions bütün transkripsiyalarda deyilənləri istənilən dildə axtarır və hər biri öz transkripsiyası və deyildiyi saniyə ilə birlikdə uyğun sətirləri qaytarır. transcriptionId axtarışı bir transkripsiyaya daraldır; lang hər nəticəyə tərcümə əlavə edir.Sətiri tapmaq asan yarıdır. Bütün mətnin nə dediyini isə iki alət də müəyyən edir.
get_summary bitmiş transkripsiyanın AI başlığını və xülasəsini qaytarır; lang ilə isteğe bağlı tərcümə olunur. state: "pending" xülasənin hələ yazıldığını bildirir (adətən iş bitəndən bir neçə saniyə sonra hazır olur), agent yenidən soruşur.translate_transcription bitmiş transkripti başqa dilə, mətn və ya vaxtlı seqmentlər şəklində qaytarır, get_transcription kimi səhifələnmiş. Tərcümələr saxlanılır, ona görə də yenidən soruşmaq işi təkrarlamır.list_voices verilmiş dildə transkripti oxuya bilən səsləri siyahıya alır: id, ad, mövcud olduqda cins və aksent, keyfiyyət reytinqi və defolt olub-olmaması ya da klonlanmış səslərinizdən biri olub-olmaması. O, səsləri təsvir edir; bir səsi yeni bir şey danışdırmır (serverin nə etmədiyi barədə aşağıda daha ətraflı).Alətlər praktikada belə zəncirlənir:
Server əlavə olunduqdan sonra Claude Code-dakı söhbət belə gedir. Podkast linki yapışdırırsınız və fransız dilində xülasə istəyirsiniz.
Agent transcribe_url çağırır:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
O, transcriptionId və state: "queued" qaytarır və next işarəsini izləyir:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Əlli dəqiqəlik epizod oxunduğundan çox dəfə sürətli transkripsiya olunur, amma bir gözləmə ərzində yox. İlk gözləmə timedOut: true qaytarır, irəliləyiş, məsələn, 61 faizdə olur; agent aləti bir dəfə də çağırır və state: "done" alır.
İndi agent lang: "fr" ilə get_summary çağırır:
{ "transcriptionId": "4f1c...", "lang": "fr" }
Əgər xülasə hələ pending-dirsə, agent bir neçə saniyə gözləyir; əks halda sizə fransız dilində başlıq və xülasə verir. "Qiymətlər haqqında harada danışdılar?" deyə soruşsanız, agent query: "pricing" və eyni transcriptionId ilə search_transcriptions çağırır və uyğun sətirləri vaxt işarələri ilə sitat gətirir. Bütün mətni fransızca istəsəniz, translate_transcription çağırır.
Bir neçə alət çağırışı, kod yoxdur, kitabxanada isə transkripsiya var. Bu çağırışların hər biri REST sorğusu ilə eyni keçid nöqtələrindən keçdi və məhz bu nəzarət nöqtələri hesabı və limitləri müəyyən edir.
MCP serveri API-yə başqa giriş qapısından daxil olmaqdır: eyni limitlər, eyni ödəniş.
POST /v1/transcriptions ilə eyni yaradılma nöqtəsindən keçir: planın yaradılma sürəti (saatda başladılan transkripsiyaların 10, 100 və ya fərdi sayı), eyni vaxtda işləyən transkripsiyaların limiti (1, 5 və ya limitsiz) və krediti hamısı tətbiq olunur. $5-lik qeydiyyat krediti kart tələb etmədən ilk sessiyanı əhatə edir.retryable və retryAfterS sahələrini ilə birlikdə isError: true qaytarır. insufficient_credit topUpUrl gətirir; rate_limited isə nə qədər gözləmək lazım olduğunu deyir. Bunun göründüyündən vacib olması var: model xəta mətnini oxuyur və hərəkət edə biləcəyi bir cümlə ölü sonu növbəti alət çağırışına çevirir./v1/mcp sorğusunun özünə də tətbiq olunur: döngəyə düşmüş agent heç bir alət işə düşməmişdən əvvəl Retry-After başlığı ilə HTTP 429 alır.idempotencyKey qəbul edir: tamamlanmış çağırışın açarını təkrar istifadə etmək birinci nəticəni təkrarlayır, açarı fərqli arqumentlərlə təkrar istifadə etmək isə rədd olunur, beləliklə öz-özünə təkrar cəhd edən agent ikinci iş başlatmır. Pul xərcləyən hər alət bunu təklif etməlidir; agentlər təkrar cəhdləri insanlardan qat-qat sərbəst edirlər.Bunlar serverin hüdudlarıdır. Qəsdən hüdudlardan kənarda qalan iki şey var.
Serverdə istənilən mətni nitqə çevirən alət yoxdur və planlaşdırılmır. VocalStack transkriptləri və onların tərcümələrini hazır və ya klonlanmış səslə oxuyur, başqa heç nə. list_voices agentə hansı səslərin dildə transkripti oxuya biləcəyini deyir, bir səsin yeni bir şeyi necə danışmalı olduğunu yox.
Transkripsiya alətləri də canlı axınları rədd edir. YouTube canlı yayımı və ya radio axını canlı transkripsiya tələb edir; bu, İdarə panelindən və ya API istinadında POST /v1/transcriptions/live vasitəsilə başladılmalıdır. Bitmiş YouTube videosu isə fayldır və transcribe_url onu qəbul edir.
Kodu özünüz yazmaq istəyirsinizsə, API ilə fayl transkripsiya etmək bölməsi eyni addımları HTTP çağırışları kimi göstərir, real vaxt rejimində transkripsiya dərsliyi isə WebSocket-i əhatə edir.