Skip to content

MCP Server

Overview

The MCP (Model Context Protocol) server provides AI-powered call handling capabilities. It enables AI agents to perform actions during phone calls, such as transferring calls, looking up contacts, and creating leads.

Connection

Endpoint

https://{domain}:9443/ucp/v2/mcp

The server uses HTTP Streamable transport.

Connect to the {domain} of the platform that carries the call. Call control tools act on calls of that platform only: a client serving calls from more than one platform must choose the endpoint, and the API key, per call. On the wrong platform transfer_call and hangup_call return an error.

Authentication

Authentication is required via API Key:

Header Description
X-API-Key Your API key

Context Headers

The following headers can be passed to provide context for the MCP session:

Header Required Description
account_id Yes The account identifier
persona_id Yes The AI persona identifier
call_id Yes The active call identifier
caller_id_number No The caller's phone number

Available Tools

Global Tools

These tools are automatically available for all AI personas.

transfer_call

Transfers the active call to a specified destination number.

Parameter Type Required Description
destination number string Yes The phone number to transfer the call to
caller_id_name string No Name the destination sees. Line breaks become spaces; longer than 120 characters is cut. Omit it to show the caller's own name.
caller_id_number string No Number the destination sees. Only digits and a leading + are kept, up to 32 characters. Omit it to show the caller's own number.

Example, for an AI agent that hands the caller to its loan desk:

{
  "name": "transfer_call",
  "arguments": {
    "destination number": "2001",
    "caller_id_name": "Fintech Loan Desk",
    "caller_id_number": "+94117575100"
  }
}

The two Caller ID fields are independent: send only one to change only that part. When the call goes to an outside number, the account's outbound Caller ID rules and the carrier decide which number is presented, and they can replace caller_id_number.


is_office_open

Checks if the office is currently open based on the persona's configured office hours and the account's timezone.

Possible responses: - Office is currently open - Office is currently closed - Office is closed today - Office is open 24 hours today


lookup_contact

Searches for a contact by phone number across all connected contact sources (native contacts, Google, Microsoft).

Parameter Type Required Description
phone_number string Yes The phone number to search for

Returns: Contact name, phone numbers, company, and source.


check_user_availability

Checks if a user is available to receive calls based on their Do Not Disturb (DND) status.

Parameter Type Required Description
user_id string Yes The user ID to check

Returns: User availability status and DND setting.


create_lead

Creates a new lead from the current call. If a lead with the same phone number already exists, a new case is created and linked to the existing lead.

Parameter Type Required Description
name string Yes Caller's name
intent string Yes The purpose of the call
classification string No One of: lead, customer, spam, other
summary string No Summary of the conversation
notes string No Additional notes

hangup_call

Ends the active call. The hangup runs a few seconds after the response, so the end of a spoken goodbye is not cut off. The tool returns an error instead when the call is not active on this platform: it already ended, or the client connected to a different platform from the one carrying the call.


Custom Tools (Per Persona)

These tools can be configured for each AI persona through the Portal.

Transfer to User

Transfers the call to a specific pre-configured user. The tool name and description are customizable.

Transfer to Queue

Transfers the call to a specific pre-configured queue. The tool name and description are customizable.

API Request

Makes a custom HTTP request to an external API. Supports: - Custom URL with variable placeholders - HTTP methods (GET, POST, etc.) - Custom headers - Variable types: text, number, and dropdown options

SDK Integration Example

Google Gen AI SDK (Python)

from google import genai
from google.genai import types

client = genai.Client()

## Define the MCP server connection
mcp_tools = types.Tool(
    mcp_servers=[
        types.McpServer(
            url="https://{domain}:9443/ucp/v2/mcp",
            http_headers={
                "X-API-Key": "your-api-key",
                "account_id": "your-account-id",
                "persona_id": "your-persona-id",
                "call_id": "your-call-id",
                "caller_id_number": "+1234567890"
            }
        )
    ]
)

## Configure the Live API session with MCP tools
config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    tools=[mcp_tools]
)

async with client.aio.live.connect(model="gemini-2.0-flash-live-001", config=config) as session:
    # The session now has access to MCP tools
    # Audio input/output handling goes here
    pass