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 को सर्भर रिमोट प्रकारको हो, {{api}}/v1/mcp मा छ, र यसको प्रयोगमा API ले जति खर्च लाग्छ त्यति नै लाग्छ। तपाईंलाई चाहिने भनेको मात्र URL हो।
ड्यासबोर्डको {{app}}/developers मा 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 को authorization spec को काम हो। रिमोट सर्भरले प्रमाणीकरण नगरिएको अनुरोधलाई 401 फर्काउँछ, जसले protected-resource metadata तर्फ इशारा गर्छ: सर्भरलाई चाहिने authorization server र scope नाम दिने एउटा सानो JSON कागजात। क्लाइन्टले त्यो पढ्छ, तपाईंको ब्राउजरमा मानक OAuth 2.1 प्रवाह चलाउँछ, र त्यही सर्भरका लागि जारी गरिएको टोकन लिएर फर्कन्छ। स्पेक पालना गर्ने कुनै पनि रिमोट MCP सर्भरले तपाईंलाई त्यसै गरी साइन इन गराउँछ, त्यसैले माथिका क्लाइन्टहरूले VocalStack बारे केही नजानी त्यो गर्न सक्छन्।
API कुञ्जी पनि काम गर्छ, सर्भरमा वा स्क्रिप्टमा चलिरहेको क्लाइन्टको लागि। यसलाई Authorization: Bearer vs_key_... रूपमा पठाउनुहोस्, REST API ले लिने उही हेडर। कुञ्जीहरू Developers → API keys अन्तर्गत बनाइन्छन्। दुई transcribe उपकरणहरूलाई Write र Stream audio अनुमति चाहिन्छ। दोस्रो फाइलको लागि अनौठो लाग्छ, तर उपकरणहरू हरेक ट्रान्सक्रिप्सनले प्रयोग गर्ने उही सिर्जना बिन्दुबाट जान्छन्, लाइभ पनि समावेश गरी, र त्यो बिन्दुले दुवै जाँच गर्छ। पढ्ने उपकरणहरूलाई Read चाहिन्छ; list_voices लाई मान्य प्रमाणपत्र मात्र चाहिन्छ।
साइन इन भएपछि एजेन्टले नौवटा उपकरण देख्छ। तपाईं आफैँ तिनीहरूको नाम विरलै लिनुहुनेछ, तर तिनीहरूलाई जान्दा एजेन्टले अर्को के गर्छ भन्ने बुझिन्छ।
हरेक उपकरणले camelCase JSON लिन्छ र फर्काउँछ, /v1 wire types मा भएकै फिल्ड नामसहित; ट्रान्सक्रिप्सनको ह्यान्डल भनेको उसको 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 प्रगति सूचनाहरू पठाउँछ: प्रतिशत र चरण, जस्तै "fetching 3.1 / 8.0 MB" वा "transcribing 01:25 of 02:00"।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 ले एजेन्टलाई कुन आवाजले कुनै भाषामा ट्रान्सक्रिप्ट पढ्न सक्छ भनेर बताउँछ, कसरी आवाजलाई नयाँ कुरा भन्न लगाउने भनेर होइन।
transcribe उपकरणहरूले लाइभ स्ट्रिम पनि अस्वीकार गर्छन्। YouTube लाइभ स्ट्रिम वा रेडियो स्ट्रिमलाई ड्यासबोर्डबाट वा API सन्दर्भ मा POST /v1/transcriptions/live मार्फत सुरु गरिएको लाइभ ट्रान्सक्रिप्सन चाहिन्छ। समाप्त भएको YouTube भिडियो एउटा फाइल हो, र transcribe_url ले त्यसलाई लिन्छ।
आफैँ कोड लेख्न चाहनुहुन्छ भने, API सँग फाइल ट्रान्सक्रिप्ट गर्ने ले उही चरणहरू HTTP कलका रूपमा देखाउँछ, र रियल-टाइम ट्यूटोरियल ले WebSocket समेट्छ।