---
title: MCP Server Integration
slug: mcp-server-integration
docTags: 
createdAt: 2026-02-17T07:33:54.384Z
---

## Overview

UNITH Digital Humans support two powerful integration methods to extend conversational capabilities: [Custom Tools](https://docs.unith.ai/tools-usage-guide) and **MCP (Model Context Protocol) Servers**. These integrations enable your Digital Human to interact with external services, trigger workflows, and perform complex operations beyond standard conversation.

The integration mIethod you choose depends on your Digital Human's operation mode and your specific use case requirements.

## Understanding Custom Tools vs. MCP Servers

### Custom Tools

Workflow automation endpoints that connect your Digital Human to external services and business processes.

**Primary Use Cases**

- Zapier workflow integration
- n8n automation sequences
- Custom webhook endpoints

**Examples**

- Trigger a Zapier workflow to create support tickets in Jira
- Execute an n8n workflow to update customer data across multiple systems
- Automate email sequences through marketing platforms

**Compatibility:** Open Conversation mode (`oc`) only. To learn more about operation modes please check [this page.](https://docs.unith.ai/create-a-digital-human)

### MCP Servers

Powerful external services that handle complex, multi-step operations using the Model Context Protocol.

**Primary Use Cases**

- Advanced calculators with multiple functions
- Database query systems
- Complex workflow automation
- Third-party service integrations with stateful operations

**Examples**

- Perform multi-step mathematical calculations
- Query and analyze database records
- Execute sophisticated business logic workflows
- Integrate with external APIs requiring context preservation

**Compatibility:** Open Conversation mode only. To learn more about operation modes please check [this page.](https://docs.unith.ai/create-a-digital-human)

**Important Limitations:**

- **Azure OpenAI:** MCP servers are currently not available when using Azure OpenAI models.
- **Provider Dependency:** MCP availability depends on your LLM provider. Currently supported: OpenAI (GPT-4o-mini recommended)
- **Mutual Exclusivity:** In Open Conversation mode, when MCP servers are configured, custom tools are not loaded. 

:::hint{type="warning"}
The system uses either MCP servers OR custom tools, **not both simultaneously**.
:::



## Configuration Guide

### Basic Configuration Structure

All tool and MCP server configurations are defined within the conversationSettings object.

```curl
{
  "conversationSettings": {
    "chat_model_settings": {
      "provider": "openai",
      "llm_name": "gpt-4o-mini",
      "max_llm_tokens": 8096,
      "api_key": "your api key"
    },
    "tools": [
      // Your custom tools go here
    ],
    "mcp_servers": [
      // Your MCP servers go here
    ]
  }
}
```

## MCP Server Configuration

### Adding an MCP Server

MCP servers are defined as JSON objects within the mcp\_servers array.

**Example Configuration**

```json
{
  "mcp_servers": [
    {
      "server_label": "calculator",
      "server_url": "https://your-mcp-server.com/sse",
      "require_approval": "never",
      "allowed_tools": ["add", "subtract", "multiply", "divide"],
      "headers": {
        "Authorization": "Bearer your-token",
        "Content-Type": "application/json"
      }
    }
  ]
}
```

### MCP Server Parameters

| **Parameter**      | **Required** | **Description**                           | **Example**                        |
| ------------------ | ------------ | ----------------------------------------- | ---------------------------------- |
| `server_label`     | ✅            | Identifier for this MCP server            | "calculator"                       |
| `server_url`       | ✅            | MCP server SSE endpoint                   | "https\://server.com/sse"          |
| `require_approval` | ❌            | When to request user permission           | "never", "always", "sometimes"     |
| `allowed_tools`    | ❌            | Specific tools to enable from this server | \["add", "subtract"]               |
| `headers`          | ❌            | Custom HTTP headers for authentication    | \{"Authorization": "Bearer token"} |

## Prompt-Based Tool Selection

:::hint{type="warning"}
**Critical Concept:** [Tool](https://docs.unith.ai/tools-usage-guide) and **MCP server** selection is entirely prompt-based. **The AI agent decides** which tools to use based on your descriptions and the user's request. High-quality descriptions are essential for effective tool usage.
:::

**For MCP Servers:**

The system automatically retrieves tool information from the MCP server, but the agent still relies on the tool descriptions provided by the server for selection decisions.

- Ensure your MCP server provides clear, descriptive tool schemas
- Test tool selection with various user queries
- Monitor which tools are being called and refine descriptions as needed

## Complete Configuration Examples

### Open Conversation with MCP Server

```json
{
  "conversationSettings": {
    "chat_model_settings": {
      "provider": "openai",
      "llm_name": "gpt-4o-mini",
      "max_llm_tokens": 8096
    },
    "mcp_servers": [
      {
        "server_label": "business-calculator",
        "server_url": "https://mcp.example.com/calculator/sse",
        "require_approval": "never",
        "allowed_tools": ["calculate_roi", "calculate_margin", "forecast_revenue"],
        "headers": {
          "Authorization": "Bearer mcp_token_abc123",
          "Content-Type": "application/json"
        }
      }
    ]
  }
}
```

## Important Notes

**Tool Selection is Prompt-Based:** The AI agent decides which tools to use based solely on your descriptions and the user's query. Invest time in crafting clear, specific tool descriptions for optimal performance.

**MCP Server Limitations:** MCP servers are only available in Open Conversation mode with OpenAI models.

**Mutual Exclusivity:** In Open Conversation mode, when MCP servers are configured, custom tools are not loaded. Choose either MCP servers OR custom tools, not both.

**Provider Requirements:** MCP implementation uses OpenAI's protocol and is optimized for GPT-4o-mini. Other models may have varying levels of support.

**Authentication:** Secure your tool endpoints with API keys. Pass authentication credentials via the api\_key parameter or custom headers.

**Performance:** Tool execution adds latency to responses. Optimize your tool endpoints for fast response times.