MCP Server Integration

Overview

UNITH Digital Humans support two powerful integration methods to extend conversational capabilities: Custom Tools 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.

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.

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.

warning_amber

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.

code

{
  "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

code

{
  "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

warning_amber

Critical Concept: Tool 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

code

{
  "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.

scheduleLast updated Mar 18, 2026