Ein MCP-Server macht aus einer API einige benannte Tools, die ein Agent mitten in einem Gespräch aufruft. Ein langer Auftrag passt dahinter, wenn das Tool ein Handle zurückgibt, auf das der Agent in begrenzten Abschnitten wartet. Fügen Sie einen Podcast-Link ein, bitten Sie um die Kernaussagen auf Französisch, und es muss kein Code geschrieben werden.
Ein Coding-Agent kann die VocalStack-API wie jedes andere Programm nutzen: Er liest die API-Referenz, schreibt ein paar Zeilen gegen das SDK und führt sie aus. Das ist der richtige Weg für alles, was ohne den Agenten läuft.
MCP (das Model Context Protocol) ist für den anderen Fall gedacht: Sie sprechen mit einem Assistenten und wollen, dass er etwas jetzt transkribiert, ohne Code. Ein MCP-Server veröffentlicht eine kurze Liste benannter Tools, jedes mit einer Beschreibung und einem JSON-Schema für seine Argumente. Der Agent liest die Liste einmal und ruft ein Tool beim Namen auf, sobald eine Anfrage dazu passt. „Transkribiere diesen Podcast und sag mir, was sie über Preise gesagt haben“ wird zu drei Tool-Aufrufen, und der Agent sieht nie eine HTTP-Route.
Es gibt zwei Arten von Servern. Ein lokaler Server läuft als Unterprozess des Clients und kommuniziert über stdio; so arbeiten die meisten Datei- und Datenbankserver. Ein entfernter Server sitzt hinter einer URL und spricht Streamable HTTP, das Transportverfahren, das in der Spezifikation vom März 2025 das ältere HTTP-plus-SSE-Verfahren (Server-Sent Events) abgelöst hat. Der Client sendet jede Anfrage, und der Server antwortet über dieselbe Verbindung; alles, was er vor dem endgültigen Ergebnis mitteilen muss, wird vorab gestreamt. Jeder Client, der gegen die aktuelle Spezifikation geschrieben wurde, kann beide Arten nutzen.
Der Server von VocalStack ist die entfernte Variante unter {{api}}/v1/mcp, und seine Nutzung kostet das Gleiche wie die API. Sie brauchen nur die URL.
Öffnen Sie den Entwicklerbereich im Dashboard unter {{app}}/developers. Der erste Tab, Connect an AI agent, zeigt die Server-URL und einen Einrichtungsschnipsel für jeden Client. Die drei Schnipsel unten entsprechen denen dort.
Führen Sie dies in Ihrem Terminal aus:
claude mcp add --transport http vocalstack {{api}}/v1/mcp
Fügen Sie dies in .cursor/mcp.json in Ihrem Projekt oder in ~/.cursor/mcp.json für alle Projekte hinzu:
{"mcpServers":{"vocalstack":{"url":"{{api}}/v1/mcp"}}}
Jeder Client, der Streamable HTTP unterstützt, kann den Server mit dieser URL hinzufügen. Dies ist die generische Form, die das Dashboard anzeigt:
{
"vocalstack": {
"type": "streamable-http",
"url": "{{api}}/v1/mcp"
}
}
Um loszulegen, brauchen Sie keinen API-Schlüssel. Beim ersten Verbindungsaufbau des Clients melden Sie sich im Browser mit Ihrem VocalStack-Konto an, und der Client behält das Token. Das Dashboard fasst es in einem Satz zusammen: „You'll sign in with your VocalStack account the first time. No key needed.“
Das ist die Autorisierungsspezifikation von MCP in Aktion und kein Sonderweg von VocalStack. Ein entfernter Server beantwortet eine nicht authentifizierte Anfrage mit einem 401, das auf seine Metadaten für geschützte Ressourcen verweist: ein kleines JSON-Dokument, das den Autorisierungsserver und die Scopes nennt, die der Server verlangt. Der Client liest es, führt im Browser einen standardisierten OAuth-2.1-Ablauf aus und kommt mit einem Token zurück, das nur für diesen Server ausgestellt ist. Jeder entfernte MCP-Server, der die Spezifikation befolgt, meldet Sie auf die gleiche Weise an; deshalb können die Clients oben das tun, ohne etwas über VocalStack zu wissen.
Ein API-Schlüssel funktioniert ebenfalls, für einen Client, der auf einem Server oder in einem Skript läuft. Senden Sie ihn als Authorization: Bearer vs_key_..., denselben Header, den die REST-API erwartet. Schlüssel erstellen Sie unter Developers → API keys. Die beiden Transkriptions-Tools benötigen die Berechtigungen Write und Stream audio. Die zweite wirkt bei einer Datei merkwürdig, aber die Tools laufen über denselben Erstellungspunkt wie jede Transkription, auch Live-Transkriptionen, und dieser Punkt prüft beide. Die Lese-Tools benötigen Read; list_voices benötigt nur eine gültige Anmeldung.
Sobald Sie angemeldet sind, sieht der Agent neun Tools. Sie werden sie selten selbst nennen, aber wer sie kennt, versteht, was der Agent als Nächstes tut.
Jedes Tool nimmt camelCase-JSON entgegen und gibt es zurück, mit denselben Feldnamen wie die Datentypen der /v1-Schnittstelle; das Handle einer Transkription ist ihre transcriptionId.
transcribe_url startet die Transkription von Audio oder Video unter einer öffentlichen URL: ein Dateilink, eine Podcast-Folge, ein YouTube-Video. Live-Streams werden nicht akzeptiert. Optionale Argumente: name, spokenLanguage (weglassen, um die Sprache zu erkennen), speakerLabels (auto, on oder off) und startS/endS, um nur einen Teil des Audios zu transkribieren.transcribe_file tut dasselbe für eine Datei, die der Agent besitzt, gesendet als fileBase64 mit ihrem filename. Die dekodierte Größe ist auf 10 MiB begrenzt, ungefähr zehn Minuten MP3 mit 128 kbps; für alles Größere geben Sie dem Agenten einen Link.Beide liefern sofort die transcriptionId, state: "queued" und einen next-Hinweis, der das Abfrage-Tool nennt. Vom Agenten erstellte Transkriptionen beginnen privat, ohne Freigabelink.
Ein Agent kann eine Live-Übertragung nicht geduldiger aussitzen als Sie; er würde das Abfrage-Tool so lange aufrufen, bis jemand ihm den Laptop wegnimmt. Eine fertige Aufnahme hat ein Ende, und darauf wartet das nächste Paar von Tools.
Ein Tool-Aufruf ist eine HTTP-Anfrage, und HTTP-Anfragen sind nicht dafür gedacht, eine Stunde zu dauern. Clients brechen sie ab, Proxys schließen sie, und ein Modell, das auf ein Tool wartet, kann nichts anderes tun. Deshalb folgt das Muster für jeden langen Auftrag hinter MCP demselben Schema wie bei der REST-API: den Auftrag starten und ein Handle erhalten, dann für eine begrenzte Zeit darauf warten und erneut aufrufen, falls er nicht fertig ist. Der Zustand steckt im Handle, nicht in der Verbindung.
wait_for_transcription blockiert, bis der Auftrag done oder failed ist oder bis timeoutS abläuft (Standard 50 Sekunden, Maximum 60, was den Aufruf unter den Timeouts hält, die die meisten Clients und Proxys anwenden). Lautet das Ergebnis timedOut: true, läuft der Auftrag noch, und der Agent ruft das Tool erneut auf. Während das Tool wartet, sendet der Server MCP-Fortschrittsbenachrichtigungen, sofern der Client sie angefordert hat: einen Prozentwert und eine Phase wie „fetching 3.1 / 8.0 MB“ oder „transcribing 01:25 of 02:00“.get_transcription liefert den Status und, sobald fertig, den Text. format: "text" gibt eine Zeile pro Segment aus, als [mm:ss] Speaker 1: ...; "segments" liefert zeitgestempelte Zeilen mit start, end, speaker und speakerName; includeWords: true fügt Wortzeiten hinzu. Ergebnisse werden seitenweise ausgegeben (offset, limit, Standard 500 Segmente), mit einem nextOffset, wenn noch mehr folgt.Die Paginierung ist für das Modell gedacht, nicht für das Netzwerk. Alles, was ein Tool zurückgibt, wird in das Kontextfenster des Agenten eingefügt, wo es mit Ihrem Gespräch konkurriert und bei jeder späteren Runde Tokens kostet. Eine zweistündige Besprechung umfasst Zehntausende Wörter; würde man alles auf einmal zurückgeben, würde die Frage, die Sie gestellt haben, aus dem Kontext gedrängt. Gute MCP-Tools geben eine Seite und einen Cursor zurück und überlassen es dem Agenten zu entscheiden, wie viel er braucht.
Ein Verbindungsabbruch oder ein Timeout bricht den Auftrag nie ab, denn der Auftrag lebt auf dem Server, nicht in der MCP-Anfrage. Ist er fertig, ist er ein weiterer Eintrag in Ihrer Bibliothek, und die nächsten Tools behandeln ihn wie jeden anderen.
list_transcriptions listet die Transkriptionen des Kontos, neueste zuerst, mit Status und Dauer; lifecycle ist active, archived oder all.search_transcriptions durchsucht, was über alle Transkriptionen hinweg gesagt wurde, in jeder Sprache, und gibt die passenden Zeilen zurück, jeweils mit ihrer Transkription und der Sekunde, in der sie gesprochen wurde. transcriptionId grenzt die Suche auf eine Transkription ein; lang fügt jeder Fundstelle eine Übersetzung hinzu.Eine Zeile zu finden ist der einfache Teil. Zwei weitere Tools finden heraus, was das Ganze insgesamt besagt.
get_summary liefert den KI-Titel und die Zusammenfassung einer fertigen Transkription, optional mit lang übersetzt. state: "pending" bedeutet, dass die Zusammenfassung noch geschrieben wird (sie ist meist innerhalb von Sekunden nach Abschluss des Auftrags fertig), und der Agent fragt erneut nach.translate_transcription liefert ein fertiges Transkript in einer anderen Sprache, als Text oder zeitgestempelte Segmente, seitenweise wie get_transcription. Übersetzungen werden gespeichert, daher wiederholt eine erneute Anfrage die Arbeit nicht.list_voices listet die Stimmen auf, die ein Transkript in einer Sprache vorlesen können: ID, Name, Geschlecht und Akzent, wenn bekannt, eine Qualitätsbewertung und ob es die Standardstimme oder eine Ihrer geklonten Stimmen ist. Es beschreibt Stimmen; es lässt keine sprechen (dazu unten mehr, was der Server nicht tut).So greifen die Tools in der Praxis ineinander.
Sobald der Server hinzugefügt ist, verläuft ein Gespräch in Claude Code so: Sie fügen einen Podcast-Link ein und bitten um die Kernaussagen auf Französisch.
Der Agent ruft transcribe_url auf:
{ "url": "https://example.org/episodes/42.mp3", "name": "Episode 42", "speakerLabels": "auto" }
Er erhält eine transcriptionId und state: "queued" zurück und folgt dem next-Hinweis:
{ "transcriptionId": "4f1c...", "timeoutS": 50 }
Eine fünfzigminütige Folge wird vielfach schneller transkribiert, als sie abläuft, aber nicht innerhalb eines einzigen Wartevorgangs. Die erste Wartezeit liefert timedOut: true mit einem Fortschritt von, sagen wir, 61 Prozent; der Agent ruft das Tool noch einmal auf und erhält state: "done".
Nun ruft der Agent get_summary mit lang: "fr" auf:
{ "transcriptionId": "4f1c...", "lang": "fr" }
Ist die Zusammenfassung noch pending, wartet der Agent einige Sekunden; andernfalls liefert er Ihnen Titel und Zusammenfassung auf Französisch. Fragen Sie „Wo haben sie über Preise gesprochen?“, ruft er search_transcriptions mit query: "pricing" und derselben transcriptionId auf und zitiert die passenden Zeilen mit ihren Zeitmarken. Bitten Sie um das Ganze auf Französisch, ruft er translate_transcription auf.
Einige Tool-Aufrufe, kein Code, und eine Transkription in Ihrer Bibliothek. Jeder dieser Aufrufe lief durch dieselben Kontrollen wie eine REST-Anfrage, und genau diese Kontrollen bestimmen die Abrechnung und die Limits.
Der MCP-Server ist die API durch eine andere Tür: gleiche Limits, gleiche Abrechnung.
POST /v1/transcriptions: Es gelten die Erstellungsrate des Tarifs (10, 100 oder eine individuelle Anzahl gestarteter Transkriptionen pro Stunde), seine Obergrenze gleichzeitiger Transkriptionen (1, 5 oder unbegrenzt) und sein Guthaben. Das Anmelde-Guthaben von $5 deckt eine erste Sitzung ab, ohne Karte.isError: true mit dem Fehlercode der REST-API, einem Satz, mit dem das Modell etwas anfangen kann, und den Feldern retryable und retryAfterS. insufficient_credit enthält eine topUpUrl; rate_limited gibt an, wie lange zu warten ist. Das wiegt schwerer, als es klingt: Ein Modell liest den Fehlertext, daher macht ein Satz, mit dem es etwas anfangen kann, aus einer Sackgasse den nächsten Tool-Aufruf./v1/mcp-Anfrage selbst: Ein schleifender Agent erhält eine HTTP-429 mit Retry-After, bevor ein Tool läuft.idempotencyKey entgegen: Wird der Schlüssel eines abgeschlossenen Aufrufs erneut verwendet, wird das erste Ergebnis wiedergegeben; wird er mit anderen Argumenten verwendet, wird das abgelehnt. So startet ein Agent, der selbstständig wiederholt, nie einen zweiten Auftrag. Jedes Tool, das Geld ausgibt, sollte dies anbieten; Agenten wiederholen weit freier als Menschen.Das sind die Grenzen dessen, was der Server tut. Zwei Dinge liegen absichtlich außerhalb davon.
Der Server hat kein Tool, das beliebigen Text in Sprache umwandelt, und ein solches ist auch nicht geplant. VocalStack spricht Transkripte und deren Übersetzungen, mit einer Standard- oder geklonten Stimme, und sonst nichts. list_voices sagt einem Agenten, welche Stimmen ein Transkript in einer Sprache vorlesen können, nicht, wie man eine Stimme dazu bringt, etwas Neues zu sagen.
Die Transkriptions-Tools lehnen außerdem Live-Streams ab. Ein YouTube-Livestream oder ein Radiostream benötigt eine Live-Transkription, die im Dashboard oder über POST /v1/transcriptions/live in der API-Referenz gestartet wird. Ein beendetes YouTube-Video ist eine Datei, und transcribe_url nimmt sie an.
Wenn Sie den Code lieber selbst schreiben möchten, zeigt eine Datei mit der API transkribieren dieselben Schritte als HTTP-Aufrufe, und das Echtzeit-Tutorial behandelt den WebSocket.