Pelayan MCP menukarkan API kepada beberapa alat bernama yang dipanggil ejen semasa perbualan, dan tugas panjang boleh diuruskan di belakangnya apabila alat itu memulangkan pengendali yang ditunggu ejen dalam giliran yang terhad. Tampal pautan podcast, minta gist-nya dalam bahasa Perancis, dan tiada kod perlu ditulis.
Ejen pengekodan boleh menggunakan API VocalStack seperti mana-mana program: baca rujukan API, tulis beberapa baris dengan SDK, dan jalankannya. Itulah laluan yang betul untuk sesuatu yang akan berjalan tanpa ejen.
MCP (Model Context Protocol) untuk kes yang lain: anda sedang berbual dengan pembantu dan mahu ia mentranskripsikan sesuatu sekarang, tanpa kod. Pelayan MCP menerbitkan senarai ringkas alat bernama, setiap satu dengan penerangan dan skema JSON untuk argumennya. Ejen membaca senarai itu sekali dan memanggil alat mengikut nama apabila permintaan sepadan. "Transkripkan podcast ini dan beritahu saya apa yang mereka kata tentang harga" menjadi tiga panggilan alat, dan ejen itu tidak pernah melihat laluan HTTP.
Pelayan terbahagi kepada dua jenis. Pelayan setempat berjalan sebagai subproses klien dan berkomunikasi melalui stdio, cara kebanyakan pelayan sistem fail dan pangkalan data berfungsi. Pelayan jauh terletak di belakang URL dan bertutur melalui Streamable HTTP, pengangkutan yang menggantikan pengangkutan HTTP-plus-SSE (server-sent events) yang lebih lama dalam semakan spesifikasi Mac 2025. Klien menghantar setiap permintaan, dan pelayan menjawab pada sambungan yang sama; apa-apa yang perlu dikatakannya sebelum hasil akhir dialirkan terlebih dahulu. Mana-mana klien yang ditulis berdasarkan spesifikasi semasa boleh menggunakan mana-mana jenis.
Pelayan VocalStack ialah jenis jauh, di {{api}}/v1/mcp, dan penggunaannya menelan kos yang sama seperti API. Yang anda perlukan hanyalah URL.
Buka bahagian Developers di Papan Pemuka di {{app}}/developers. Tab pertama, Connect an AI agent, memaparkan URL pelayan dan coretan persediaan untuk setiap klien. Tiga coretan di bawah sepadan dengan yang dipaparkan di sana.
Jalankan arahan ini dalam terminal anda:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Tambahkan ini ke .cursor/mcp.json dalam projek anda, atau ke ~/.cursor/mcp.json untuk setiap projek:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Mana-mana klien yang menyokong Streamable HTTP boleh menambah pelayan dengan URL ini. Ini ialah bentuk generik yang dipaparkan oleh Papan Pemuka:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Anda tidak perlukan kunci API untuk bermula. Kali pertama klien bersambung, anda log masuk dengan akaun VocalStack anda dalam pelayar, dan klien menyimpan token itu. Papan Pemuka meringkaskannya dalam satu baris: "You'll sign in with your VocalStack account the first time. No key needed."
Ini ialah spesifikasi kebenaran MCP yang sedang berfungsi, bukan helah VocalStack. Pelayan jauh menjawab permintaan tanpa pengesahan dengan 401 yang menunjuk kepada metadata sumber terlindungnya: dokumen JSON kecil yang menamakan pelayan kebenaran dan skop yang diperlukan oleh pelayan. Klien membacanya, menjalankan aliran OAuth 2.1 standard dalam pelayar anda, dan kembali dengan token yang dikeluarkan untuk pelayan itu sahaja. Mana-mana pelayan MCP jauh yang mengikut spesifikasi akan log masuk anda dengan cara yang sama, itulah sebabnya klien di atas boleh melakukannya tanpa mengetahui apa-apa tentang VocalStack.
Kunci API juga berfungsi, untuk klien yang berjalan di pelayan atau dalam skrip. Hantarkannya sebagai Authorization: Bearer vs_key_..., header yang sama yang diterima oleh API REST. Kunci dicipta di bawah Developers → API keys. Dua alat transkripsi memerlukan kebenaran Write dan Stream audio. Yang kedua kedengaran pelik untuk fail, tetapi alat-alat itu melalui titik penciptaan yang sama seperti setiap transkripsi, termasuk yang langsung, dan titik itu menyemak kedua-duanya. Alat bacaan memerlukan Read; list_voices hanya memerlukan sebarang kelayakan yang sah.
Sebaik sahaja anda log masuk, ejen itu akan melihat sembilan alat. Anda jarang menamakannya sendiri, tetapi mengetahuinya menjelaskan apa yang ejen lakukan seterusnya.
Setiap alat mengambil dan memulangkan JSON camelCase, dengan nama medan yang sama seperti jenis wayar /v1; pengendali sesuatu transkripsi ialah transcriptionId-nya.
transcribe_url memulakan transkripsi audio atau video di URL awam: pautan fail, episod podcast, video YouTube. Strim langsung tidak diterima. Argumen pilihan: name, spokenLanguage (tinggalkannya untuk mengesan bahasa), speakerLabels (auto, on atau off) dan startS/endS untuk mentranskripsikan hanya sebahagian audio.transcribe_file melakukan perkara yang sama untuk fail yang dipegang oleh ejen, dihantar sebagai fileBase64 dengan filename-nya. Saiz yang dinyahkod dihadkan kepada 10 MiB, kira-kira sepuluh minit MP3 128 kbps; untuk yang lebih besar, berikan ejen itu pautan.Kedua-duanya kembali serta-merta dengan transcriptionId, state: "queued" dan petunjuk next yang menamakan alat tunggu. Transkripsi yang dicipta oleh ejen bermula secara persendirian, tanpa pautan kongsi.
Ejen tidak boleh duduk menonton siaran langsung dengan lebih sabar daripada anda; ia akan terus memanggil alat tunggu sehingga seseorang mengambil komputer riba itu daripadanya. Rakaman yang selesai mempunyai penghujung, dan itulah yang ditunggu oleh dua alat seterusnya.
Panggilan alat ialah satu permintaan HTTP, dan permintaan HTTP tidak sepatutnya berlarutan selama sejam. Klien akan berhenti menunggu, proksi menutup sambungan, dan model yang tersekat pada satu alat tidak boleh melakukan apa-apa lagi. Maka corak untuk mana-mana tugas panjang di belakang MCP ialah corak yang juga digunakan oleh API REST: mulakan tugas dan dapatkan pengendali, tunggu padanya untuk masa yang terhad, dan panggil semula jika belum selesai. Pengendali itulah yang membawa keadaan, bukan sambungan.
wait_for_transcription menyekat sehingga tugas menjadi done atau failed, atau sehingga timeoutS berlalu (lalai 50 saat, maksimum 60, yang memastikan panggilan berada di bawah had masa yang kebanyakan klien dan proksi gunakan). Jika hasil menyatakan timedOut: true, tugas masih berjalan dan ejen memanggil alat itu sekali lagi. Semasa alat menunggu, pelayan menghantar pemberitahuan kemajuan MCP jika klien memintanya: peratusan dan fasa seperti "fetching 3.1 / 8.0 MB" atau "transcribing 01:25 of 02:00".get_transcription memulangkan status dan, apabila selesai, teksnya. format: "text" memberi satu baris setiap segmen sebagai [mm:ss] Speaker 1: ...; "segments" memberi baris berdasarkan masa dengan start, end, speaker dan speakerName; includeWords: true menambah masa setiap perkataan. Hasil dibahagi halaman (offset, limit, lalai 500 segmen) dengan nextOffset apabila masih ada lagi.Pembahagian halaman itu untuk model, bukan untuk rangkaian. Apa-apa yang dipulangkan oleh alat dimasukkan ke dalam tetingkap konteks ejen, di mana ia bersaing dengan perbualan anda dan menelan token pada setiap giliran seterusnya. Mesyuarat dua jam ialah puluhan ribu perkataan; memulangkan semuanya sekaligus akan menolak soalan anda keluar daripada konteks. Alat MCP yang baik memulangkan satu halaman dan kursor, dan membiarkan ejen memutuskan berapa banyak yang diperlukannya.
Pemutusan sambungan atau tamat masa tidak pernah membatalkan tugas, kerana tugas itu hidup di pelayan, bukan dalam permintaan MCP. Apabila ia selesai, tugas itu menjadi satu lagi entri dalam perpustakaan anda, dan alat seterusnya melayannya seperti mana-mana transkripsi lain.
list_transcriptions menyenaraikan transkripsi akaun, yang terbaharu dahulu, dengan keadaan dan tempoh; lifecycle ialah active, archived atau all.search_transcriptions mencari apa yang dikatakan merentasi setiap transkripsi, dalam mana-mana bahasa, dan memulangkan baris yang sepadan, setiap satu dengan transkripsinya dan saat ia dituturkan. transcriptionId mengecilkan carian kepada satu transkripsi; lang menambah terjemahan bagi setiap padanan.Mencari satu baris ialah separuh yang murah. Dua alat lagi berfungsi untuk memahami keseluruhan kandungan.
get_summary memulangkan tajuk AI dan ringkasan transkripsi yang selesai, secara pilihan diterjemahkan dengan lang. state: "pending" bermaksud ringkasan masih ditulis (biasanya siap dalam beberapa saat selepas tugas selesai), dan ejen bertanya semula.translate_transcription memulangkan transkrip yang selesai dalam bahasa lain, sebagai teks atau segmen berdasarkan masa, dibahagi halaman seperti get_transcription. Terjemahan disimpan, jadi meminta semula tidak mengulang kerja itu.list_voices menyenaraikan suara yang boleh membacakan transkrip dalam sesuatu bahasa: id, nama, jantina dan loghat apabila diketahui, penarafan kualiti, dan sama ada ia suara lalai atau salah satu suara klon anda. Ia menerangkan suara; ia tidak menjadikan suara itu bercakap (lebih lanjut di bawah tentang perkara yang tidak dilakukan oleh pelayan).Berikut ialah cara alat-alat ini dirangkaikan dalam amalan.
Sebaik sahaja pelayan ditambah, perbualan dalam Claude Code berjalan begini. Anda menampal pautan podcast dan meminta gist-nya dalam bahasa Perancis.
Ejen memanggil transcribe_url:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Ia mendapat semula transcriptionId dan state: "queued", lalu mengikut petunjuk next:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Episod lima puluh minit ditranskripsikan berkali-kali lebih pantas daripada masa ia dimainkan, tetapi tidak dalam satu tempoh tunggu. Tunggu pertama memulangkan timedOut: true dengan kemajuan pada, katakan, 61 peratus, jadi ejen memanggil alat itu sekali lagi dan mendapat state: "done".
Kini ejen memanggil get_summary dengan lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Jika ringkasan masih pending, ejen menunggu beberapa saat; jika tidak, ia menyerahkan kepada anda tajuk dan ringkasan dalam bahasa Perancis. Tanya "di mana mereka bercakap tentang harga?" dan ia memanggil search_transcriptions dengan query: "pricing" dan transcriptionId yang sama, lalu memetik baris yang sepadan beserta cap masanya. Minta keseluruhannya dalam bahasa Perancis dan ia memanggil translate_transcription.
Beberapa panggilan alat, tanpa kod, dan satu transkripsi dalam perpustakaan anda. Setiap panggilan itu melalui pintu yang sama seperti permintaan REST, dan pintu-pintu itulah yang menetapkan bil dan had.
Pelayan MCP ialah API melalui pintu hadapan yang berbeza: had yang sama, bil yang sama.
POST /v1/transcriptions: kadar penciptaan pelan (10, 100 atau nombor tersuai transkripsi yang dimulakan sejam), had transkripsi serentak (1, 5 atau tanpa had) dan kreditnya semuanya terpakai. Kredit pendaftaran $5 menampung sesi pertama, tanpa kad diperlukan.isError: true dengan kod ralat API REST, satu ayat yang boleh diambil tindakan oleh model, dan medan retryable dan retryAfterS. insufficient_credit membawa topUpUrl; rate_limited menyatakan berapa lama perlu menunggu. Ini lebih penting daripada yang kedengarannya: model membaca teks ralat, dan ayat yang boleh diambil tindakan menukar jalan mati kepada panggilan alat yang seterusnya./v1/mcp itu sendiri: ejen yang terperangkap dalam gelung akan menerima HTTP 429 dengan Retry-After sebelum sebarang alat dijalankan.idempotencyKey: menggunakan semula kunci panggilan yang telah selesai akan memainkan semula hasil pertama, dan menggunakannya dengan argumen yang berbeza akan ditolak, jadi ejen yang mencuba semula sendiri tidak pernah memulakan tugas kedua. Mana-mana alat yang membelanjakan wang harus menawarkan ini; ejen mencuba semula jauh lebih kerap daripada manusia.Itulah had luar pelayan. Dua perkara berada di luar had itu dengan sengaja.
Pelayan tidak mempunyai alat yang menukar teks arbitrari kepada ucapan, dan tiada yang dirancang. VocalStack menuturkan transkrip dan terjemahannya, dalam suara sedia ada atau suara klon, dan tiada yang lain. list_voices memberitahu ejen suara mana yang boleh membacakan transkrip dalam sesuatu bahasa, bukan cara untuk menjadikan suara itu menuturkan sesuatu yang baharu.
Alat transkripsi juga menolak strim langsung. Strim langsung YouTube atau strim radio memerlukan transkripsi langsung, yang dimulakan dari Papan Pemuka atau melalui POST /v1/transcriptions/live dalam rujukan API. Video YouTube yang telah selesai ialah fail, dan transcribe_url menerimanya.
Jika anda lebih suka menulis kodnya sendiri, mentranskripsikan fail dengan API menerangkan langkah yang sama sebagai panggilan HTTP, dan tutorial masa nyata meliputi WebSocket.