Servidor MCP do VoiceBooker

O servidor MCP (Model Context Protocol) do VoiceBooker permite que um cliente de IA compatível gerencie os recursos VoiceBooker do utilizador autenticado. É 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 X-API-TOKEN:

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

Os campos de ID dos recursos usam camelCase nos schemas e nas respostas MCP: botId, stageId, botStageId, sharedBotId e callSessionId. 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

prompt e tools têm, cada um, seu próprio modo de execução. As opções settings.promptExec e settings.toolsExec são independentes e afetam apenas o campo correspondente:

• Se promptExec estiver ausente ou for false, prompt será processado como texto Liquid e enviado ao LLM como mensagem do sistema. Com promptExec: true, prompt deve conter JavaScript definindo prompt(params). A função deve retornar um objeto: { prompt: "..." } cria uma mensagem do sistema usada pelo LLM na próxima resposta, enquanto { text: "..." } cria uma mensagem direta do assistente, retornada sem alterações. Se os dois campos forem retornados, somente prompt será usado.
• Se toolsExec estiver ausente ou for false, um valor tools não vazio deve ser uma string JSON que seja convertida em um array de ferramentas de função compatíveis com OpenAI. Cada ferramenta local também precisa de um handler com o mesmo nome em functions; uma função presente apenas em functions nunca é executada automaticamente. Com toolsExec: true, tools deve conter JavaScript definindo tools(params), e a função deve retornar { tools: [...] }; retornar o array diretamente é inválido. Ferramentas geradas dinamicamente também precisam de handlers com o mesmo nome em functions.
• Os dois campos podem usar modos diferentes. Por exemplo, um prompt JavaScript com ferramentas JSON estáticas ou um prompt Liquid com ferramentas JavaScript geradas dinamicamente são válidos. Apenas a mistura de formatos dentro do mesmo campo é proibida: prompt não pode conter texto Liquid e uma função JavaScript ao mesmo tempo, e tools não pode conter uma string JSON e código JavaScript ao mesmo tempo.

Em um handler de ferramenta, data é enviado ao LLM como resultado da ferramenta para que ele formule a próxima resposta. text é retornado diretamente como fala do assistente, sem alterações. Se ambos forem retornados, data terá precedência e text não será enviado diretamente.

list_stages também retorna botEngine: lightweight usa JavaScript síncrono com api() e webhook; extendedNodeJs usa JavaScript baseado em Promises e permite fetch. Um settings.packageJson não nulo ativa extendedNodeJs; ausente ou nulo ativa lightweight. Não use async, await, fetch, Promise, import ou require no motor leve.

Os nomes dos stages diferenciam maiúsculas e minúsculas. settings.initialStages define o stack inicial. O código do prompt pode mudar de stage retornando o stack atualizado:

function prompt(params) {
  params.stack.push("Booking");
  return { state: params.state, stack: params.stack, prompt: "Peça a data da reserva." };
}

Uma ferramenta pode mudar de stage com transitionTo: "Booking"; dropStage: true remove o stage atual antes do handler. Ferramentas dinâmicas usam function tools(params) { return { tools: [...] }; } e cada ferramenta local precisa de um handler com o mesmo nome em functions. toolsState/toolsStack aplicam-se a tools(params); state/stack ao seu handler.

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

Testes de bots

As ferramentas de teste de bots gerem configurações para dois bots diferentes da empresa autenticada. O bot de origem inicia a conversa e o bot de destino responde. As respostas usam a estrutura pública com srcBotId e destBotId.

settings pode incluir convInitBot, maxConvTurns, asCall, startTimeout e stateUpdate. Ambos os bots devem estar visíveis, pertencer à empresa autenticada e ser diferentes.

Contas SIP

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

get_trace_conversation inclui chamadas webhook resumidas como fsCalls. Use list_call_webhook_events para obter os detalhes completos. Conversas sujeitas a retenção de dados são excluídas e filtros de APIs ocultas são aplicados.