MCP Server API Specification

The MCP (Model Context Protocol) server provides a JSON-RPC interface that allows external voice bots to interact with Buzzeasy workflows. It is primarily used to gracefully exit a call and optionally return structured data such as workflow variables and conversation transcripts.

Access the MCP server

Endpoint

POST https://api.buzzeasy.com/voicebots/mcp

Headers

Header	Value
Authorization	Bearer <token>
Content-Type	application/json
Accept	application/json, text/event-stream

Protocol

The API follows the JSON-RPC 2.0 specification.

Each request must include:

• jsonrpc: Must be "2.0"
• id: A unique request identifier
• method: The method to invoke
• params: Method-specific parameters

Tool Discovery

While there is only a single action to call, clients are able to discover available tools using the list action.

Request:

{
  "jsonrpc": "2.0",
  "id": "discover-tools-1",
  "method": "tools/list",
  "params": {}
}

Response:

{
  "result": {
    "tools": [
      {
        "name": "leave",
        "description": "Request end of conversation, and optionally pass collected information using workflowData and the transcription",
        "inputSchema": {
          "type": "object",
          "properties": {
            "conversationId": {
              "description": "Unique identifier of the conversation",
              "type": "string"
            },
            "workflowData": {
              "description": "Optional data to attach to the conversations",
              "type": ["object", "null"],
              "additionalProperties": {
                "type": ["string", "null"]
              },
              "default": null
            },
            "transcript": {
              "description": "Optional transcription recorded by the bot",
              "type": ["object", "null"],
              "properties": {
                "languageCode": {
                  "type": ["string", "null"]
                },
                "phrases": {
                  "type": ["array", "null"],
                  "items": {
                    "type": ["object", "null"],
                    "properties": {
                      "text": {
                        "type": ["string", "null"]
                      },
                      "timestamp": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "speakerType": {
                        "type": "string",
                        "enum": ["Customer", "Bot"]
                      }
                    }
                  }
                }
              },
              "default": null
            }
          },
          "required": ["conversationId"]
        }
      }
    ]
  },
  "id": "discover-tools-1",
  "jsonrpc": "2.0"
}

Leave tool

The leave tool can be used by the bot to gracefully leave the conversation and pass extra information back to the workflow.

The conversationId is provided to the external voice bot in the initial SIP INVITE request via the X-Conversation-Id header.

When the leave tool is invoked:

• The bot is removed from the call
• The workflow resumes execution
• Provided workflowData is merged into the current workflow context
• Provided transcript is stored and made available for further processing