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.

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

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.

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