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

Herramienta	Función
`list_bots`	Lista los contenedores de bots.
`create_bot`	Crea un contenedor con un stage `Welcome`. `name` es obligatorio; `settings`, `initial_state`, `wizard` y `editable_keys` son opcionales.
`update_bot`	Modifica los metadatos sin sustituir el comportamiento de los stages. `botId` es obligatorio.
`delete_bot`	Elimina u oculta un bot; los bots con stages se ocultan.
`list_stages`	Lista todos los stages ordenados de un bot. `botId` es obligatorio.
`create_stage`	Crea un stage asociado a un bot. `botId` y `name` son obligatorios.
`update_stage`	Modifica un stage y su configuración por bot. `botId` y `stageId` son obligatorios.
`delete_stage`	Elimina un stage del flujo. `botId` y `stageId` son obligatorios.

En modo texto, prompt es un prompt Liquid/de sistema y tools es un array JSON de herramientas compatible con OpenAI. En modo JavaScript, activa settings.promptExec o settings.toolsExec para el campo correspondiente. No mezcles los formatos; las funciones deben devolver objetos estructurados, nunca una cadena simple o null.

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

Cuentas SIP

Herramienta	Función
`list_sip_accounts`	Lista cuentas usadas para registro, enrutamiento, webhooks y transferencias. `include_inactive` es `true` de forma predeterminada.
`create_sip_account`	Guarda una cuenta SIP editable y actualiza el registro del conector; no compra ni provisiona un número.
`update_sip_account`	Actualiza una cuenta conservando los campos no indicados; `id` es obligatorio y la configuración se combina.
`delete_sip_account`	Elimina cuentas editables. Las cuentas gestionadas por el sistema se desregistran con `register: false`.

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

Herramienta	Función
`list_call_history`	Busca sesiones telefónicas y de chat. Todos los parámetros son opcionales: `botId`, `start`, `end_date`, `call`, `limit` y `offset`. Sin parámetros, busca todos los bots.
`get_trace_conversation`	Devuelve turnos y eventos de trace de una sesión. `callSessionId` es obligatorio y `limit` tiene un máximo de 1000.

Las conversaciones sujetas a retención de datos se excluyen y se aplican las máscaras de webhook configuradas. Trata las transcripciones, los números y los datos de funciones como información empresarial confidencial.