Un servidor MCP converte unha API en poucas ferramentas con nome que un agente chama no medio dunha conversa, e un traballo longo cabe detrás dunha delas cando a ferramenta devolve un identificador que o agente agarda en quendas limitadas. Pega a ligazón dun podcast, pide o resumo en francés e non se escribe ningún código.
Un agente de programación pode usar a API de VocalStack do mesmo xeito que calquera programa: ler a referencia da API, escribir algunhas liñas co SDK e executalas. Esa é a vía axeitada para algo que se vaia executar sen o agente.
MCP (o Model Context Protocol) é para o outro caso: estás a falar cun asistente e queres que transcriba algo agora, sen código. Un servidor MCP publica unha lista curta de ferramentas con nome, cada unha cunha descrición e un esquema JSON para os seus argumentos. O agente lee a lista unha vez e chama unha ferramenta polo nome cando unha petición coincide con ela. «Transcribe este podcast e dime o que dixeron sobre os prezos» convértese en tres chamadas a ferramentas, e o agente nunca ve unha ruta HTTP.
Os servidores son de dous tipos. Un servidor local executa como subproceso do cliente e comunícase por stdio, que é como funcionan a maioría dos servidores de sistema de ficheiros e de bases de datos. Un servidor remoto está detrás dunha URL e fala Streamable HTTP, o transporte que substituíu ao anterior HTTP-plus-SSE (eventos enviados polo servidor) na revisión de marzo de 2025 da especificación. O cliente envía cada petición, e o servidor responde pola mesma conexión; calquera cousa que teña que dicir antes do resultado final envíase en fluxo antes del. Calquera cliente escrito segundo a especificación actual pode usar calquera dos dous tipos.
O servidor de VocalStack é do tipo remoto, en {{api}}/v1/mcp, e usalo custa o mesmo que custa a API. Só necesitas a URL.
Abre a área Developers do panel en {{app}}/developers. A primeira pestana, Connect an AI agent, mostra a URL do servidor e un fragmento de configuración para cada cliente. Os tres fragmentos de abaixo coinciden cos que aparecen alí.
Executa isto no teu terminal:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Engade isto a .cursor/mcp.json no teu proxecto, ou a ~/.cursor/mcp.json para todos os proxectos:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Calquera cliente que admita Streamable HTTP pode engadir o servidor con esta URL. Esta é a forma xenérica que mostra o panel:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Non necesitas unha clave de API para comezar. A primeira vez que o cliente se conecta, inicias sesión coa túa conta de VocalStack no navegador, e o cliente garda o token. O panel di en só unha liña: «Iniciarás sesión coa túa conta de VocalStack a primeira vez. Non fai falta ningunha clave.»
Isto é a especificación de autorización de MCP en acción, non un truco de VocalStack. Un servidor remoto responde a unha petición sen autenticar cun 401 que apunta aos seus metadatos de recurso protexido: un pequeno documento JSON que indica o servidor de autorización e os ámbitos que o servidor require. O cliente lee o documento, executa un fluxo OAuth 2.1 estándar no navegador e volve cun token emitido só para ese servidor. Calquera servidor MCP remoto que siga a especificación che dará acceso do mesmo xeito, polo que os clientes anteriores poden facelo sen saber nada de VocalStack.
Tamén funciona unha clave de API, para un cliente que se execute nun servidor ou nun script. Envíaa como Authorization: Bearer vs_key_..., a mesma cabeceira que acepta a API REST. As claves créanse en Developers → API keys. As dúas ferramentas de transcrición necesitan os permisos Write e Stream audio. O segundo parece estraño para un ficheiro, pero as ferramentas pasan polo mesmo punto de creación que todas as transcricións, incluídas as en directo, e ese punto comproba ambos. As ferramentas de lectura necesitan Read; list_voices só necesita unha credencial válida.
Unha vez que iniciaste sesión, o agente ve nove ferramentas. Raramente as nomearás ti mesmo, pero coñecelas explica o que fai o agente a seguir.
Cada ferramenta recibe e devolve JSON en camelCase, cos mesmos nomes de campo que os tipos de /v1; o identificador dunha transcrición é o seu transcriptionId.
transcribe_url inicia a transcrición de audio ou vídeo nunha URL pública: unha ligazón a un ficheiro, un episodio de podcast, un vídeo de YouTube. Non se aceptan as transmisións en directo. Argumentos opcionais: name, spokenLanguage (omítelo para detectar o idioma), speakerLabels (auto, on ou off) e startS/endS para transcribir só unha parte do audio.transcribe_file fai o mesmo para un ficheiro que o agente ten, enviado como fileBase64 co seu filename. O tamaño decodificado está limitado a 10 MiB, uns dez minutos de MP3 a 128 kbps; para algo máis grande, dálle ao agente unha ligazón.Ambas devolven de inmediato o transcriptionId, state: "queued" e unha pista next que indica a ferramenta de espera. As transcricións creadas polo agente comezan privadas, sen ligazón para compartir.
Un agente non pode aguantar unha transmisión en directo máis pacientemente do que o podes facer ti; seguiría chamando á ferramenta de espera ata que alguén lle quitase o portátil. Unha gravación rematada ten un final, e iso é o que espera o seguinte par de ferramentas.
Unha chamada a unha ferramenta é unha petición HTTP, e as peticións HTTP non están pensadas para durar unha hora. Os clientes renúnciano, os proxies pechan a conexión, e un modelo bloqueado nunha ferramenta non pode facer outra cousa. Por iso, o patrón para calquera traballo longo detrás de MCP é o mesmo que usa tamén a API REST: iniciar o traballo e obter un identificador, esperar por el durante un tempo limitado e volver a chamar se non está listo. O estado o leva o identificador, non a conexión.
wait_for_transcription bloquea ata que o traballo estea done ou failed, ou ata que pase timeoutS (por defecto 50 segundos, máximo 60, o que mantén a chamada por debaixo dos tempos límite da maioría de clientes e proxies). Se o resultado indica timedOut: true, o traballo segue en curso e o agente volve chamar á ferramenta. Mentres a ferramenta espera, o servidor envía notificacións de progreso de MCP se o cliente as pediu: unha porcentaxe e unha fase, como «obtendo 3.1 / 8.0 MB» ou «transcribindo 01:25 de 02:00».get_transcription devolve o estado e, cando está listo, o texto. format: "text" dá unha liña por segmento como [mm:ss] Speaker 1: ...; "segments" dá liñas con tempo con start, end, speaker e speakerName; includeWords: true engade os tempos das palabras. Os resultados están paxinados (offset, limit, por defecto 500 segmentos) cun nextOffset cando quedan máis.A paxinación está para o modelo, non para a rede. Todo o que devolve unha ferramenta pégase na xanela de contexto do agente, onde compite coa túa conversa e custa tokens en cada quenda posterior. Unha reunión de dúas horas son decenas de miles de palabras; devolvelas todas de golpe empurraría para fóra do contexto a pregunta que fixeches. As boas ferramentas MCP devolven unha páxina e un cursor, e deixan que o agente decida canto precisa.
Unha desconexión ou un tempo esgotado nunca cancela o traballo, porque o traballo vive no servidor, non na petición MCP. Cando remata, o traballo é unha entrada máis da túa biblioteca, e as seguintes ferramentas tratana como a calquera outra.
list_transcriptions lista as transcricións da conta, das máis recentes ás máis antigas, con estado e duración; lifecycle é active, archived ou all.search_transcriptions busca o que se dixo en todas as transcricións, en calquera idioma, e devolve as liñas coincidentes, cada unha coa súa transcrición e o segundo en que se dixo. transcriptionId limita a busca a unha transcrición; lang engade unha tradución de cada resultado.Atopar unha liña é a metade barata. Hai dúas ferramentas máis que averiguan o que dixo todo o conxunto.
get_summary devolve o título de IA e o resumo dunha transcrición rematada, opcionalmente traducidos con lang. state: "pending" significa que o resumo aínda se está escribindo (normalmente está listo en segundos despois de que remate o traballo), e o agente volve preguntar.translate_transcription devolve unha transcrición rematada noutro idioma, como texto ou segmentos con tempo, paxinada como get_transcription. As traduccións gárdanse, polo que volver preguntar non repite o traballo.list_voices lista as voces que poden ler unha transcrición nun idioma: identificador, nome, xénero e acento cando se coñecen, unha valoración de calidade, e se é a predeterminada ou unha das túas voces clonadas. Describe as voces; non fai que ningunha fale (máis abaixo, o que o servidor non fai).Así encadéanse as ferramentas na práctica.
Unha vez engadido o servidor, unha conversa en Claude Code faise así. Pegas a ligazón dun podcast e pides o resumo en francés.
O agente chama a transcribe_url:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Recibe un transcriptionId e state: "queued", e segue a pista next:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Un episodio de cincuenta minutos transcríbese moitas veces máis rápido do que se reproduce, pero non dentro dunha soa espera. A primeira espera devolve timedOut: true co progreso, por exemplo, nun 61 por cento, así que o agente chama á ferramenta outra vez e obtén state: "done".
Agora o agente chama a get_summary con lang: "fr":
{ "transcriptionId": "4f1c...", "lang": "fr" }
Se o resumo segue en pending, o agente agarda uns segundos; se non, entrégache un título e un resumo en francés. Pregunta «onde falaron dos prezos?» e chama a search_transcriptions con query: "pricing" e o mesmo transcriptionId, e cita as liñas coincidentes cos seus marcas de tempo. Pide o conxunto completo en francés e chama a translate_transcription.
Unhas poucas chamadas a ferramentas, sen código, e unha transcrición na túa biblioteca. Cada unha desas chamadas pasou polos mesmos controis que unha petición REST, e eses controis son os que fixan a factura e os límites.
O servidor MCP é a API por unha porta diferente: os mesmos límites, a mesma factura.
POST /v1/transcriptions: aplícanse o ritmo de creación do plan (10, 100 ou un número personalizado de transcricións iniciadas por hora), o seu límite de transcricións simultáneas (1, 5 ou sen límite) e o seu crédito. O crédito de $5 de alta cobre unha primeira sesión, sen necesidade de tarxeta.isError: true co código de erro da API REST, unha frase na que o modelo pode actuar, e os campos retryable e retryAfterS. insufficient_credit leva un topUpUrl; rate_limited indica canto hai que esperar. Isto importa máis do que parece: un modelo lee o texto do erro, así que unha frase na que pode actuar converte un calexón sen saída nun seguinte paso./v1/mcp: un agente en bucle recibe un HTTP 429 con Retry-After antes de que se execute ningunha ferramenta.idempotencyKey: reutilizar a clave dunha chamada completada repite o primeiro resultado, e reutilizala con argumentos diferentes recházase, así que un agente que reintenta por conta propia nunca inicia un segundo traballo. Calquera ferramenta que gaste diñeiro debería ofrecer isto; os agentes reintentan moito máis libremente que as persoas.Eses son os límites do que fai o servidor. Dúas cousas quedan fóra deles a propósito.
O servidor non ten ningunha ferramenta que converta texto arbitrario en fala, e non se prevé ningunha. VocalStack fala transcricións e as súas traduccións, cunha voz predefinida ou clonada, e nada máis. list_voices indica ao agente que voces poden ler unha transcrición nun idioma, non como facer que unha voz diga algo novo.
As ferramentas de transcrición tampouco aceptan transmisións en directo. Unha transmisión en directo de YouTube ou unha emisora de radio necesita unha transcrición en directo, iniciada desde o panel ou a través de POST /v1/transcriptions/live na referencia da API. Un vídeo de YouTube rematado é un ficheiro, e transcribe_url acéptao.
Se preferes escribir o código ti mesmo, transcribir un ficheiro coa API explica os mesmos pasos como chamadas HTTP, e o tutorial en tempo real trata o WebSocket.