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