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

# MCP Integration

> Give your AI assistants access to any external tool or data source. Build custom integrations with n8n or your own code.

MCP (Model Context Protocol) allows your AI voice agents to access external tools and systems in real-time during calls. Agents can query databases, update CRMs, check calendars, and more—all while speaking with the customer.

## What is MCP?

MCP is an open protocol that lets AI models interact with external tools. Instead of hard-coding integrations, you connect an MCP server, and your assistants automatically discover and use available tools.

**Example:** Connect an MCP server for your CRM, and your assistant can:

* Look up customer information by phone number
* Check order status during the call
* Update contact records after qualifying a lead

## How MCP Works in EolasFlow

<Steps>
  <Step title="Connect MCP Server">
    You register an MCP server (your tools endpoint).
  </Step>

  <Step title="Enable on VoiceFlow">
    You enable MCP on a VoiceFlow and select your server.
  </Step>

  <Step title="Tool Discovery">
    When a call starts, EolasFlow connects to your MCP server and discovers available tools.
  </Step>

  <Step title="Agent Uses Tools">
    During the call, your AI assistant can call any discovered tool as needed.
  </Step>

  <Step title="Results Spoken">
    Tool results are processed by the AI and spoken to the customer.
  </Step>
</Steps>

## Setting Up MCP

### Step 1: Register an MCP Server

<Steps>
  <Step title="Navigate to Integrations">
    Go to **Connections → MCP Servers**.
  </Step>

  <Step title="Add New Server">
    Click **Add Server** and enter:

    * **Name:** A descriptive name (e.g., "CRM Tools")
    * **URL:** Your MCP server's SSE endpoint
  </Step>

  <Step title="Configure Authentication (Optional)">
    If your server requires authentication, add an API key. It's sent as a Bearer token.
  </Step>

  <Step title="Preview Tools">
    Click **Preview** to discover available tools without saving.
  </Step>

  <Step title="Review Tools">
    See the list of tools your server provides with their descriptions and parameters.
  </Step>

  <Step title="Save Server">
    Click **Save** to register the server.
  </Step>
</Steps>

### Step 2: Enable MCP on a VoiceFlow

<Steps>
  <Step title="Open VoiceFlow Settings">
    Go to **VoiceFlows** and click on your VoiceFlow.
  </Step>

  <Step title="Navigate to MCP Tab">
    Click the **MCP** tab in VoiceFlow settings.
  </Step>

  <Step title="Enable MCP">
    Toggle MCP **On** and select your registered server.
  </Step>

  <Step title="Configure Timeout (Optional)">
    Adjust the tool execution timeout if needed (default: 5 seconds).
  </Step>

  <Step title="Save Configuration">
    Click **Save**. Your agent now has access to MCP tools during calls.
  </Step>
</Steps>

## MCP Server Requirements

Your MCP server must:

* Support **SSE (Server-Sent Events)** transport
* Implement the **JSON-RPC 2.0** protocol
* Handle these methods:
  * `initialize` - Establish connection
  * `tools/list` - Return available tools
  * `tools/call` - Execute a tool

### Tool Definition Format

Your server returns tools in this format:

```json theme={null}
{
  "tools": [
    {
      "name": "get_customer",
      "description": "Look up customer by phone number",
      "inputSchema": {
        "type": "object",
        "properties": {
          "phone": {
            "type": "string",
            "description": "Customer phone number"
          }
        },
        "required": ["phone"]
      }
    }
  ]
}
```

### Tool Execution

When the AI calls a tool, your server receives:

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_customer",
    "arguments": {
      "phone": "+15551234567"
    }
  },
  "id": 123
}
```

Your server responds with:

```json theme={null}
{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Customer: John Smith, Status: Premium, Last Order: Jan 10"
      }
    ]
  },
  "id": 123
}
```

## Tool Whitelisting

Optionally restrict which tools your assistant can access:

1. In MCP server settings, expand **Advanced Options**
2. Add tool names to the **Tools Whitelist**
3. Only listed tools will be available to agents

<Note>
  Leave the whitelist empty to allow access to all tools from the server.
</Note>

## Agent Integration

Your AI assistant automatically uses MCP tools when appropriate. To help the agent know when to use tools, update your assistant's description:

```
You have access to these tools:
- get_customer: Use when you need customer information
- check_order_status: Use when customer asks about an order
- schedule_callback: Use to book follow-up calls

Always greet the customer, then use get_customer to look up their account.
```

<Tip>
  The AI automatically speaks tool results to the customer in a natural way. You don't need to script how results are presented.
</Tip>

## Testing MCP

### Test Server Connection

1. Go to **Connections → MCP Servers**
2. Click **Test** on your server
3. View discovered tools and verify they're correct

### Make a Test Call

1. Go to **Conversations**
2. Click **Test Call**
3. Select a VoiceFlow with MCP enabled
4. Call yourself and test tool usage

## MCP Configuration Options

| Setting             | Description                           | Default           |
| ------------------- | ------------------------------------- | ----------------- |
| **URL**             | Your MCP server's SSE endpoint        | Required          |
| **API Key**         | Authentication token (sent as Bearer) | Optional          |
| **Tools Whitelist** | Restrict available tools              | Empty (all tools) |
| **Timeout**         | Max time for tool execution           | 5000ms            |

## Best Practices

<Tip>
  **Fast Responses:** Tools should respond within 5 seconds. Long operations cause awkward pauses in conversation.
</Tip>

<Tip>
  **Clear Descriptions:** Write clear tool descriptions so the AI knows when to use each tool.
</Tip>

<Tip>
  **Handle Errors Gracefully:** Return helpful error messages the AI can communicate to the customer.
</Tip>

<Tip>
  **Test Thoroughly:** Make test calls to verify tools work correctly in real conversations.
</Tip>

<Warning>
  **Sensitive Data:** Be careful with tools that return sensitive information. The AI may speak this to the customer.
</Warning>

## Common Use Cases

| Use Case                | Tools to Implement                        |
| ----------------------- | ----------------------------------------- |
| **Customer Lookup**     | `get_customer_by_phone`                   |
| **Order Status**        | `check_order_status`, `track_shipment`    |
| **Appointment Booking** | `get_available_slots`, `book_appointment` |
| **CRM Updates**         | `update_contact`, `add_note`              |
| **Knowledge Base**      | `search_faq`, `get_article`               |

## Example: CRM Integration

A typical CRM MCP server might provide:

| Tool                | Description                              |
| ------------------- | ---------------------------------------- |
| `get_customer`      | Look up customer by phone                |
| `get_recent_orders` | List customer's recent orders            |
| `update_status`     | Update customer status (lead → prospect) |
| `add_note`          | Add note to customer record              |

During a call:

1. Call starts, agent greets customer
2. Agent calls `get_customer` to retrieve their info
3. Agent personalizes conversation based on customer data
4. Customer asks about an order, agent calls `get_recent_orders`
5. Call ends, agent calls `add_note` with call summary

## Troubleshooting

### Tools Not Discovered

1. Verify server URL is correct (must be SSE endpoint)
2. Check server is running and accessible
3. Test the server directly using **Preview**
4. Review server logs for connection issues

### Tool Execution Failures

1. Check timeout settings (increase if tools are slow)
2. Review tool error messages in call logs
3. Verify tool parameters match the schema
4. Test tools individually using your MCP server's interface

### Agent Not Using Tools

1. Update agent description to explain when to use tools
2. Verify MCP is enabled on the VoiceFlow
3. Check that tool descriptions are clear
4. Make test calls to observe agent behavior

## Build Your Own MCP Server

Don't have an existing MCP server? Build your own using automation platforms like **n8n**, **Zapier**, or **Make**. This gives you the freedom to connect your AI assistants to any tool or data source.

<CardGroup cols={3}>
  <Card title="n8n" icon="circle-nodes">
    Build MCP endpoints visually
  </Card>

  <Card title="Any API" icon="globe">
    Connect to any REST API
  </Card>

  <Card title="Your Database" icon="database">
    Query your own data
  </Card>
</CardGroup>

With a custom MCP server you can:

* Look up customer data from your CRM
* Check inventory or order status
* Query your internal databases
* Access any API during calls
* Build custom tools specific to your business

<Card title="Automation Workflows Guide" icon="rocket" href="/guides/automation">
  Learn how to build custom MCP servers with n8n and other tools
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configure Webhooks" icon="link" href="/guides/webhooks">
    Send call events to external systems
  </Card>

  <Card title="Configure Assistants" icon="robot" href="/guides/assistants">
    Configure your AI assistant to use MCP tools
  </Card>
</CardGroup>