MCP серверот го претвора API-то во неколку именувани алатки што агентот ги повикува усред разговор, а долга работа стои зад една алатка кога таа враќа рачка на која агентот чека во ограничени интервали. Залепете линк до подкаст, побарајте резиме на француски и не се пишува ниту една линија код.
Агент за програмирање може да го користи VocalStack API-то како што секоја програма го користи: да ја прочита API референцата, да напише неколку линии со SDK-то и да ги изврши. Тоа е вистинскиот пат за нешто што ќе работи без агентот.
MCP (Model Context Protocol) е за другиот случај: разговарате со асистент и сакате да транскрибира нешто сега, без код. MCP серверот објавува краток список именувани алатки, секоја со опис и JSON шема за нејзините аргументи. Агентот го чита списокот еднаш и ја повикува алатката по име кога барањето ќе се поклопи со неа. „Транскрибирај го овој подкаст и кажи ми што рекоа за цените“ се претвора во три повици на алатки, а агентот никогаш не го гледа HTTP патот.
Серверите се два вида. Локалниот сервер работи како подпроцес на клиентот и комуницира преку stdio, така работат повеќето сервери за датотечни системи и бази на податоци. Далечинскиот сервер стои зад URL и зборува Streamable HTTP, транспортот што го замени постариот HTTP-plus-SSE (server-sent events) транспорт во мартовската ревизија на спецификацијата од 2025. Клиентот го испраќа секое барање, а серверот одговара на истата врска; сè што има да каже пред конечниот резултат се испраќа однапред во поток. Секој клиент напишан според сегашната спецификација може да користи кој било од двата вида.
Серверот на 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 документ што ги именува серверот за авторизација и опсезите што серверот ги бара. Клиентот го чита, извршува стандарден OAuth 2.1 тек во прелистувачот и се враќа со токен издаден за тој сервер единствено. Секој далечински MCP сервер што ја следи спецификацијата ве најавува на ист начин, затоа клиентите погоре можат да го направат тоа без да знаат што и да е за VocalStack.
API клуч исто така работи, за клиент што работи на сервер или во скрипта. Испратете го како Authorization: Bearer vs_key_..., истиот заглавие што го прима REST API-то. Клучевите се создаваат под Developers → API keys. Двете алатки за транскрипција бараат дозволби Write и Stream audio. Втората звучи чудно за датотека, но алатките минуваат преку истата точка на создавање како секоја транскрипција, вклучително и онаа во живо, а таа точка ги проверува и двете. Алатките за читање бараат Read; list_voices бара само валидни акредитиви.
Откако ќе се најавите, агентот ги гледа девет алатки. Ретко ќе ги именувате сами, но познавањето на нив објаснува што агентот ќе направи понатаму.
Секоја алатка прима и враќа camelCase JSON, со истите имиња на полињата како /v1 wire типовите; рачката на една транскрипција е нејзиниот 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-от.