Serveur MCP VoiceBooker

Le serveur MCP (Model Context Protocol) de VoiceBooker permet à un client IA compatible de gérer les ressources VoiceBooker de l’entreprise authentifiée. Il permet d’inspecter et de modifier les bots et les stages, de configurer les comptes SIP et d’analyser l’historique des appels sans développer une intégration REST séparée.

Connexion du serveur

Le serveur utilise MCP Streamable HTTP et est disponible à l’adresse suivante :

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

Chaque requête doit contenir un token API VoiceBooker dans l’en-tête Token :

Token: <votre-token-api>

Le token détermine le contexte de l’entreprise. Les ressources d’une autre entreprise ne peuvent pas être lues ou modifiées. Ne partagez le token qu’avec le client MCP concerné et ne l’enregistrez pas dans une configuration partagée.

Exemple de configuration JSON :

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

Selon le client, le champ peut s’appeler headers, httpHeaders ou être défini par une variable d’environnement. Reconnectez le client après l’enregistrement de la configuration afin qu’il découvre les outils.

Utilisation

Le serveur renvoie des IDs pour ses ressources. Réutilisez-les exactement comme ils sont renvoyés. Pour inspecter un bot : appelez list_bots, puis list_stages avec son ID. Les stages contiennent les prompts, les outils, les fonctions et le comportement réel du bot. Lisez tous les stages avant toute modification.

Pour analyser une conversation, appelez d’abord list_call_history, puis get_trace_conversation avec l’ID de session retourné. Le trace contient les tours de conversation, l’état, la pile et les appels de fonctions ou de webhooks.

Outils disponibles

Bots et stages

Outil	Fonction
`list_bots`	Liste les conteneurs de bots. `include_deleted` inclut les bots masqués.
`create_bot`	Crée un conteneur avec un stage `Welcome`. `name` est obligatoire; `settings`, `initial_state`, `wizard` et `editable_keys` sont facultatifs.
`update_bot`	Modifie les métadonnées du bot sans remplacer son comportement de stage. `bot_id` est obligatoire.
`delete_bot`	Supprime ou masque un bot; les bots possédant des stages sont masqués.
`list_stages`	Liste tous les stages ordonnés d’un bot. `bot_id` est obligatoire.
`create_stage`	Crée un stage rattaché à un bot. `bot_id` et `name` sont obligatoires.
`update_stage`	Modifie un stage et ses paramètres d’instance. `bot_id` et `stage_id` sont obligatoires.
`delete_stage`	Retire un stage du flux du bot. `bot_id` et `stage_id` sont obligatoires.

En mode texte, prompt est un prompt Liquid/système et tools est un tableau JSON de fonctions compatible OpenAI. En mode JavaScript, activez settings.promptExec ou settings.toolsExec pour le champ correspondant. Ne mélangez pas les deux formats; les fonctions doivent renvoyer des objets structurés, jamais une chaîne seule ou null.

Utilisez wizard pour un assistant simple à un seul stage. Pour un flux expert ou multi-stage, créez ou modifiez les stages séparément.

Comptes SIP

Outil	Fonction
`list_sip_accounts`	Liste les comptes utilisés pour l’enregistrement, le routage, les webhooks et les transferts. `include_inactive` vaut `true` par défaut.
`create_sip_account`	Enregistre un compte SIP modifiable et déclenche une mise à jour du connecteur; il ne provisionne pas de numéro.
`update_sip_account`	Modifie un compte en conservant les champs non fournis; `id` est obligatoire et les paramètres sont fusionnés.
`delete_sip_account`	Supprime les comptes modifiables. Les comptes gérés par le système sont désenregistrés avec `register: false`.

Les mots de passe SIP sont en écriture seule et ne sont jamais renvoyés. Un mot de passe omis est conservé lors d’une mise à jour; une chaîne vide l’efface.

Historique et traces

Outil	Fonction
`list_call_history`	Recherche les sessions téléphoniques et de chat. Tous les paramètres sont facultatifs : `bot_id`, `start`, `end_date`, `call`, `limit` et `offset`. Sans paramètre, tous les bots sont recherchés.
`get_trace_conversation`	Renvoie les tours de conversation et les événements de trace d’une session. `call_session_id` est obligatoire et `limit` est plafonné à 1000.

Les conversations soumises à une restriction de conservation sont exclues et les masquages de webhooks configurés sont appliqués. Traitez les transcriptions, numéros et données de fonctions comme des données confidentielles.