> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.agentduet.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentduet.com/_mcp/server.

# MCP

This guide shows how to integrate the AgentDuet SDK with the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) so live speech agents can call structured tools over a shared tool surface during phone calls.

Sample: **OmniBank phone servicing** (authenticate, fees, escalate).

Demo caller: **Ava Chen**, card ending **4821**.

## What this integration provides

- AgentDuet answers inbound calls and streams PCM to Gemini Live
- Gemini Live declares tools from an MCP server's `list_tools` result
- Tool calls dispatch to the MCP server over stdio (`call_tool`)
- Swap `mcp_tools_server.py` to change capabilities without touching call wiring

## How the pieces fit

```mermaid
flowchart LR
  Caller[Caller] --> AgentDuet[AgentDuet]
  AgentDuet --> Gemini[Gemini Live]
  Gemini --> Tools[MCP tools]
  Tools --> Server[mcp_tools_server]
```

| Layer | Owns |
|---|---|
| **AgentDuet** | Connector, answer/hangup, PCM in/out |
| **Gemini Live** | Speech-to-speech + function calls |
| **MCP client** (`main.py`) | Stdio connect, schema cleanup, dispatch |
| **MCP server** (`mcp_tools_server.py`) | Bank tools (auth, summary, waiver, escalate) |

## Prerequisites

- Python **3.12+**
- AgentDuet API key and connector UUID from [agentduet.com](https://agentduet.com)
- [Gemini API key](https://aistudio.google.com/apikey)

## Step 1: Clone the sample

```bash
git clone https://github.com/AgentDuet/agentduet-samples.git
cd agentduet-samples/integrations/mcp/omnibank-servicing
```

Layout:

```
omnibank-servicing/
├── main.py               # AgentDuet + Gemini Live + MCP client
├── mcp_tools_server.py   # FastMCP bank tools (stdio)
├── requirements.txt
└── .env.example
```

## Step 2: Install

```bash
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

The sample pins [`agentduet==1.0.0`](https://pypi.org/project/agentduet/1.0.0/).

## Step 3: Configure `.env`

```bash
cp .env.example .env
```

```bash
AGENTDUET_API_KEY=your-connector-api-key
AGENTDUET_CONNECTOR_UUID=your-connector-uuid
GEMINI_API_KEY=
```

## Step 4: Run

```bash
python main.py
```

`main.py` spawns `mcp_tools_server.py` over stdio, loads tool declarations into
Gemini Live, then waits for calls.

Call your AgentDuet number. Say you are Ava Chen, card ending 4821.

| Ask / do | Expect |
|---|---|
| Give name + last 4 | Agent spells back, then `authenticate_customer` |
| Ask about fees | Late fee $30 + interest $45.50 from tool result |
| Waive one fee | `process_fee_waiver` approves (within $50 cap) |
| Waive both fees | Refused or escalated (`record_escalation`) |

## Tools

| Tool | Role |
|---|---|
| `authenticate_customer` | Match name + last 4; return fees and waiver limit |
| `get_account_summary` | Card, balance, outstanding fees |
| `process_fee_waiver` | Waive fees up to $50 total |
| `record_escalation` | Log supervisor handoff; return reference |

## How AgentDuet and MCP connect

1. On startup, the app opens an MCP stdio client to `mcp_tools_server.py`.
2. `list_tools` becomes Gemini `FunctionDeclaration`s (JSON Schema keys Gemini
   rejects are stripped).
3. On each inbound call, AgentDuet answers and Gemini Live streams audio.
4. When the model emits a tool call, the app runs `call_tool` and returns the
   result with `send_tool_response`.
5. Hangup closes the Gemini session; the MCP server process stays up for the
   next call.

## Related

- [Sample on GitHub](https://github.com/AgentDuet/agentduet-samples/tree/main/integrations/mcp/omnibank-servicing)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Gemini Live](/integrations/gemini-live)
- [Call Commands](/concepts/call-commands)