Servidor MCP de VoiceBooker

El servidor MCP (Model Context Protocol) de VoiceBooker permite que un cliente de IA compatible gestione los recursos de VoiceBooker de la empresa autenticada. 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 Token:

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

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. `include_deleted` incluye bots ocultos.
`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. `bot_id` 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. `bot_id` es obligatorio.
`create_stage`	Crea un stage asociado a un bot. `bot_id` y `name` son obligatorios.
`update_stage`	Modifica un stage y su configuración por bot. `bot_id` y `stage_id` son obligatorios.
`delete_stage`	Elimina un stage del flujo. `bot_id` y `stage_id` 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: `bot_id`, `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. `call_session_id` 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.