VoiceBooker MCP-Server

Der VoiceBooker-MCP-Server (Model Context Protocol) ermöglicht kompatiblen KI-Clients, die VoiceBooker-Ressourcen des authentifizierten Unternehmens 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:

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": { "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

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:

Mit list_bots den Bot finden.
Mit list_stages und der Bot-ID alle Stages abrufen. Erst die Stages enthalten Prompts, Tools, Funktionen und das konkrete Verhalten.
Die vollständigen Stage-Daten lesen, bevor Änderungen vorgenommen werden.
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

Tool	Funktion
`list_bots`	Listet Bot-Container des authentifizierten Unternehmens. `include_deleted` kann unsichtbare Bots einschließen.
`create_bot`	Erstellt einen Bot-Container mit einer ersten `Welcome`-Stage. `name` ist erforderlich; `settings`, `initial_state`, `wizard` und `editable_keys` sind optional.
`update_bot`	Ändert Bot-Metadaten. `bot_id` ist erforderlich; das Stage-Verhalten wird nicht ersetzt.
`delete_bot`	Löscht einen Bot oder macht ihn unsichtbar. Bots mit Stages werden unsichtbar gemacht.

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

Stages

Tool	Funktion
`list_stages`	Listet alle geordneten Stages eines Bots. `bot_id` ist erforderlich; `include_deleted` schließt unsichtbare Stages ein.
`create_stage`	Erstellt eine Stage und hängt sie an einen Bot. `bot_id` und `name` sind erforderlich. Prompt, Tools, Funktionen, Settings und `stage_config` definieren das Verhalten.
`update_stage`	Ändert eine Stage und ihre botbezogene Konfiguration. `bot_id` und `stage_id` sind erforderlich; `instance_settings` ändert die Instanzwerte.
`delete_stage`	Entfernt eine Stage aus dem Flow. `bot_id` und `stage_id` sind erforderlich.

Im Textmodus ist prompt ein Liquid-/System-Prompt und tools ein JSON-kodiertes OpenAI-Tool-Array. Im JavaScript-Modus setzen settings.promptExec und/oder settings.toolsExec den jeweiligen JavaScript-Modus voraus. JSON-Tools und JavaScript-Code dürfen nicht gemischt werden. Tool-Funktionen müssen strukturierte Objekte wie { data, text, state, stack } zurückgeben, niemals nur einen String oder null.

SIP-Konten

Tool	Funktion
`list_sip_accounts`	Listet SIP-Konten für Registrierung, Routing, Webhooks und Weiterleitungen. `include_inactive` ist standardmäßig `true`.
`create_sip_account`	Speichert ein editierbares SIP-Konto und stößt eine Connector-Registrierung an. Es wird keine Telefonnummer gekauft oder provisioniert.
`update_sip_account`	Aktualisiert ein Konto und erhält nicht angegebene Felder. `id` ist erforderlich; Settings werden zusammengeführt.
`delete_sip_account`	Löscht editierbare Konten. Systemverwaltete Konten werden stattdessen mit `register: false` abgemeldet.

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

Tool	Funktion
`list_call_history`	Findet Telefon- und Chat-Sessions. Alle Argumente sind optional; verfügbar sind unter anderem `bot_id`, ISO-8601 `start`/`end_date`, `call`, `limit` und `offset`. Ohne Argumente werden alle Bots durchsucht.
`get_trace_conversation`	Liefert Gesprächszeilen und Trace-Ereignisse einer Session. `call_session_id` ist erforderlich; `limit` ist auf 1000 begrenzt.

Gespräche mit aktivierter Datenaufbewahrungs-Sperre werden ausgeschlossen; konfigurierte Webhook-Maskierungen werden angewendet. Transkripte, Telefonnummern und Funktionsdaten sind vertrauliche Geschäftsdaten.

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.

VoiceBooker MCP-Server

Auf dieser Seite