# MCP Server

Source: https://docs.qvoice.net/docs/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 |

---

#### 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
```
