Servidor MCP do VoiceBooker

O servidor MCP (Model Context Protocol) do VoiceBooker permite que um cliente de IA compatível gerencie os recursos VoiceBooker da empresa autenticada. É possível consultar e editar bots e stages, configurar contas SIP e investigar o histórico de chamadas sem criar uma integração REST separada.

Adicionar o servidor

O servidor usa MCP Streamable HTTP e está disponível em:

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

Cada solicitação deve incluir um token de API do VoiceBooker no cabeçalho Token:

Token: <seu-token-de-api>

O token define o contexto da empresa; recursos de outras empresas não podem ser lidos ou alterados. Compartilhe o token apenas com o cliente MCP necessário e não o coloque em configurações compartilhadas.

Exemplo de configuração JSON:

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

Dependendo do cliente, o campo pode se chamar headers, httpHeaders ou ser definido por uma variável de ambiente. Reconecte o cliente depois de salvar a configuração para que ele descubra as ferramentas.

Usar o servidor

O servidor retorna IDs para os seus recursos. Reutilize-os exatamente como foram retornados. Para inspecionar um bot, use list_bots e depois list_stages com o ID do bot: os stages contêm os prompts, ferramentas, funções e o comportamento real. Leia todos os stages antes de fazer alterações.

Para investigar uma conversa, use primeiro list_call_history e depois get_trace_conversation com o ID da sessão retornado. O trace contém turnos, estado, stack e chamadas de funções ou webhooks.

Ferramentas disponíveis

Bots e stages

Ferramenta	Função
`list_bots`	Lista os contêineres de bots. `include_deleted` inclui bots ocultos.
`create_bot`	Cria um contêiner com um stage `Welcome`. `name` é obrigatório; `settings`, `initial_state`, `wizard` e `editable_keys` são opcionais.
`update_bot`	Altera os metadados sem substituir o comportamento dos stages. `bot_id` é obrigatório.
`delete_bot`	Exclui ou oculta um bot; bots com stages ficam ocultos.
`list_stages`	Lista todos os stages ordenados de um bot. `bot_id` é obrigatório.
`create_stage`	Cria um stage ligado a um bot. `bot_id` e `name` são obrigatórios.
`update_stage`	Altera um stage e sua configuração por bot. `bot_id` e `stage_id` são obrigatórios.
`delete_stage`	Remove um stage do fluxo. `bot_id` e `stage_id` são obrigatórios.

No modo de texto, prompt é um prompt Liquid/de sistema e tools é um array JSON de ferramentas compatível com OpenAI. No modo JavaScript, ative settings.promptExec ou settings.toolsExec para o campo correspondente. Não misture os formatos; as funções devem retornar objetos estruturados, nunca uma string simples ou null.

Use wizard para assistentes simples de um único stage. Para fluxos avançados ou multi-stage, crie ou altere os stages separadamente.

Contas SIP

Ferramenta	Função
`list_sip_accounts`	Lista contas usadas para registro, roteamento, webhooks e transferências. `include_inactive` é `true` por padrão.
`create_sip_account`	Salva uma conta SIP editável e atualiza o registro do connector; não compra nem provisiona um número.
`update_sip_account`	Atualiza uma conta preservando campos não informados; `id` é obrigatório e as configurações são mescladas.
`delete_sip_account`	Exclui contas editáveis. Contas gerenciadas pelo sistema são desregistradas com `register: false`.

As senhas SIP são somente para escrita e nunca são retornadas. Ao atualizar, omitir uma senha preserva a existente; uma string vazia a remove.

Histórico e traces

Ferramenta	Função
`list_call_history`	Pesquisa sessões telefônicas e de chat. Todos os parâmetros são opcionais: `bot_id`, `start`, `end_date`, `call`, `limit` e `offset`. Sem parâmetros, pesquisa todos os bots.
`get_trace_conversation`	Retorna turnos e eventos de trace de uma sessão. `call_session_id` é obrigatório e `limit` tem máximo de 1000.

Conversas sujeitas a retenção de dados são excluídas e as máscaras de webhook configuradas são aplicadas. Trate transcrições, números e dados de funções como informações comerciais confidenciais.