VoiceBooker MCP Server

The VoiceBooker MCP (Model Context Protocol) server lets an MCP-compatible AI client manage the VoiceBooker resources belonging to the authenticated business. 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 Token header:

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:

Setting	Value
Transport	Streamable HTTP
URL	`https://voicebooker.de/app/api/v1/mcp`
Header	`Token: <your-api-token>`

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

{
  "mcpServers": {
    "voicebooker": {
      "url": "https://voicebooker.de/app/api/v1/mcp",
      "headers": {
        "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

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

Call list_bots to find the bot.
Call list_stages with that bot's id. A bot is a container; its stages contain the actual prompts, tools, functions, and conversation behavior.
Read the complete stage data before changing it.
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

Tool	Purpose	Important arguments
`list_bots`	Lists bot containers for the authenticated business.	`include_deleted` optionally includes soft-deleted bots. The result is an overview, not the full conversation definition.
`create_bot`	Creates a bot container and an initial `Welcome` stage.	`name` is required. Optional `settings`, `initial_state`, `wizard`, and `editable_keys` configure high-level bot data.
`update_bot`	Updates high-level bot metadata.	`bot_id` is required. Updating a bot does not change its stage behavior.
`delete_bot`	Deletes or soft-deletes a bot.	`bot_id` is required. Bots with stages are made invisible rather than being removed immediately.

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.

Stages

Tool	Purpose	Important arguments
`list_stages`	Lists every ordered stage attached to a bot.	`bot_id` is required; `include_deleted` optionally includes invisible stages.
`create_stage`	Creates and attaches a stage to a bot.	`bot_id` and `name` are required. Use `prompt`, `tools`, `functions`, `settings`, and `stage_config` to define behavior.
`update_stage`	Updates a stage and its per-bot-stage configuration.	`bot_id` and `stage_id` are required. `bot_stage_id` can identify a specific bot-stage association; `instance_settings` updates its configuration values.
`delete_stage`	Removes a stage from a bot's ordered flow.	`bot_id` and `stage_id` are required. Deleting the last association can hide or remove the stage depending on its contents.

Stages support two execution modes. In text mode, prompt is a Liquid/system prompt and tools is a JSON-encoded OpenAI-compatible function-tool array. In JavaScript mode, set settings.promptExec and/or settings.toolsExec to true and provide the corresponding JavaScript contract:

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

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

Do not mix JSON tool arrays with JavaScript tool code. The matching *State and *Stack settings control whether state and stage-stack data are passed through and persisted. Tool functions must return structured objects such as { data, text, state, stack }, not a bare string or null.

SIP accounts

Tool	Purpose	Important arguments
`list_sip_accounts`	Lists SIP accounts used for registration, inbound routing, webhooks, and transfers.	`include_inactive` controls whether inactive accounts are included; it defaults to `true`.
`create_sip_account`	Stores an editable SIP account and triggers a connector registration update.	Supply provider details such as `phone_number`, `sip_registrar`, `sip_user`, `sip_pass`, and optional `bot_id`, `webhook`, or `transfer_to`. It does not purchase or provision a phone number.
`update_sip_account`	Updates an account while preserving fields that were not supplied.	`id` is required. Settings are merged; omitted passwords are preserved, while an empty password clears the stored credential.
`delete_sip_account`	Removes an editable account or unregisters a system-managed account.	`id` is required. System-managed accounts cannot be deleted and are changed to `register: false`.

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

Tool	Purpose	Important arguments
`list_call_history`	Finds recent telephone-call and chat sessions.	All arguments are optional. Use `bot_id`, ISO-8601 `start`/`end_date`, `call`, `limit` (maximum 100), and `offset` to filter or paginate. Calling it with no arguments searches all bots for the business.
`get_trace_conversation`	Retrieves detailed conversation turns and trace events for one call session.	`call_session_id` is required; `limit` controls the number of turns and is capped at 1000.

Call-history tools exclude conversations marked for data retention and apply configured webhook masking. Treat transcripts, phone numbers, function arguments, 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.

VoiceBooker MCP Server

On this page