> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP)

> Connect your agent to external MCP servers for extended capabilities

The Model Context Protocol (MCP) integration lets you connect your Telzino AI phone agent to external MCP servers, extending the agent's capabilities with custom tools, data sources, and actions that it can use during live conversations.

## What is MCP?

MCP is an open protocol that provides a standardized way to connect AI models to external systems. Many third-party CRMs, ERPs, and business platforms now offer MCP servers as part of their product. By connecting one of these MCP servers to your Telzino agent, you can give the agent direct access to that platform's data and functionality during live conversations — without building a custom integration from scratch.

## Key Benefits

* **Third-Party Platform Access** — Connect your agent to MCP servers provided by CRMs, ERPs, scheduling platforms, and other business tools to access their data and functionality during live calls.
* **Real-Time Data** — Your agent can fetch live data from connected platforms to provide accurate, up-to-date answers to callers (e.g., look up order status, check inventory, pull customer records).
* **Growing Ecosystem** — As more platforms adopt the MCP standard, new integrations become available without requiring custom development on your end.

## How to Enable MCP Integration

### Via the Dashboard

1. In the Telzino Dashboard, navigate to **Customers → your Organization → your Agent → Integrations**.
2. Find **Model Context Protocol (MCP)** and click to configure.
3. Enter the MCP server URL from your vendor — **SSE** endpoint for SSE transport, or the **streamable HTTP** MCP URL for HTTP transport (same field; it must match the transport you choose next).
4. Choose **Transport Type**: **`sse`** or **`http`**.
5. Click **Test Connection** to verify the endpoint and discover available tools.
6. Click **Save Connection**. Your agent can now call the tools exposed by that MCP server during live conversations.

### Via the API

You can also add MCP servers when creating or updating an agent via the API using the `extensions.mcp_servers` field. The request shape uses `name` and `url`; the platform transforms these to `connection_name` and `mcp_endpoint_url` when storing. See [Create Agent — MCP Servers Request Body](/api-reference/agents/create#mcp-servers-request-body) for all accepted fields.

**API-created connections show a yellow "Not tested" badge** in the Portal MCP dialog because no connection test has been run. To validate and activate tool discovery:

1. Open the agent in the Dashboard → **Integrations** → **Model Context Protocol (MCP)**.
2. Click the connection with the **Not tested** badge — it opens directly in edit mode.
3. Click **Test Connection** to verify the endpoint and populate the tools list.
4. Click **Update Connection** to save the test result (this clears the badge).

The **MCP Endpoint URL** field in the modal is the full URL of the MCP server endpoint (same helper text as in the product). You can enter a **`https://`** URL (typical in production) or an **`http://`** URL (for example **`http://localhost:3000/...`** for local development), as long as that host is reachable from Telzino when testing or at call time. That choice is the **URL scheme** of the address—separate from **Transport Type** **`http`** (streamable HTTP MCP) vs **`sse`** (SSE), which selects how the client speaks to the server once connected.

### SSE vs HTTP transport

**HTTP MCPs** are supported the same way as **SSE** MCPs. The stored row is still `extensions.mcp_servers[]` with the same fields; what changes is **`transport_type`** and which MCP client transport the platform uses when **testing** the connection and what the **voice / runtime** stack reads from the agent row.

* **`transport_type`** — Must be the lowercase string **`"sse"`** or **`"http"`** as persisted. Do **not** use `"SSE"`, `"HTTP"`, or other casing; the server reads the flag exactly as stored.
* **`mcp_endpoint_url`** — **Same field name** for both transports. For **`http`**, set it to your MCP server’s **streamable HTTP** endpoint. For **`sse`**, set it to your server’s **SSE** endpoint URL. Only `transport_type` distinguishes how the URL is interpreted.
* **Test connection (server-side)** — The test runner picks the transport from that flag: **`http`** → streamable HTTP client transport; **`sse`** (or non-`http`) → SSE client transport (with EventSource-style header behavior for SSE).

The Dashboard persists each connection in snake\_case: `connection_name`, `mcp_endpoint_url`, `transport_type` (either `"sse"` or `"http"`, lowercase), optional `auth_headers`, `initialization_options`, and after save an `id` (UUID). Optional `fingerprint` and a **`tools`** array (entries with **`name`** and **`description`** only—no full tool schemas) may appear when populated.

The JSON examples below use **`http`** transport and a streamable HTTP-style URL.

## API Usage

* **GET** [`/v1/agents/{agentId}`](/api-reference/agents/get) returns the agent row unchanged from storage. Whatever is under `extensions.mcp_servers` is the persisted list. Field reference: [Get Agent — stored MCP shape](/api-reference/agents/get#stored-mcp-connection-shape).

* **POST / PATCH** ([Create](/api-reference/agents/create) / [Update](/api-reference/agents/update) agent) validate `extensions` on write. Each MCP entry uses a **different request shape** (`name` and `url` are both required) — the platform transforms this to the stored shape on write. See [Create Agent — MCP request body](/api-reference/agents/create#mcp-servers-request-body). Do not paste a GET `mcp_servers` array directly into a POST/PATCH body without converting `connection_name` → `name` and `mcp_endpoint_url` → `url`.

**API-created connections are stored without `fingerprint` or `tools`** until they are tested from the Portal. The Portal displays a "Not tested" badge for these connections and opens them in edit mode for immediate testing.

Example **stored fragment** for a **dashboard-created** connection (after testing):

```json theme={null}
{
  "extensions": {
    "mcp_servers": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "connection_name": "My Company MCP Server",
        "mcp_endpoint_url": "https://mcp.example.com/mcp",
        "transport_type": "http",
        "auth_headers": { "Authorization": "Bearer YOUR_TOKEN" },
        "initialization_options": {},
        "fingerprint": "sha256:abc123…",
        "tools": [
          { "name": "lookup_customer", "description": "Find customer by phone number" }
        ]
      }
    ]
  }
}
```

Example **stored fragment** for an **API-created** connection (not yet tested):

```json theme={null}
{
  "extensions": {
    "mcp_servers": [
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "connection_name": "CRM MCP Server",
        "mcp_endpoint_url": "https://mcp.mycrm.com/sse",
        "transport_type": "sse",
        "auth_headers": {},
        "initialization_options": {},
        "tools": []
      }
    ]
  }
}
```

## Example Use Cases

* **CRM Integration** — Connect to your CRM's MCP server so your agent can pull up customer records and personalize conversations in real time.
* **ERP & Order Management** — Let your agent look up order status, check inventory, or retrieve account details from your ERP platform during a call.
* **Scheduling Platforms** — Connect to third-party scheduling systems that offer MCP servers to enable appointment booking and availability checking.
* **Healthcare & Practice Management** — Integrate with EHR and practice management systems that expose MCP endpoints for patient scheduling and record lookup.

<Info>
  MCP server URLs and authentication credentials are provided by the third-party platform you are integrating with. Check with your platform vendor to confirm they offer an MCP server and to obtain connection details.
</Info>