Servidor MCP de VoiceBooker

El servidor MCP (Model Context Protocol) de VoiceBooker permite que un cliente de IA compatible gestione los recursos de VoiceBooker del usuario autenticado. Puedes consultar y editar bots y stages, configurar cuentas SIP e investigar el historial de llamadas sin crear una integración REST independiente.

Añadir el servidor

El servidor utiliza MCP Streamable HTTP y está disponible en:

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

Cada solicitud debe incluir un token de API de VoiceBooker en la cabecera X-API-TOKEN:

X-API-TOKEN: <tu-token-de-api>

El token determina el contexto de la empresa; los recursos de otras empresas no se pueden leer ni modificar. Comparte el token solo con el cliente MCP necesario y no lo guardes en configuraciones compartidas.

Ejemplo de configuración JSON:

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

Según el cliente, el campo puede llamarse headers, httpHeaders o definirse mediante una variable de entorno. Vuelve a conectar el cliente después de guardar la configuración para que descubra las herramientas.

Usar el servidor

Los campos de ID de recursos usan camelCase en los esquemas y respuestas MCP: botId, stageId, botStageId, sharedBotId y callSessionId. El servidor devuelve IDs para sus recursos. Reutilízalos exactamente como se devuelven. Para inspeccionar un bot, usa list_bots y después list_stages con su ID: los stages contienen los prompts, herramientas, funciones y el comportamiento real. Lee todos los stages antes de realizar cambios.

Para investigar una conversación, usa primero list_call_history y después get_trace_conversation con el ID de sesión devuelto. El trace incluye turnos, estado, stack y llamadas a funciones o webhooks.

Herramientas disponibles

Bots y stages

prompt y tools tienen cada uno su propio modo de ejecución. Las opciones settings.promptExec y settings.toolsExec son independientes y solo afectan al campo correspondiente:

• Si promptExec está ausente o es false, prompt se procesa como texto Liquid y se envía al LLM como mensaje del sistema. Con promptExec: true, prompt debe contener JavaScript que defina prompt(params). La función debe devolver un objeto: { prompt: "..." } crea un mensaje del sistema que el LLM usa para su siguiente respuesta, mientras que { text: "..." } crea un mensaje directo del asistente que se devuelve sin cambios. Si devuelve ambos campos, solo se utiliza prompt.
• Si toolsExec está ausente o es false, un valor tools no vacío debe ser una cadena JSON que se decodifique en un array de herramientas de función compatibles con OpenAI. Cada herramienta local también necesita un handler con el mismo nombre en functions; una función situada solo en functions nunca se ejecuta automáticamente. Con toolsExec: true, tools debe contener JavaScript que defina tools(params), y la función debe devolver { tools: [...] }; devolver directamente el array no es válido. Las herramientas generadas dinámicamente también necesitan handlers con el mismo nombre en functions.
• Los dos campos pueden usar modos diferentes. Por ejemplo, un prompt JavaScript con herramientas JSON estáticas, o un prompt Liquid con herramientas JavaScript generadas dinámicamente, son válidos. Solo está prohibido mezclar formatos dentro del mismo campo: prompt no puede contener a la vez texto Liquid y una función JavaScript, y tools no puede contener a la vez una cadena JSON y código JavaScript.

En un handler de herramienta, data se envía al LLM como resultado de la herramienta para que formule la siguiente respuesta. text se devuelve directamente como respuesta del asistente sin cambios. Si se devuelven ambos, data tiene prioridad y text no se envía directamente.

list_stages también devuelve botEngine: lightweight usa JavaScript síncrono con api() y webhook; extendedNodeJs usa JavaScript basado en Promises y permite fetch. Un settings.packageJson no nulo activa extendedNodeJs; ausente o nulo activa lightweight. No uses async, await, fetch, Promise, import ni require en el motor ligero.

Los nombres de stage distinguen mayúsculas y minúsculas. settings.initialStages define el stack inicial. El código del prompt puede cambiar de stage devolviendo el stack actualizado:

function prompt(params) {
  params.stack.push("Booking");
  return { state: params.state, stack: params.stack, prompt: "Pide la fecha de la reserva." };
}

Una herramienta puede cambiar de stage con transitionTo: "Booking"; dropStage: true elimina el stage actual antes del handler. Las herramientas dinámicas usan function tools(params) { return { tools: [...] }; } y cada herramienta local necesita un handler con el mismo nombre en functions. toolsState/toolsStack se aplican a tools(params) y state/stack a su handler.

Usa wizard para asistentes sencillos de un solo stage. Para flujos expertos o multi-stage, crea o modifica los stages por separado.

Pruebas de bots

Las herramientas de pruebas de bots gestionan configuraciones para dos bots diferentes de la empresa autenticada. El bot de origen es quien inicia la conversación y el bot de destino quien responde. Las respuestas usan la estructura pública con srcBotId y destBotId.

settings puede incluir convInitBot, maxConvTurns, asCall, startTimeout y stateUpdate. Ambos bots deben estar visibles, pertenecer a la empresa autenticada y ser diferentes.

Cuentas SIP

Las contraseñas SIP son de solo escritura y nunca se devuelven. Al actualizar, omitir una contraseña conserva la existente; una cadena vacía la elimina.

Historial y trazas

get_trace_conversation incluye las llamadas webhook resumidas como fsCalls. Usa list_call_webhook_events para obtener los detalles completos. Se excluyen las conversaciones sujetas a retención de datos y se aplican los filtros de API ocultas configurados.