Serveur MCP VoiceBooker

Le serveur MCP (Model Context Protocol) de VoiceBooker permet à un client IA compatible de gérer les ressources VoiceBooker de l’utilisateur authentifié. 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 X-API-TOKEN :

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

Les champs d’ID de ressources utilisent camelCase dans les schémas et les réponses MCP : botId, stageId, botStageId, sharedBotId et callSessionId. 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

prompt et tools ont chacun leur propre mode d’exécution. Les options settings.promptExec et settings.toolsExec sont indépendantes et ne s’appliquent qu’au champ correspondant :

• Si promptExec est absent ou vaut false, prompt est traité comme un texte Liquid et envoyé au LLM comme message système. Avec promptExec: true, prompt doit contenir du JavaScript définissant prompt(params). La fonction doit renvoyer un objet : { prompt: "..." } crée un message système utilisé par le LLM pour sa réponse suivante, tandis que { text: "..." } crée un message assistant direct renvoyé sans modification. Si les deux champs sont renvoyés, seul prompt est utilisé.
• Si toolsExec est absent ou vaut false, une valeur tools non vide doit être une chaîne JSON décodable en tableau de fonctions compatible OpenAI. Chaque outil local doit aussi avoir un handler du même nom dans functions; une fonction placée seule dans functions n’est jamais exécutée automatiquement. Avec toolsExec: true, tools doit contenir du JavaScript définissant tools(params), qui doit renvoyer { tools: [...] }; renvoyer directement le tableau est invalide. Les outils générés dynamiquement nécessitent également des handlers du même nom dans functions.
• Les deux champs peuvent utiliser des modes différents. Par exemple, un prompt JavaScript avec des outils JSON statiques, ou un prompt Liquid avec des outils JavaScript générés dynamiquement, sont valides. Seul le mélange des formats dans un même champ est interdit : prompt ne peut pas contenir à la fois du texte Liquid et une fonction JavaScript, et tools ne peut pas contenir à la fois une chaîne JSON et du code JavaScript.

Pour un handler d’outil, data est envoyé au LLM comme résultat de l’outil afin qu’il formule la réponse suivante. text est au contraire renvoyé directement comme réponse assistant inchangée. Si les deux sont renvoyés, data est prioritaire; text n’est pas envoyé directement.

list_stages renvoie également botEngine : lightweight utilise du JavaScript synchrone avec api() et webhook, tandis que extendedNodeJs utilise du JavaScript basé sur les Promises et permet fetch. Un settings.packageJson non nul active extendedNodeJs; une valeur absente ou nulle active lightweight. N’utilisez pas async, await, fetch, Promise, import ou require avec le moteur léger.

Les noms de stages sont sensibles à la casse. settings.initialStages définit la pile initiale. Le code du prompt peut changer de stage en renvoyant la pile mise à jour :

function prompt(params) {
  params.stack.push("Booking");
  return { state: params.state, stack: params.stack, prompt: "Demandez la date de réservation." };
}

Un outil peut changer de stage avec transitionTo: "Booking"; dropStage: true retire le stage actuel avant l’exécution du handler. Les outils dynamiques utilisent function tools(params) { return { tools: [...] }; } et chaque outil local nécessite un handler du même nom dans functions. toolsState/toolsStack concernent tools(params); state/stack concernent son handler.

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.

Tests de bots

Les outils de test de bots gèrent des configurations pour deux bots différents de l’entreprise authentifiée. Le bot source est l’appelant et le bot destination répond. Les réponses utilisent la structure publique avec srcBotId et destBotId.

settings peut contenir convInitBot, maxConvTurns, asCall, startTimeout et stateUpdate. Les deux bots doivent être visibles, appartenir à l’entreprise authentifiée et être différents.

Comptes SIP

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

get_trace_conversation ne contient que des appels webhook résumés dans fsCalls. Utilisez list_call_webhook_events pour les détails complets. Les conversations soumises à une restriction de conservation sont exclues et les filtres d’API masquées sont appliqués.