VoiceBooker MCP-Server

Der VoiceBooker-MCP-Server (Model Context Protocol) ermöglicht kompatiblen KI-Clients, die VoiceBooker-Ressourcen des authentifizierten Benutzers zu verwalten. Bots und Stages können geprüft und geändert, SIP-Konten konfiguriert und Anrufverläufe untersucht werden – ohne eine eigene REST-Integration zu bauen.

Verbindung herstellen

Der Server ist unter folgender URL als MCP Streamable HTTP verfügbar:

https://voicebooker.de/app/api/v1/mcp

Jede Anfrage benötigt ein VoiceBooker-API-Token im Header:

X-API-TOKEN: <Ihr-API-Token>

API-Tokens werden in VoiceBooker erstellt oder verwaltet. Teilen Sie das Token nur mit dem benötigten MCP-Client und speichern Sie es nicht in einer gemeinsam genutzten Konfigurationsdatei. Das Token bestimmt den Unternehmenskontext; Ressourcen anderer Unternehmen können weder gelesen noch geändert werden.

Ein JSON-basierter MCP-Client kann beispielsweise so konfiguriert werden:

{
  "mcpServers": {
    "voicebooker": {
      "url": "https://voicebooker.de/app/api/v1/mcp",
      "headers": { "X-API-TOKEN": "<Ihr-API-Token>" }
    }
  }
}

Je nach Client heißen die Felder möglicherweise headers, httpHeaders oder werden über Umgebungsvariablen gesetzt. Verbinden Sie den Client nach dem Speichern neu und lassen Sie die verfügbaren VoiceBooker-Tools auflisten.

Verwendung

Ressourcen-ID-Felder verwenden in MCP-Schemas und Antworten camelCase: botId, stageId, botStageId, sharedBotId und callSessionId. Der Server liefert IDs für seine Ressourcen. Verwenden Sie diese IDs bei weiteren Aufrufen genau so, wie sie zurückgegeben wurden. Für eine Bot-Inspektion:

1. Mit list_bots den Bot finden.
2. Mit list_stages und der Bot-ID alle Stages abrufen. Erst die Stages enthalten Prompts, Tools, Funktionen und das konkrete Verhalten.
3. Die vollständigen Stage-Daten lesen, bevor Änderungen vorgenommen werden.
4. Das passende Create-, Update- oder Delete-Tool verwenden und die Antwort prüfen.

Für die Fehlersuche rufen Sie zuerst list_call_history und anschließend get_trace_conversation mit der zurückgegebenen Call-Session-ID auf. Der Trace enthält Gesprächszeilen, State, Stack sowie Funktions- und Webhook-Aufrufe.

Verfügbare Tools

Bots

wizard eignet sich für einfache Single-Stage-Assistenten. Für Expert- oder Multi-Stage-Flows die Stages separat erstellen oder ändern.

Bot-Snapshots

Snapshots sind versionierte, unternehmensbezogene Kopien der vollständigen Bot-Definition. Vor einer Wiederherstellung wird automatisch ein Backup des aktuellen Bots erstellt.

Bot-Tests

Bot-Test-Tools verwalten Testkonfigurationen für zwei verschiedene Bots im authentifizierten Unternehmen. Der Quell-Bot ist die anrufende Seite, der Ziel-Bot die antwortende Seite. Die Antworten verwenden die öffentliche API-Struktur mit srcBotId und destBotId.

settings kann convInitBot, maxConvTurns, asCall, startTimeout und stateUpdate enthalten. Beide Bots müssen sichtbar sein und zum authentifizierten Unternehmen gehören; Quell- und Ziel-Bot müssen verschieden sein.

Stages

prompt und tools haben jeweils einen eigenen Ausführungsmodus. Die Flags settings.promptExec und settings.toolsExec sind unabhängig voneinander und müssen nur für das jeweilige Feld gesetzt werden:

• Wenn promptExec fehlt oder false ist, wird prompt als Liquid-Text verarbeitet und als System-Nachricht an das LLM übergeben. Wenn promptExec: true gesetzt ist, muss prompt JavaScript mit prompt(params) enthalten. Diese Funktion muss ein Objekt zurückgeben: { prompt: "..." } erzeugt eine System-Nachricht, die das LLM für die nächste Antwort verwendet; { text: "..." } erzeugt eine direkte Assistant-Nachricht, die unverändert zurückgegeben wird. Gibt die Funktion beide Felder zurück, wird nur prompt verwendet.
• Wenn toolsExec fehlt oder false ist, muss tools – sofern es nicht leer ist – ein JSON-kodierter String sein, der zu einem Array von OpenAI-kompatiblen Function-Tools decodiert werden kann. Jedes lokale Tool benötigt außerdem einen gleichnamigen Handler in functions; ein Eintrag in functions allein wird niemals automatisch ausgeführt. Wenn toolsExec: true gesetzt ist, muss tools stattdessen JavaScript mit tools(params) enthalten. Die Funktion muss { tools: [...] } zurückgeben; ein direkt zurückgegebenes Array ist ungültig. Dynamisch erzeugte lokale Tools benötigen ebenfalls gleichnamige Handler in functions.
• Die beiden Felder dürfen unterschiedliche Modi verwenden. Beispielsweise sind ein JavaScript-prompt mit statischen JSON-Tools oder ein Liquid-prompt mit dynamisch erzeugten JavaScript-Tools zulässig. Nicht zulässig ist nur das Vermischen der Formate innerhalb desselben Feldes: prompt darf nicht gleichzeitig Liquid-Text und eine JavaScript-Funktion enthalten, und tools darf nicht gleichzeitig ein JSON-Array-String und JavaScript-Code sein.

Ein Tool-Handler muss ein strukturiertes Objekt zurückgeben. data wird als Tool-Ergebnis an das LLM übergeben, damit es daraus die nächste Assistant-Antwort formuliert. text wird dagegen direkt und unverändert als Assistant-Nachricht zurückgegeben. Wenn ein Handler beide Felder liefert, hat data Vorrang; text wird dann nicht direkt ausgegeben. Die Handler in functions werden erst ausgeführt, wenn das LLM das jeweilige Tool aufruft.

list_stages liefert außerdem botEngine: lightweight steht für synchrones JavaScript mit api() und webhook(), extendedNodeJs für Promise-basiertes JavaScript mit fetch. Ein nicht-null settings.packageJson aktiviert extendedNodeJs; ein fehlender oder null-Wert aktiviert lightweight. Verwenden Sie im Lightweight-Modus nicht async, await, fetch, Promise, import oder require.

Stage-Namen sind exakt und groß-/kleinschreibungssensitiv. settings.initialStages legt den anfänglichen Stack fest. Prompt-Code kann den Stage wechseln, indem er den aktualisierten Stack zurückgibt:

function prompt(params) {
  params.stack.push("Booking");
  return { state: params.state, stack: params.stack, prompt: "Frage nach dem Buchungsdatum." };
}

Ein Tool kann mit transitionTo: "Booking" wechseln; dropStage: true entfernt den aktuellen Stage vor dem Handler. Dynamische Tools verwenden function tools(params) { return { tools: [...] }; }; jedes lokale Tool benötigt einen gleichnamigen Handler in functions. toolsState/toolsStack gelten für tools(params), state/stack in der Tooldefinition für den Handler.

SIP-Konten

SIP-Passwörter sind nur schreibbar und werden niemals zurückgegeben. Beim Update erhält das Weglassen eines Passworts das bestehende Passwort; ein leerer String löscht es.

Anrufverläufe und Traces

get_trace_conversation enthält Webhook-Aufrufe nur zusammengefasst als fsCalls. Für vollständige Ereignisdaten verwenden Sie list_call_webhook_events. Gespräche mit aktivierter Datenaufbewahrungs-Sperre werden ausgeschlossen; konfigurierte Filter für verborgene APIs werden angewendet.

Wichtige Hinweise

• Lesen Sie vor dem Ändern eines Bots immer seine vollständigen Stages.
• Behalten Sie beim Ändern einer Stage den Text-/JavaScript-Modus bei.
• Beachten Sie, dass das Löschen von Bots oder Stages aktive Gesprächsabläufe verändern kann.
• Beachten Sie, dass das Erstellen eines SIP-Kontos die Konfiguration speichert und die Connector-Registrierung auslösen kann, aber keine DID provisioniert.