Server MCP mengubah API menjadi beberapa alat bernama yang dipanggil agen di tengah percakapan, dan pekerjaan panjang dapat ditangani di baliknya ketika alat mengembalikan handle yang ditunggu agen dalam giliran yang terbatas. Tempelkan tautan podcast, minta ringkasannya dalam bahasa Prancis, dan tidak perlu menulis kode.
Agen pengodean dapat memakai API VocalStack seperti program lain pada umumnya: membaca Referensi API, menulis beberapa baris dengan SDK, lalu menjalankannya. Itu jalur yang tepat untuk sesuatu yang akan berjalan tanpa agen.
MCP (Model Context Protocol) ditujukan untuk kasus lainnya: Anda sedang berbicara dengan asisten dan ingin ia mentranskripsi sesuatu sekarang juga, tanpa kode. Server MCP menerbitkan daftar pendek alat bernama, masing-masing dengan deskripsi dan skema JSON untuk argumennya. Agen membaca daftar itu sekali dan memanggil alat berdasarkan nama ketika sebuah permintaan cocok dengannya. "Transkripsikan podcast ini dan beri tahu saya apa yang mereka katakan tentang harga" menjadi tiga panggilan alat, dan agen tidak pernah melihat rute HTTP.
Ada dua jenis server. Server lokal berjalan sebagai subproses dari klien dan berkomunikasi lewat stdio, cara kerja sebagian besar server sistem berkas dan basis data. Server jarak jauh berada di balik URL dan berbicara melalui Streamable HTTP, transport yang menggantikan transport HTTP-plus-SSE (server-sent events) yang lebih lama dalam revisi spesifikasi Maret 2025. Klien mengirim setiap permintaan, dan server menjawab pada koneksi yang sama; apa pun yang harus disampaikan sebelum hasil akhir dialirkan lebih dulu. Klien apa pun yang ditulis mengikuti spesifikasi terkini dapat memakai kedua jenis itu.
Server VocalStack adalah jenis jarak jauh, di {{api}}/v1/mcp, dan pemakaiannya dikenai biaya yang sama dengan API. Yang Anda perlukan hanyalah URL-nya.
Buka area Developers di Dasbor melalui {{app}}/developers. Tab pertama, Connect an AI agent, menampilkan URL server dan cuplikan pengaturan untuk setiap klien. Ketiga cuplikan di bawah ini sama dengan yang ditampilkan di sana.
Jalankan ini di terminal Anda:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Tambahkan ini ke .cursor/mcp.json di proyek Anda, atau ke ~/.cursor/mcp.json untuk setiap proyek:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Klien apa pun yang mendukung Streamable HTTP dapat menambahkan server dengan URL ini. Ini bentuk umum yang ditampilkan Dasbor:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Anda tidak memerlukan kunci API untuk mulai. Saat klien pertama kali terhubung, Anda masuk dengan akun VocalStack di peramban, dan klien menyimpan tokennya. Dasbor merangkumnya dalam satu baris: “Anda akan masuk dengan akun VocalStack Anda pada kali pertama. Tidak perlu kunci.”
Ini adalah spesifikasi otorisasi MCP yang sedang bekerja, bukan trik khusus VocalStack. Server jarak jauh menjawab permintaan yang tidak terautentikasi dengan 401 yang menunjuk ke metadata sumber daya yang dilindungi: dokumen JSON kecil yang menyebutkan server otorisasi dan cakupan yang dibutuhkan server. Klien membacanya, menjalankan alur OAuth 2.1 standar di peramban Anda, dan kembali dengan token yang diterbitkan khusus untuk server itu saja. Setiap server MCP jarak jauh yang mengikuti spesifikasi akan memberi Anda masuk dengan cara yang sama, itulah sebabnya klien di atas dapat melakukannya tanpa mengetahui apa pun tentang VocalStack.
Kunci API juga bisa dipakai, untuk klien yang berjalan di server atau dalam skrip. Kirimkan sebagai Authorization: Bearer vs_key_..., header yang sama dengan yang diterima REST API. Kunci dibuat di bawah Developers → API keys. Kedua alat transkripsi memerlukan izin Write dan Stream audio. Yang kedua terdengar janggal untuk sebuah file, tetapi alat-alat itu melewati titik pembuatan yang sama dengan setiap transkripsi, termasuk yang langsung, dan titik itu memeriksa keduanya. Alat pembacaan memerlukan Read; list_voices hanya memerlukan kredensial yang valid.
Setelah Anda masuk, agen melihat sembilan alat. Anda jarang menyebut namanya sendiri, tetapi mengetahuinya menjelaskan apa yang akan dilakukan agen berikutnya.
Setiap alat menerima dan mengembalikan JSON camelCase, dengan nama field yang sama seperti tipe wire /v1; handle sebuah transkripsi adalah transcriptionId-nya.
transcribe_url memulai transkripsi audio atau video di URL publik: tautan file, episode podcast, video YouTube. Siaran langsung tidak diterima. Argumen opsional: name, spokenLanguage (hilangkan untuk mendeteksi bahasa), speakerLabels (auto, on, atau off) dan startS/endS untuk mentranskripsi hanya sebagian audio.transcribe_file melakukan hal yang sama untuk file yang dipegang agen, dikirim sebagai fileBase64 dengan filename-nya. Ukuran setelah didekode dibatasi 10 MiB, kira-kira sepuluh menit MP3 128 kbps; untuk yang lebih besar, berikan tautan kepada agen.Keduanya langsung mengembalikan transcriptionId, state: "queued", dan petunjuk next yang menyebut alat penunggu. Transkripsi yang dibuat agen dimulai sebagai privat, tanpa tautan berbagi.
Agen tidak bisa menunggu siaran langsung dengan lebih sabar daripada Anda; ia akan terus memanggil alat penunggu sampai seseorang mengambil laptopnya. Rekaman yang sudah selesai memiliki akhir, dan itulah yang ditunggu oleh pasangan alat berikutnya.
Satu panggilan alat adalah satu permintaan HTTP, dan permintaan HTTP tidak dimaksudkan untuk berlangsung selama satu jam. Klien menyerah, proksi menutupnya, dan model yang terblokir pada satu alat tidak dapat melakukan hal lain. Jadi pola untuk pekerjaan panjang di balik MCP adalah pola yang juga dipakai REST API: mulai pekerjaan dan dapatkan handle, tunggu selama waktu yang terbatas, lalu panggil lagi jika belum selesai. Handle, bukan koneksi, yang membawa status.
wait_for_transcription menunggu sampai pekerjaan done atau failed, atau sampai timeoutS berlalu (standarnya 50 detik, maksimum 60, yang menjaga panggilan tetap di bawah batas waktu yang diterapkan sebagian besar klien dan proksi). Jika hasilnya berisi timedOut: true, pekerjaan masih berjalan dan agen memanggil alat itu lagi. Selama alat menunggu, server mengirim notifikasi kemajuan MCP jika klien memintanya: persentase dan fase, seperti "mengunduh 3.1 / 8.0 MB" atau "mentranskripsi 01:25 dari 02:00".get_transcription mengembalikan status dan, setelah selesai, teksnya. format: "text" memberi satu baris per segmen sebagai [mm:ss] Speaker 1: ...; "segments" memberi baris berwaktu dengan start, end, speaker, dan speakerName; includeWords: true menambahkan waktu setiap kata. Hasil dibagi per halaman (offset, limit, standarnya 500 segmen) dengan nextOffset jika masih ada sisanya.Pembagian halaman ini ditujukan untuk model, bukan untuk jaringan. Semua yang dikembalikan alat ditempelkan ke jendela konteks agen, tempat ia bersaing dengan percakapan Anda dan memakan token di setiap giliran berikutnya. Rapat dua jam berisi puluhan ribu kata; mengembalikan semuanya sekaligus akan mendorong pertanyaan Anda keluar dari konteks. Alat MCP yang baik mengembalikan satu halaman dan sebuah kursor, lalu membiarkan agen memutuskan seberapa banyak yang ia perlukan.
Putus koneksi atau batas waktu tidak pernah membatalkan pekerjaan, karena pekerjaan hidup di server, bukan di permintaan MCP. Setelah selesai, pekerjaan menjadi satu entri lagi di pustaka Anda, dan alat-alat berikutnya memperlakukannya seperti yang lain.
list_transcriptions mencantumkan transkripsi akun, yang terbaru lebih dulu, dengan status dan durasi; lifecycle berupa active, archived, atau all.search_transcriptions mencari apa yang diucapkan di semua transkripsi, dalam bahasa apa pun, dan mengembalikan baris yang cocok, masing-masing dengan transkripsinya dan detik saat diucapkan. transcriptionId mempersempit pencarian ke satu transkripsi; lang menambahkan terjemahan untuk setiap hasil.Menemukan satu baris itu mudah. Dua alat lain menentukan apa yang dikatakan secara keseluruhan.
get_summary mengembalikan judul dan ringkasan AI dari transkripsi yang sudah selesai, yang dapat diterjemahkan dengan lang. state: "pending" berarti ringkasan masih ditulis (biasanya siap dalam hitungan detik setelah pekerjaan selesai), dan agen bertanya lagi.translate_transcription mengembalikan transkrip yang sudah selesai dalam bahasa lain, sebagai teks atau segmen berwaktu, dibagi per halaman seperti get_transcription. Terjemahan disimpan, jadi bertanya lagi tidak mengulang pekerjaan.list_voices mencantumkan suara yang dapat membacakan transkrip dalam suatu bahasa: id, nama, jenis kelamin dan aksen jika diketahui, peringkat kualitas, serta apakah itu suara bawaan atau salah satu suara kloning Anda. Alat ini mendeskripsikan suara; ia tidak membuat suara berbicara (lebih lanjut tentang hal itu di bawah).Berikut cara alat-alat ini saling terhubung dalam praktiknya.
Setelah server ditambahkan, percakapan di Claude Code berjalan seperti ini. Anda menempelkan tautan podcast dan meminta ringkasannya dalam bahasa Prancis.
Agen memanggil transcribe_url:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Agen mendapatkan kembali transcriptionId dan state: "queued", lalu mengikuti petunjuk next:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Episode lima puluh menit ditranskripsi berkali-kali lebih cepat daripada waktu putarnya, tetapi tidak dalam satu kali tunggu. Tunggu pertama mengembalikan timedOut: true dengan kemajuan, misalnya, 61 persen, jadi agen memanggil alat sekali lagi dan mendapatkan state: "done".
Sekarang agen memanggil get_summary dengan lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Jika ringkasan masih pending, agen menunggu beberapa detik; jika tidak, ia menyerahkan kepada Anda judul dan ringkasan dalam bahasa Prancis. Tanyakan "di mana mereka membicarakan harga?" dan ia memanggil search_transcriptions dengan query: "pricing" dan transcriptionId yang sama, lalu mengutip baris yang cocok beserta stempel waktunya. Minta keseluruhannya dalam bahasa Prancis dan ia memanggil translate_transcription.
Beberapa panggilan alat, tanpa kode, dan satu transkripsi di pustaka Anda. Setiap panggilan itu melewati gerbang yang sama dengan permintaan REST, dan gerbang itulah yang menentukan tagihan dan batasnya.
Server MCP adalah API melalui pintu depan yang berbeda: batas yang sama, tagihan yang sama.
POST /v1/transcriptions: laju pembuatan paket (10, 100, atau angka khusus transkripsi yang dimulai per jam), batas transkripsi serentak (1, 5, atau tak terbatas), dan kredit paket berlaku semuanya. Kredit pendaftaran $5 cukup untuk sesi pertama, tanpa kartu.isError: true dengan kode galat REST API, sebuah kalimat yang dapat ditindaklanjuti model, serta kolom retryable dan retryAfterS. insufficient_credit membawa topUpUrl; rate_limited menyatakan berapa lama harus menunggu. Ini lebih penting dari kedengarannya: model membaca teks galat, jadi kalimat yang dapat ditindaklanjuti mengubah jalan buntu menjadi panggilan alat berikutnya./v1/mcp itu sendiri: agen yang berulang akan mendapat HTTP 429 dengan Retry-After sebelum alat mana pun berjalan.idempotencyKey: menggunakan ulang kunci dari panggilan yang sudah selesai akan memutar ulang hasil pertama, dan menggunakannya dengan argumen yang berbeda akan ditolak, sehingga agen yang mencoba ulang sendiri tidak pernah memulai pekerjaan kedua. Alat apa pun yang membelanjakan uang sebaiknya menawarkan ini; agen mencoba ulang jauh lebih bebas daripada manusia.Itulah batas dari apa yang dilakukan server. Dua hal berada di luar batas itu secara sengaja.
Server tidak punya alat yang mengubah teks sembarang menjadi ucapan, dan tidak ada yang direncanakan. VocalStack membacakan transkrip dan terjemahannya, dengan suara bawaan atau suara kloning, dan tidak ada yang lain. list_voices memberi tahu agen suara mana yang dapat membacakan transkrip dalam suatu bahasa, bukan cara membuat suara mengucapkan sesuatu yang baru.
Alat transkripsi juga menolak siaran langsung. Siaran langsung YouTube atau aliran radio memerlukan transkripsi langsung, yang dimulai dari Dasbor atau melalui POST /v1/transcriptions/live di Referensi API. Video YouTube yang sudah selesai adalah file, dan transcribe_url menerimanya.
Jika Anda lebih suka menulis kodenya sendiri, mentranskripsi file dengan API menjelaskan langkah yang sama sebagai panggilan HTTP, dan tutorial transkripsi real-time membahas WebSocket.