Mae gweinydd MCP yn troi API yn ychydig o offer wedi'u henwi y mae asiant yn eu galw yng nghanol sgwrs, a gall swydd hir ffitio y tu ôl i un pan fydd yr offeryn yn rhoi cyfeiriad y mae'r asiant yn aros amdano mewn tro cyfyngedig. Gludwch ddolen bodlediad, gofynnwch am hanfod y peth yn Ffrangeg, ac ni ysgrifennir unrhyw god.
Gall asiant codio ddefnyddio API VocalStack yn yr un ffordd ag unrhyw raglen: darllen y cyfeirnod API, ysgrifennu ychydig linellau yn erbyn yr SDK, a'u rhedeg. Dyna'r llwybr cywir ar gyfer rhywbeth a fydd yn rhedeg heb yr asiant.
Mae MCP (y Model Context Protocol) ar gyfer yr achos arall: rydych chi'n siarad â chynorthwyydd ac eisiau iddo drawsgrifio rhywbeth nawr, heb god. Mae gweinydd MCP yn cyhoeddi rhestr fer o offer wedi'u henwi, pob un gyda disgrifiad a sgema JSON ar gyfer ei ddadleuon. Mae'r asiant yn darllen y rhestr unwaith ac yn galw offeryn wrth ei enw pan fydd cais yn cyfateb iddo. "Trawsgrifiwch y bodlediad hwn a dywedwch wrthyf beth ddywedon nhw am brisio" yn dod yn dri galwad offeryn, ac nid yw'r asiant byth yn gweld llwybr HTTP.
Mae dau fath o weinydd. Mae gweinydd lleol yn rhedeg fel is-broses o'r cleient ac yn siarad dros stdio, fel y mae'r rhan fwyaf o weinyddion system ffeiliau a chronfeydd data yn gweithio. Mae gweinydd o bell y tu ôl i URL ac yn siarad Streamable HTTP, y cludiant a gymerodd le'r cludiant HTTP-plus-SSE (digwyddiadau a anfonir gan y gweinydd) hŷn yn adolygiad Mawrth 2025 o'r manyleb. Mae'r cleient yn postio pob cais, ac mae'r gweinydd yn ateb ar yr un cysylltiad; mae unrhyw beth y mae angen iddo ei ddweud cyn y canlyniad terfynol yn cael ei ffrydio o'i flaen. Gall unrhyw gleient a ysgrifennwyd yn erbyn y fanyleb gyfredol ddefnyddio'r naill fath neu'r llall.
Gweinydd o bell yw gweinydd VocalStack, yn {{api}}/v1/mcp, ac mae ei ddefnyddio yn costio'r hyn y mae'r API yn ei gostio. Y cyfan sydd ei angen arnoch yw'r URL.
Agorwch ardal Developers y Dangosfwrdd yn {{app}}/developers. Mae'r tab cyntaf, Connect an AI agent, yn dangos URL y gweinydd a darn gosod ar gyfer pob cleient. Mae'r tri darn isod yn cyfateb i'r rhai a ddangosir yno.
Rhedwch hyn yn eich terfynell:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Ychwanegwch hyn at .cursor/mcp.json yn eich prosiect, neu at ~/.cursor/mcp.json ar gyfer pob prosiect:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Gall unrhyw gleient sy'n cefnogi Streamable HTTP ychwanegu'r gweinydd gyda'r URL hwn. Dyma'r ffurf gyffredinol y mae'r Dangosfwrdd yn ei dangos:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Nid oes angen allwedd API i ddechrau. Y tro cyntaf i'r cleient gysylltu, rydych chi'n mewngofnodi gyda'ch cyfrif VocalStack yn y porwr, ac mae'r cleient yn cadw'r tocyn. Mae'r Dangosfwrdd yn ei roi mewn un llinell: "Byddwch yn mewngofnodi gyda'ch cyfrif VocalStack y tro cyntaf. Nid oes angen allwedd."
Dyma fanyleb awdurdodi MCP ar waith, nid tric VocalStack. Mae gweinydd o bell yn ateb cais heb ddilysiad gyda 401 sy'n pwyntio at ei fetadata adnodd gwarchodedig: dogfen JSON fach sy'n enwi'r gweinydd awdurdodi a'r cwmpasau sydd eu hangen ar y gweinydd. Mae'r cleient yn ei darllen, yn rhedeg llif OAuth 2.1 safonol yn eich porwr, ac yn dychwelyd gyda thocyn a gyhoeddwyd ar gyfer y gweinydd hwnnw yn unig. Mae unrhyw weinydd MCP o bell sy'n dilyn y manyleb yn eich mewngofnodi yn yr un ffordd, a dyna pam y gall y cleientiaid uchod wneud hynny heb wybod dim am VocalStack.
Mae allwedd API hefyd yn gweithio, ar gyfer cleient sy'n rhedeg ar weinydd neu mewn sgript. Anfonwch hi fel Authorization: Bearer vs_key_..., yr un pennawd y mae'r REST API yn ei dderbyn. Crëir allweddi o dan Developers → API keys. Mae angen y caniatadau Write a Stream audio ar y ddau offeryn trawsgrifio. Mae'r ail yn swnio'n od ar gyfer ffeil, ond mae'r offer yn mynd drwy'r un pwynt creu â phob trawsgrifiad, rhai byw hefyd, ac mae'r pwynt hwnnw'n gwirio'r ddau. Mae angen Read ar yr offer darllen; mae list_voices ond angen tystlythyr dilys.
Unwaith y byddwch wedi mewngofnodi, mae'r asiant yn gweld naw offeryn. Prin y byddwch yn eu henwi eich hun, ond mae gwybod amdanynt yn egluro beth mae'r asiant yn ei wneud nesaf.
Mae pob offeryn yn cymryd ac yn dychwelyd JSON camelCase, gyda'r un enwau maes â mathau wifren /v1; ei gyfeiriad yw ei transcriptionId.
transcribe_url yn dechrau trawsgrifio sain neu fideo ar URL cyhoeddus: dolen ffeil, pennod bodlediad, fideo YouTube. Ni dderbynnir ffrydiau byw. Dadleuon dewisol: name, spokenLanguage (hepgorwch ef i ganfod yr iaith), speakerLabels (auto, on neu off) a startS/endS i drawsgrifio rhan o'r sain yn unig.transcribe_file yn gwneud yr un peth ar gyfer ffeil sydd gan yr asiant, wedi'i hanfon fel fileBase64 gyda'i filename. Mae'r maint wedi'i ddatgodio wedi'i gyfyngu i 10 MiB, tua 10 munud o MP3 128 kbps; ar gyfer unrhyw beth mwy, rhowch ddolen i'r asiant.Mae'r ddau yn dychwelyd ar unwaith gyda'r transcriptionId, state: "queued" ac awgrym next sy'n enwi'r offeryn aros. Mae trawsgrifiadau a grëir gan asiant yn dechrau'n breifat, heb ddolen rannu.
Ni all asiant eistedd trwy ddarllediad byw yn fwy amyneddgar nag y gallwch chi; byddai'n dal i alw'r offeryn aros nes i rywun gymryd y gliniadur oddi arno. Mae recordiad gorffenedig yn dod i ben, a dyna y mae'r ddau offeryn nesaf yn aros amdano.
Un cais HTTP yw un galwad offeryn, ac nid yw ceisiadau HTTP i fod i bara awr. Mae cleientiaid yn rhoi'r gorau iddyn nhw, mae dirprwyon yn eu cau, ac ni all model sydd wedi'i rwystro gan un offeryn wneud dim arall. Felly'r patrwm ar gyfer unrhyw swydd hir y tu ôl i MCP yw'r un y mae'r REST API yn ei ddefnyddio hefyd: cychwyn y swydd a chael cyfeiriad, aros amdani am amser cyfyngedig, a galw eto os nad yw wedi gorffen. Y cyfeiriad, nid y cysylltiad, sy'n cario'r cyflwr.
wait_for_transcription yn blocio nes bod y swydd yn done neu failed, neu nes bod timeoutS yn mynd heibio (50 eiliad yn ddiofyn, 60 yn uchafswm, sy'n cadw'r alwad o dan y terfynau amser y mae'r rhan fwyaf o gleientiaid a dirprwyon yn eu cymhwyso). Os yw'r canlyniad yn dweud timedOut: true, mae'r swydd yn dal i redeg ac mae'r asiant yn galw'r offeryn eto. Tra bo'r offeryn yn aros, mae'r gweinydd yn anfon hysbysiadau cynnydd MCP os yw'r cleient wedi gofyn amdanynt: canran a cham fel "yn lawrlwytho 3.1 / 8.0 MB" neu "yn trawsgrifio 01:25 o 02:00".get_transcription yn dychwelyd y statws ac, unwaith y mae wedi gorffen, y testun. Mae format: "text" yn rhoi un llinell i bob segment fel [mm:ss] Speaker 1: ...; mae "segments" yn rhoi llinellau wedi'u hamseru gyda start, end, speaker a speakerName; mae includeWords: true yn ychwanegu amseriadau geiriau. Mae'r canlyniadau wedi'u tudalennu (offset, limit, 500 o segmentau yn ddiofyn) gyda nextOffset pan fo mwy ar ôl.Mae'r tudalennu yno ar gyfer y model, nid y rhwydwaith. Mae popeth y mae offeryn yn ei ddychwelyd yn cael ei gludo i ffenestr cyd-destun yr asiant, lle mae'n cystadlu â'ch sgwrs ac yn costio tocynnau ym mhob tro diweddarach. Mae cyfarfod dwy awr yn ddegau o filoedd o eiriau; byddai dychwelyd y cyfan ar unwaith yn gwthio'r cwestiwn a ofynnwyd gennych allan o'r cyd-destun. Mae offer MCP da yn dychwelyd tudalen a chyrchwr, ac yn gadael i'r asiant benderfynu faint sydd ei angen arno.
Nid yw datgysylltiad neu derfyn amser byth yn canslo'r swydd, gan fod y swydd yn byw ar y gweinydd, nid yn y cais MCP. Unwaith y mae wedi gorffen, mae'r swydd yn un cofnod arall yn eich llyfrgell, ac mae'r offer nesaf yn ei drin fel unrhyw un arall.
list_transcriptions yn rhestru trawsgrifiadau'r cyfrif, y rhai mwyaf newydd yn gyntaf, gyda statws a hyd; lifecycle yw active, archived neu all.search_transcriptions yn chwilio'r hyn a ddywedwyd ar draws pob trawsgrifiad, mewn unrhyw iaith, ac yn dychwelyd y llinellau cyfatebol, pob un gyda'i drawsgrifiad a'r eiliad y'i siaradwyd. Mae transcriptionId yn cyfyngu'r chwiliad i un trawsgrifiad; mae lang yn ychwanegu cyfieithiad o bob canlyniad.Dod o hyd i linell yw'r hanner rhad. Mae dau offeryn arall yn cyfrifo beth ddywedwyd yn y cyfan.
get_summary yn dychwelyd teitl a chrynodeb AI trawsgrifiad sydd wedi gorffen, wedi'i gyfieithu yn ddewisol gyda lang. Mae state: "pending" yn golygu bod y crynodeb yn dal i gael ei ysgrifennu (fel arfer mae'n barod o fewn eiliadau i'r swydd orffen), ac mae'r asiant yn gofyn eto.translate_transcription yn dychwelyd trawsgrifiad gorffenedig mewn iaith arall, fel testun neu segmentau wedi'u hamseru, wedi'u tudalennu fel get_transcription. Mae cyfieithiadau'n cael eu storio, felly nid yw gofyn eto yn ailadrodd y gwaith.list_voices yn rhestru'r lleisiau a all ddarllen trawsgrifiad mewn iaith: id, enw, rhyw ac acen pan fo'n hysbys, sgôr ansawdd, ac a yw'n llais diofyn neu'n un o'ch lleisiau wedi'u clonio. Mae'n disgrifio lleisiau; nid yw'n gwneud i un siarad (mwy isod am yr hyn nad yw'r gweinydd yn ei wneud).Dyma sut mae'r offer yn cysylltu â'i gilydd yn ymarferol.
Unwaith y mae'r gweinydd wedi'i ychwanegu, mae sgwrs yn Claude Code yn mynd fel hyn. Rydych chi'n gludo dolen bodlediad ac yn gofyn am hanfod y peth yn Ffrangeg.
Mae'r asiant yn galw transcribe_url:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Mae'n cael yn ôl transcriptionId a state: "queued", ac yn dilyn yr awgrym next:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Trawsgrifir pennod o 50 munud lawer gwaith yn gyflymach nag y mae'n chwarae, ond nid o fewn un aros. Mae'r aros cyntaf yn dychwelyd timedOut: true gyda chynnydd ar, dyweder, 61 y cant, felly mae'r asiant yn galw'r offeryn unwaith eto ac yn cael state: "done".
Nawr mae'r asiant yn galw get_summary gyda lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Os yw'r crynodeb yn dal yn pending, mae'r asiant yn aros ychydig eiliadau; fel arall mae'n rhoi teitl a chrynodeb i chi yn Ffrangeg. Gofynnwch "ble buon nhw'n siarad am brisio?" ac mae'n galw search_transcriptions gyda query: "pricing" a'r un transcriptionId, ac yn dyfynnu'r llinellau cyfatebol gyda'u hamserau. Gofynnwch am y cyfan yn Ffrangeg ac mae'n galw translate_transcription.
Ychydig o alwadau offeryn, dim cod, a thrawsgrifiad yn eich llyfrgell. Aeth pob un o'r galwadau hynny drwy'r un pyrth â chais REST, a'r pyrth hynny sy'n pennu'r bil a'r terfynau.
Y gweinydd MCP yw'r API drwy ddrws ffrynt gwahanol: yr un terfynau, yr un bil.
POST /v1/transcriptions: mae cyfradd creu'r cynllun (10, 100 neu nifer personol o drawsgrifiadau a ddechreuwyd yr awr), ei derfyn trawsgrifio cydamserol (1, 5 neu di-ben-draw) a'i gredyd i gyd yn berthnasol. Mae'r credyd cofrestru $5 yn talu am sesiwn gyntaf, heb fod angen cerdyn.isError: true gyda chod gwall yr API REST, brawddeg y gall y model weithredu arni, a'r meysydd retryable a retryAfterS. Mae insufficient_credit yn cario topUpUrl; mae rate_limited yn dweud pa mor hir i aros. Mae hyn yn bwysicach nag y mae'n swnio: mae model yn darllen testun y gwall, felly mae brawddeg y gall weithredu arni yn troi pen draw marw yn yr alwad offeryn nesaf./v1/mcp ei hun: mae asiant mewn dolen yn cael HTTP 429 gyda Retry-After cyn i unrhyw offeryn redeg.idempotencyKey: mae ailddefnyddio'r un idempotencyKey o alwad sydd wedi gorffen yn ail-chwarae'r canlyniad cyntaf, ac mae ailddefnyddio gyda dadleuon gwahanol yn cael ei wrthod, felly ni fydd asiant sy'n ailgeisio ar ei ben ei hun byth yn dechrau ail swydd. Dylai unrhyw offeryn sy'n gwario arian gynnig hyn; mae asiantau'n ailgeisio'n llawer mwy rhydd nag y mae pobl yn ei wneud.Dyna ymylon yr hyn y mae'r gweinydd yn ei wneud. Mae dau beth y tu allan iddynt yn fwriadol.
Nid oes gan y gweinydd offeryn sy'n troi testun mympwyol yn lleferydd, ac nid oes un wedi'i gynllunio. Mae VocalStack yn llefaru trawsgrifiadau a'u cyfieithiadau, mewn llais parod neu lais wedi'i glonio, ac ni wna ddim arall. Mae list_voices yn dweud wrth asiant pa leisiau a all ddarllen trawsgrifiad mewn iaith, nid sut i wneud i lais ddweud rhywbeth newydd.
Mae'r offer trawsgrifio hefyd yn gwrthod ffrydiau byw. Mae ffrwd fyw YouTube neu ffrwd radio yn angen trawsgrifiad byw, wedi'i ddechrau o'r Ddangosfwrdd neu drwy POST /v1/transcriptions/live yn y cyfeirnod API. Mae fideo YouTube gorffenedig yn ffeil, ac mae transcribe_url yn ei derbyn.
Os hoffech ysgrifennu'r cod eich hun, mae trawsgrifio ffeil gyda'r API yn mynd drwy'r un camau â galwadau HTTP, ac mae'r tiwtorial amser real yn ymdrin â'r WebSocket.