Server MCP promění API v několik pojmenovaných nástrojů, které agent volá uprostřed konverzace, a dlouhá úloha se do něj vejde, když nástroj vrátí identifikátor, na který agent čeká v omezených krocích. Vložte odkaz na podcast, požádejte o shrnutí ve francouzštině a žádný kód se nepíše.
Kódující agent může používat VocalStack API stejně jako libovolný program: přečte referenční příručku, napíše pár řádků proti SDK a spustí je. To je správná cesta pro něco, co poběží bez agenta.
MCP (Model Context Protocol) je určen pro opačný případ: mluvíte s asistentem a chcete, aby něco hned přepsal, bez kódu. Server MCP zveřejní krátký seznam pojmenovaných nástrojů, z nichž každý má popis a JSON schéma svých argumentů. Agent seznam přečte jednou a nástroj zavolá podle názvu, když požadavek odpovídá. „Přepiš tenhle podcast a řekni mi, co říkali o cenách“ se promění ve tři volání nástrojů a agent nikdy neuvidí HTTP cestu.
Servery jsou dvojího druhu. Lokální server běží jako podproces klienta a komunikuje přes stdio, což je způsob, jakým funguje většina serverů pro souborový systém a databáze. Vzdálený server sídlí za URL a mluví Streamable HTTP, transportem, který v březnové revizi specifikace z roku 2025 nahradil starší transport HTTP-plus-SSE (server-sent events). Klient odešle každý požadavek a server odpoví na stejném spojení; cokoli, co musí sdělit ještě před konečným výsledkem, se posílá streamem předem. Libovolný klient napsaný proti aktuální specifikaci může používat oba druhy.
VocalStacku server je vzdáleného druhu, na adrese {{api}}/v1/mcp, a používání stojí totéž co API. Potřebujete jen tu URL.
Otevřete v ovládacím panelu oblast Developers na {{app}}/developers. První záložka, Connect an AI agent, ukazuje URL serveru a nastavovací úryvek pro každého klienta. Tři úryvky níže odpovídají těm, které se tam zobrazují.
Spusťte to ve svém terminálu:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Přidejte to do .cursor/mcp.json ve svém projektu, nebo do ~/.cursor/mcp.json pro všechny projekty:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Jakýkoli klient, který podporuje Streamable HTTP, může server přidat pomocí této URL. Toto je obecný tvar, který ovládací panel zobrazuje:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Na začátek API klíč nepotřebujete. Při prvním připojení klienta se přihlásíte ke svému účtu VocalStack v prohlížeči a klient si token ponechá. Ovládací panel to shrnuje jednou větou: „Při prvním přihlášení se přihlásíte ke svému účtu VocalStack. Klíč není potřeba.“
Toto je autorizační specifikace MCP v praxi, ne trik VocalStacku. Vzdálený server odpoví neověřenému požadavku chybou 401, která ukazuje na jeho metadata chráněného zdroje: malý dokument JSON, který jmenuje autorizační server a rozsahy, jež server vyžaduje. Klient je přečte, v prohlížeči provede standardní tok OAuth 2.1 a vrátí se s tokenem vydaným právě pro tento server. Každý vzdálený server MCP, který specifikaci dodržuje, vás přihlásí stejně, a proto to výše uvedení klienti dokážou bez jakékoli znalosti VocalStacku.
API klíč také funguje, pro klienta běžícího na serveru nebo ve skriptu. Posílejte jej jako Authorization: Bearer vs_key_..., tedy stejnou hlavičku, jakou přijímá REST API. Klíče se vytvářejí v Developers → API keys. Dva nástroje pro přepis potřebují oprávnění Write a Stream audio. Druhé zní u souboru divně, ale nástroje procházejí stejným místem vytváření jako každý přepis, včetně živých, a to místo kontroluje obě. Nástroje pro čtení potřebují Read; list_voices potřebuje jen platné přihlášení.
Jakmile jste přihlášeni, agent vidí devět nástrojů. Sami je budete jmenovat jen zřídka, ale znalost pomůže pochopit, co agent udělá dál.
Každý nástroj přijímá a vrací JSON v camelCase se stejnými názvy polí jako typy /v1; identifikátor přepisu je jeho transcriptionId.
transcribe_url spustí přepis zvuku nebo videa na veřejné URL: odkaz na soubor, epizodu podcastu, video na YouTube. Živé streamy se nepřijímají. Volitelné argumenty jsou name, spokenLanguage (vynechte jej, pokud chcete jazyk zjistit automaticky), speakerLabels (auto, on nebo off) a startS/endS, abyste přepsali jen část zvuku.transcribe_file dělá totéž pro soubor, který agent drží, odeslaný jako fileBase64 se svým filename. Dekódovaná velikost je omezena na 10 MiB, zhruba deset minut MP3 se 128 kbps; u větších souborů dejte agentovi odkaz.Oba vrátí okamžitě transcriptionId, state: "queued" a nápovědu next, která jmenuje nástroj pro čekání. Přepisy vytvořené agentem začínají jako soukromé, bez sdíleného odkazu.
Agent nevydrží sedět u živého vysílání trpělivěji než vy; volal by nástroj pro čekání dál, dokud by mu někdo nevzal notebook. Dokončený záznam má konec, a na ten čeká následující dvojice nástrojů.
Volání nástroje je jeden požadavek HTTP a požadavky HTTP nejsou určeny k tomu, aby trvaly hodinu. Klienti je vzdávají, proxy je zavírají a model, který čeká na jeden nástroj, nemůže dělat nic jiného. Proto je vzorem pro každou dlouhou úlohu za MCP stejný vzor, jaký používá i REST API: spustit úlohu a dostat identifikátor, čekat na ni omezenou dobu a zavolat znovu, pokud ještě neskončila. Stav nese identifikátor, ne spojení.
wait_for_transcription blokuje, dokud úloha není done nebo failed, nebo dokud neuplyne timeoutS (výchozí 50 sekund, maximum 60, což udrží volání pod časovými limity, které uplatňuje většina klientů a proxy). Pokud výsledek říká timedOut: true, úloha stále běží a agent nástroj zavolá znovu. Zatímco nástroj čeká, server posílá oznámení o průběhu MCP, pokud je klient vyžádal: procento a fázi, například „načítání 3.1 / 8.0 MB“ nebo „přepisování 01:25 z 02:00“.get_transcription vrací stav a po dokončení text. format: "text" dává jeden řádek na segment ve tvaru [mm:ss] Speaker 1: ...; "segments" vrací časované řádky s start, end, speaker a speakerName; includeWords: true přidá časy slov. Výsledky jsou stránkované (offset, limit, výchozí 500 segmentů) s nextOffset, když zbývá více.Stránkování je tu kvůli modelu, ne kvůli síti. Všechno, co nástroj vrátí, se vloží do kontextového okna agenta, kde soupeří s vaší konverzací a stojí tokeny při každém dalším kroku. Dvouhodinová schůzka jsou desítky tisíc slov; vrátit ji celou najednou by vytlačilo otázku, kterou jste položili, z kontextu. Dobré nástroje MCP vracejí stránku a kurzor a nechají agenta rozhodnout, kolik potřebuje.
Odpojení nebo vypršení časového limitu nikdy úlohu nezruší, protože úloha žije na serveru, ne v požadavku MCP. Jakmile je hotová, je to jeden další záznam ve vaší knihovně a další nástroje s ním zacházejí jako s každým jiným.
list_transcriptions vypíše přepisy účtu od nejnovějšího, se stavem a délkou; lifecycle je active, archived nebo all.search_transcriptions prohledá, co bylo řečeno, napříč všemi přepisy, v jakémkoli jazyce, a vrátí odpovídající řádky, každý s jeho přepisem a sekundou, kdy zazněl. transcriptionId zúží hledání na jeden přepis; lang přidá k pokaždé nalezenému řádku jeho překlad.Najít řádek je levná polovina. Dva další nástroje zjistí, co říkal celek.
get_summary vrátí AI název a shrnutí dokončeného přepisu, volitelně přeložené pomocí lang. state: "pending" znamená, že shrnutí se ještě píše (obvykle je připraveno během několika sekund po dokončení úlohy), a agent se zeptá znovu.translate_transcription vrátí dokončený přepis v jiném jazyce, jako text nebo časované segmenty, stránkované jako get_transcription. Překlady se ukládají, takže opětovný dotaz neopakuje práci.list_voices vypíše hlasy, které mohou přečíst přepis v daném jazyce: identifikátor, název, pohlaví a přízvuk, jsou-li známy, hodnocení kvality a zda jde o výchozí hlas, nebo jeden z vašich klonovaných hlasů. Hlasy popisuje; nenechá žádný z nich něco říct (k tomu, co server nedělá, níže).Takto nástroje v praxi navazují.
Jakmile je server přidán, konverzace v Claude Code vypadá takto. Vložíte odkaz na podcast a požádáte o shrnutí ve francouzštině.
Agent zavolá transcribe_url:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Dostane zpět transcriptionId a state: "queued" a řídí se nápovědou next:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Padesátiminutová epizoda se přepíše mnohokrát rychleji, než se přehrává, ale ne uvnitř jediného čekání. První čekání vrátí timedOut: true s průběhem, řekněme 61 procent, takže agent nástroj zavolá ještě jednou a dostane state: "done".
Teď agent zavolá get_summary s lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Pokud je shrnutí stále pending, agent několik sekund počká; jinak vám předá název a shrnutí ve francouzštině. Zeptáte-li se „kde mluvili o cenách?“, zavolá search_transcriptions s query: "pricing" a stejným transcriptionId a citovat bude odpovídající řádky s jejich časovými značkami. Požádáte-li o celý přepis ve francouzštině, zavolá translate_transcription.
Několik volání nástrojů, žádný kód a přepis ve vaší knihovně. Každé z těchto volání prošlo stejnými branami jako požadavek REST a právě ony určují účet a limity.
Server MCP je API přes jiné vstupní dveře: stejné limity, stejný účet.
POST /v1/transcriptions: platí tarifní rychlost vytváření (10, 100 nebo vlastní počet přepisů spuštěných za hodinu), limit souběžných přepisů (1, 5 nebo neomezený) a váš kredit. Kredit $5 při registraci pokryje první relaci, bez karty.isError: true s kódem chyby REST API, větou, podle které model může jednat, a poli retryable a retryAfterS. insufficient_credit nese topUpUrl; rate_limited říká, jak dlouho čekat. To je důležitější, než zní: model čte text chyby, takže věta, podle které může jednat, promění slepou uličku v další volání nástroje./v1/mcp: smyčkující se agent dostane HTTP 429 s Retry-After, dřív než běží jakýkoli nástroj.idempotencyKey: opětovné použití klíče dokončeného volání zopakuje první výsledek, a opětovné použití s jinými argumenty je odmítnuto, takže agent, který zkouší znovu sám od sebe, nikdy nespustí druhou úlohu. Každý nástroj, který utrácí peníze, by ji měl nabízet; agenti zkouší znovu mnohem ochotněji než lidé.Tyto hranice jsou krajní mez toho, co server dělá. Dvě věci leží za nimi úmyslně.
Server nemá nástroj, který by převedl libovolný text na řeč, a žádný se neplánuje. VocalStack mluví přepisy a jejich překlady, standardním nebo klonovaným hlasem, a nic dalšího. list_voices říká agentovi, které hlasy mohou přečíst přepis v daném jazyce, ne jak přimět hlas říct něco nového.
Nástroje pro přepis také odmítají živé streamy. Živý stream na YouTube nebo rozhlasová stanice potřebuje živý přepis, spuštěný z ovládacího panelu nebo přes POST /v1/transcriptions/live v referenční příručce API. Dokončené video na YouTube je soubor a transcribe_url ho přijme.
Pokud raději napíšete kód sami, přepis souboru přes API prochází stejné kroky jako volání HTTP a návod pro reálný čas popisuje WebSocket.