Server MCP di VoiceBooker

Il server MCP (Model Context Protocol) di VoiceBooker consente a un client AI compatibile di gestire le risorse VoiceBooker dell’azienda autenticata. Puoi ispezionare e modificare bot e stage, configurare account SIP e analizzare la cronologia delle chiamate senza creare un’integrazione REST separata.

Collegare il server

Il server utilizza MCP Streamable HTTP ed è disponibile all’indirizzo:

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

Ogni richiesta deve includere un token API VoiceBooker nell’header Token:

Token: <il-tuo-token-api>

Il token determina il contesto aziendale; le risorse di altre aziende non possono essere lette o modificate. Condividi il token solo con il client MCP necessario e non inserirlo in configurazioni condivise.

Esempio di configurazione JSON:

{
  "mcpServers": {
    "voicebooker": {
      "url": "https://voicebooker.de/app/api/v1/mcp",
      "headers": { "Token": "<il-tuo-token-api>" }
    }
  }
}

A seconda del client, il campo può chiamarsi headers, httpHeaders oppure essere fornito tramite una variabile d’ambiente. Ricollega il client dopo aver salvato la configurazione per consentire la scoperta automatica degli strumenti.

Utilizzo

Il server restituisce gli ID delle risorse. Riutilizzali esattamente come vengono restituiti. Per ispezionare un bot, usa list_bots, poi list_stages con il suo ID: gli stage contengono prompt, strumenti, funzioni e comportamento effettivo. Leggi tutti gli stage prima di modificare il bot.

Per analizzare una conversazione, usa prima list_call_history, quindi get_trace_conversation con l’ID della sessione restituito. Il trace include turni, stato, stack e chiamate a funzioni o webhook.

Strumenti disponibili

Bot e stage

Strumento	Funzione
`list_bots`	Elenca i contenitori bot. `include_deleted` include i bot nascosti.
`create_bot`	Crea un contenitore con uno stage `Welcome`. `name` è obbligatorio; `settings`, `initial_state`, `wizard` ed `editable_keys` sono opzionali.
`update_bot`	Modifica i metadati senza sostituire il comportamento degli stage. `bot_id` è obbligatorio.
`delete_bot`	Elimina o nasconde un bot; i bot con stage vengono nascosti.
`list_stages`	Elenca tutti gli stage ordinati di un bot. `bot_id` è obbligatorio.
`create_stage`	Crea uno stage collegato a un bot. `bot_id` e `name` sono obbligatori.
`update_stage`	Modifica uno stage e la sua configurazione per bot. `bot_id` e `stage_id` sono obbligatori.
`delete_stage`	Rimuove uno stage dal flusso. `bot_id` e `stage_id` sono obbligatori.

In modalità testo, prompt è un prompt Liquid/sistema e tools è un array JSON di strumenti compatibile con OpenAI. In modalità JavaScript, attiva settings.promptExec o settings.toolsExec per il campo corrispondente. Non mischiare i due formati; le funzioni devono restituire oggetti strutturati, mai una stringa semplice o null.

Usa wizard per assistenti semplici a singolo stage. Per flussi esperti o multi-stage, crea o modifica gli stage separatamente.

Account SIP

Strumento	Funzione
`list_sip_accounts`	Elenca gli account per registrazione, routing, webhook e trasferimenti. `include_inactive` è `true` per impostazione predefinita.
`create_sip_account`	Salva un account SIP modificabile e aggiorna la registrazione del connector; non acquista né configura un numero.
`update_sip_account`	Aggiorna un account conservando i campi non forniti; `id` è obbligatorio e le impostazioni vengono unite.
`delete_sip_account`	Elimina gli account modificabili. Gli account gestiti dal sistema vengono invece deregistrati con `register: false`.

Le password SIP sono solo scrivibili e non vengono mai restituite. Se una password viene omessa durante un aggiornamento, quella esistente viene conservata; una stringa vuota la cancella.

Cronologia e trace

Strumento	Funzione
`list_call_history`	Cerca sessioni telefoniche e chat. Tutti i parametri sono opzionali: `bot_id`, `start`, `end_date`, `call`, `limit` e `offset`. Senza parametri cerca tutti i bot.
`get_trace_conversation`	Restituisce turni ed eventi trace di una sessione. `call_session_id` è obbligatorio; `limit` è massimo 1000.

Le conversazioni soggette a conservazione dei dati vengono escluse e vengono applicate le mascherature webhook configurate. Considera trascrizioni, numeri e dati delle funzioni informazioni aziendali riservate.