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.
Адкрыйце раздзел Developers ў панэлі кіравання па адрасе {{app}}/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. Ключ не патрэбны.»
Гэта працуе па спецыфікацыі аўтарызацыі MCP, а не па нейкай асаблівасці VocalStack. Выдалены сервер на неаўтарызаваны запыт адказвае кодам 401 са спасылкай на метаданыя свайго абароненага рэсурсу — невялікі JSON-дакумент, які называе сервер аўтарызацыі і патрэбныя правы доступу (scopes). Кліент чытае яго, у браўзеры праходзіць стандартны працэс OAuth 2.1 і вяртаецца з токенам, выдадзеным толькі для гэтага сервера. Любы выдалены MCP-сервер, які выконвае спецыфікацыю, уваходзіць так жа, таму кліенты вышэй могуць гэта рабіць, нічога не ведаючы пра VocalStack.
Ключ API таксама падыходзіць для кліента, які працуе на серверы або ў скрыпце. Адпраўляйце яго як Authorization: Bearer vs_key_... — той самы загаловак, які прымае REST API. Ключы ствараюцца ў Developers → API keys. Для двух інструментаў транскрыбавання патрэбны правы Write і Stream audio. Другое права для файла можа здацца дзіўным, але інструменты праходзяць праз тую ж кропку стварэння, што і кожная транскрыпцыя, у тым ліку жывыя, а гэтая кропка правярае абодва. Інструментам чытання патрэбны Read; list_voices патрабуе толькі сапраўдных уліковых дадзеных.
Пасля ўваходу агент бачыць дзевяць інструментаў. Вы рэдка будзеце называць іх самі, але веданне іх тлумачыць, што агент зробіць далей.
Кожны інструмент прымае і вяртае JSON у camelCase, з тымі ж назвамі палёў, што і ў тыпах /v1; маркерам транскрыпцыі служыць яе transcriptionId.
transcribe_url пачынае транскрыбаванне аўдыя або відэа па публічным URL: спасылка на файл, эпізод падкаста, відэа на YouTube. Прамыя трансляцыі не прымаюцца. Неабавязковыя аргументы: name, spokenLanguage (калі яго не паказваць, мова вызначаецца аўтаматычна), speakerLabels (auto, on або off) і startS/endS, каб транскрыбаваць толькі частку аўдыя.transcribe_file робіць тое ж для файла, які ёсць у агента, — ён перадаецца ў fileBase64 з filename. Памер пасля дэкадавання абмежаваны 10 MiB, гэта прыблізна дзесяць хвілін MP3 з бітрэйтам 128 kbps; для большага файла дайце агенту спасылку.Абодва інструменты адразу вяртаюць transcriptionId, state: "queued" і падказку next з назвай інструмента чакання. Транскрыпцыі, створаныя агентам, пачынаюцца як прыватныя, без спасылкі для агульнага доступу.
Агент не можа цярпліва прасядзець жывую трансляцыю даўжэй за вас: ён будзе зноў і зноў выклікаць інструмент чакання, пакуль хтосьці не забярэ ў яго ноўтбук. У гатовага запісу ёсць канец, і менавіта яго чакаюць наступныя два інструменты.
Выклік інструмента — гэта адзін HTTP-запыт, а HTTP-запыты не прызначаны для таго, каб доўжыцца гадзіну. Кліенты адмаўляюцца ад іх, проксі закрываюць іх, а мадэль, заблякаваная адным інструментам, ні на што больш не здольная. Таму шаблон для любой доўгай задачы праз MCP той самы, што і ў REST API: запусціць задачу і атрымаць маркер, чакаць на яго абмежаваны час і выклікаць зноў, калі яна не гатовая. Стан нясе маркер, а не злучэнне.
wait_for_transcription чакае, пакуль задача не стане done або failed, або пакуль не мінуць timeoutS (па змаўчанні 50 секунд, максімум 60 — гэта ўкладваецца ў тайм-аўты, якія ўжываюць большасць кліентаў і проксі). Калі вынік мае timedOut: true, задача яшчэ ідзе, і агент выклікае інструмент зноў. Пакуль інструмент чакае, сервер адпраўляе апавяшчэнні пра прагрэс MCP, калі кліент іх запытаў: працэнт і этап, напрыклад «запампоўка 3,1 / 8,0 MB» або «транскрыбаванне 01:25 з 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".
Цяпер агент выклікае get_summary з lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Калі падсумаванне ўсё яшчэ pending, агент чакае некалькі секунд; інакш ён падае вам назву і падсумаванне па-французску. Спытайце: «Дзе яны казалі пра цэны?» — і ён выклікае search_transcriptions з query: "pricing" і тым жа transcriptionId, а потым цытуе знойдзеныя радкі з тайм-кодамі. Калі вы просіце ўвесь тэкст па-французску, ён выклікае 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: цыкліруючы агент атрымлівае HTTP 429 з Retry-After яшчэ да запуску любога інструмента.idempotencyKey: паўторны выклік з ключом завершанага выкліку вяртае першы вынік, а паўтарэнне з іншымі аргументамі адхіляецца, таму агент, які паўторна спрабуе сам, ніколі не запускае другую задачу. Любы інструмент, які тратуе грошы, павінен прапаноўваць гэта; агенты паўтараюць спробы значна смялей, чым людзі.Гэта межы таго, што робіць сервер. Два пункты свядома ляжаць па-за імі.
У сервера няма інструмента, які ператварае любы тэкст у маўленне, і такі не плануецца. VocalStack агучвае транскрыпты і іх пераклады стандартным або кланаваным голасам і нічога больш. list_voices паведамляе агенту, якія галасы могуць прачытаць транскрыпт на пэўнай мове, а не як прымусіць голас сказаць нешта новае.
Інструменты транскрыбавання таксама адмаўляюцца ад прамых трансляцый. Прамую трансляцыю YouTube або радыёстрым трэба транскрыбаваць у рэжыме жывой транскрыпцыі, запушчанай з панэлі кіравання або праз POST /v1/transcriptions/live у даведніку API. Гатовае відэа на YouTube — гэта файл, і transcribe_url яго прымае.
Калі вы хочаце напісаць код самі, транскрыбаванне файла з дапамогай API паказвае тыя ж крокі як HTTP-выклікі, а дапаможнік па транскрыбаванні ў рэальным часе апісвае WebSocket.