VoiceBooker MCP Server

The VoiceBooker MCP (Model Context Protocol) server lets an MCP-compatible AI client manage the VoiceBooker resources belonging to the authenticated user. You can use it to inspect and update bots and stages, configure SIP accounts, and investigate call history without building a separate REST integration.

The server is available at:

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

It uses MCP Streamable HTTP. Every request must be authenticated with a VoiceBooker API token. The token is sent in the X-API-TOKEN header:

X-API-TOKEN: <your-api-token>

Create or manage API tokens in VoiceBooker, then give the token only to the MCP client that needs access. The server runs every operation in the context of the business associated with that token; resources belonging to another business cannot be read or changed.

Add the server to an MCP client

MCP clients use the same URL and header, but the configuration format varies by client. For clients that support a remote HTTP server, add this server as an HTTP or Streamable HTTP connection and set:

For example, an MCP client using a JSON configuration can use:

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

If your client calls the header httpHeaders, headers, or uses a separate environment-variable field, use the equivalent setting from that client's documentation. Do not put the token in the URL or commit it to a configuration file that is shared with other users.

After saving the configuration, reconnect or restart the client and ask it to list the available VoiceBooker tools. The client should discover the tools automatically through MCP; no tool-specific REST URLs are required.

Using the server

Resource ID fields use camelCase in MCP tool schemas and responses: botId, stageId, botStageId, sharedBotId, and callSessionId.

The MCP server returns IDs for its resources. Pass these IDs back to later tool calls exactly as returned. A useful inspection workflow is:

1. Call list_bots to find the bot.
2. Call list_stages with that bot's id. A bot is a container; its stages contain the actual prompts, tools, functions, and conversation behavior.
3. Read the complete stage data before changing it.
4. Use the relevant create, update, or delete tool and verify the returned object.

When debugging a conversation, call list_call_history first, then pass the returned call-session id to get_trace_conversation. This exposes the transcript turns, active state and stack, and function/webhook calls. Compare the trace with list_stages before proposing a stage change.

Available tools

Bots

Use wizard for a simple single-stage assistant. For expert-mode or multi-stage behavior, create or update the stages separately. Updating wizard data does not replace the stages.

Bot snapshots

Snapshots are versioned, business-scoped copies of a bot's complete definition. Restoring a snapshot first creates an automatic backup of the current bot. Snapshot IDs are scoped to their bot.

Bot tests

Bot-test tools manage persisted test setups for two different bots in the authenticated business. The source bot is the calling side and the destination bot is the responding side. Tool responses use the public API shape with srcBotId and destBotId.

The settings object may contain test options such as convInitBot, maxConvTurns, asCall, startTimeout, and stateUpdate. Both bot IDs must identify visible bots in the authenticated business, and the source and destination must be different. Inspect the available bots with list_bots first when IDs are not already known.

Stages

prompt and tools each have their own execution mode. The settings.promptExec and settings.toolsExec flags are independent and only affect their corresponding field:

• If promptExec is absent or false, prompt is rendered as Liquid text and sent to the LLM as a system message. With promptExec: true, prompt must contain JavaScript defining prompt(params). It must return an object: { prompt: "..." } creates a system message used by the LLM for its next answer, while { text: "..." } creates a direct assistant message returned unchanged. If both fields are returned, only prompt is used.
• If toolsExec is absent or false, a non-empty tools value must be a JSON-encoded string that decodes to an array of OpenAI-compatible function tools. Every local tool also needs a same-named handler in functions; a function placed in functions alone is never executed automatically. With toolsExec: true, tools must instead contain JavaScript defining tools(params), which must return { tools: [...] }; returning the array directly is invalid. Dynamically generated local tools also need same-named handlers in functions.
• The fields may use different modes. For example, JavaScript prompt with static JSON tools, or a Liquid prompt with dynamically generated JavaScript tools, is valid. Only mixing formats within one field is invalid: prompt cannot contain both Liquid text and a JavaScript function, and tools cannot contain both a JSON array string and JavaScript code.

// prompt code
function prompt(params) {
  return { prompt: "Welcome the caller and ask how you can help." };
}

// tools code
function tools(params) {
  return { tools: [] };
}

For promptExec, prompt adds a system instruction that the LLM uses to generate the next answer, while text sends literal assistant speech unchanged. If both are returned, prompt takes precedence. For example, a dynamic greeting can use return { prompt: "Greet the caller using this value: " + JSON.stringify(data) }; use return { text: "Value: " + data.value } only when the output must bypass LLM rewriting.

For a tool handler, data becomes an LLM-visible tool result and the LLM generates the final answer from it; text becomes direct assistant speech and is returned unchanged. If both data and text are returned by a tool handler, data takes precedence. The preferred natural-language pattern is:

function saveCustomer(params) {
  params.state.customerName = params.customerName;
  return { state: params.state, data: "Customer saved." };
}

The matching *State and *Stack settings control whether state and stage-stack data are passed through and persisted. prompt, tools, and tool handlers must return structured objects, not a bare string, array, null, or undefined.

list_stages also reports botEngine: lightweight means synchronous JavaScript with injected api() and webhook() helpers; extendedNodeJs means Promise-based JavaScript with fetch and the extended runtime package. A non-null bot settings.packageJson selects extendedNodeJs; an absent or null value selects lightweight. Do not use async, await, fetch, Promise, import, or require in a lightweight bot.

Use exact, case-sensitive stage names. The initial flow is configured with bot settings.initialStages. Prompt code can switch stages by returning the updated stack:

function prompt(params) {
  params.stack.push("Booking");
  return { state: params.state, stack: params.stack, prompt: "Ask the user for the booking date." };
}

A tool can switch stages declaratively with transitionTo: "Booking"; dropStage: true removes the current stage before the handler runs. Dynamic tools use function tools(params) { return { tools: [...] }; }, and every locally generated tool needs a same-named handler in functions. toolsState and toolsStack are required when tools(params) itself reads or returns state and stack; tool-level state and stack are required when the handler reads or returns them.

SIP accounts

SIP passwords are write-only. They are accepted when creating or updating an account but are never returned by list_sip_accounts, create_sip_account, or update_sip_account; the response only indicates whether a credential is configured.

Call history and traces

get_trace_conversation includes summarized webhook calls as fsCalls. Use list_call_webhook_events when full persisted event details are needed. Call-history tools exclude conversations marked for data retention and apply configured hidden-API filtering. Treat transcripts, phone numbers, function arguments, request/response bodies, and function results as sensitive business data.

Permissions and operational notes

• The token determines the business context and authorization boundary.
• IDs returned by the server identify the corresponding resource. Pass them back exactly as returned.
• Read a bot's stages before describing or editing what the bot does. Bot settings alone do not represent the complete conversation flow.
• Read a stage before updating it and preserve its current text-versus-JavaScript execution mode.
• Deleting bots or stages can change an active conversation flow. Confirm the target and inspect related stages first.
• Creating a SIP account saves configuration and can trigger connector registration; it does not provision a DID.