Model Context Protocol - Voice Agent API

Connect Model Context Protocol (MCP) servers to extend your agents with external tools and data sources.

Prerequisites: API key, MCP server endpoint URL

Overview

MCP servers provide a standardized way for agents to access external tools and data sources. Agents can connect to multiple MCP servers to extend their capabilities beyond built-in integrations.

Configuration Fields

name (string, required) - Human-readable name for the server
description (string, optional) - Description of the server’s purpose or tools
url (string, required) - MCP server endpoint URL
auth_type (string, optional) - Authentication type: "none", "bearer_token", "api_key", "custom_headers". Default: "none"
auth_token (string, optional) - Token for "bearer_token" or "api_key" authentication
headers (object, optional) - HTTP headers for authentication or custom configuration

Transport Type Detection

The API automatically detects the appropriate transport protocol based on the URL path:

URLs ending with /mcp → streamable HTTP transport (recommended)
URLs ending with /sse → Server-Sent Events transport (deprecated)
Other URLs → defaults to SSE for backward compatibility

Create Agent with MCP Servers

Configure MCP servers when creating a new agent.

import requests

response = requests.post(
    'https://dev.voice.ai/api/v1/agent/',
    headers={'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'},
    json={
        'name': 'MCP-Enhanced Agent',
        'config': {
            'prompt': 'You are an assistant with access to external tools via MCP servers.',
            'mcp_servers': [
                {
                    'name': 'Example API Server',
                    'description': 'Provides access to internal APIs',
                    'url': 'https://api.example.com/mcp',
                    'auth_type': 'bearer_token',
                    'auth_token': 'your-api-token'
                }
            ]
        }
    }
)

agent_id = response.json()['agent_id']
print(f'Created agent with MCP servers: {agent_id}')

curl -X POST "https://dev.voice.ai/api/v1/agent/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MCP-Enhanced Agent",
    "config": {
      "prompt": "You are an assistant with access to external tools via MCP servers.",
      "mcp_servers": [
        {
          "name": "Example API Server",
          "description": "Provides access to internal APIs",
          "url": "https://api.example.com/mcp",
          "auth_type": "bearer_token",
          "auth_token": "your-api-token"
        }
      ]
    }
  }'

const response = await fetch('https://dev.voice.ai/api/v1/agent/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'MCP-Enhanced Agent',
    config: {
      prompt: 'You are an assistant with access to external tools via MCP servers.',
      mcp_servers: [
        {
          name: 'Example API Server',
          description: 'Provides access to internal APIs',
          url: 'https://api.example.com/mcp',
          auth_type: 'bearer_token',
          auth_token: 'your-api-token'
        }
      ]
    }
  })
});

const data = await response.json();
console.log(`Created agent with MCP servers: ${data.agent_id}`);

Update Agent with MCP Servers

Add or modify MCP servers for an existing agent. Note: Agent must be paused before updating.

import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'}

# Pause agent first
requests.post(f'https://dev.voice.ai/api/v1/agent/{agent_id}/pause', headers=headers)

# Update with MCP servers
response = requests.put(
    f'https://dev.voice.ai/api/v1/agent/{agent_id}',
    headers=headers,
    json={
        'config': {
            'mcp_servers': [
                {
                    'name': 'Database Server',
                    'description': 'Access to customer database',
                    'url': 'https://db.example.com/mcp',
                    'auth_type': 'api_key',
                    'auth_token': 'db-api-key-123'
                },
                {
                    'name': 'Calendar Server',
                    'url': 'https://calendar.example.com/mcp',
                    'headers': {
                        'X-API-Key': 'calendar-key',
                        'X-Client-ID': 'client-123'
                    }
                }
            ]
        }
    }
)

# Redeploy agent
requests.post(f'https://dev.voice.ai/api/v1/agent/{agent_id}/deploy', headers=headers)

# Pause agent first
curl -X POST "https://dev.voice.ai/api/v1/agent/{agent_id}/pause" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Update with MCP servers
curl -X PUT "https://dev.voice.ai/api/v1/agent/{agent_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "mcp_servers": [
        {
          "name": "Database Server",
          "description": "Access to customer database",
          "url": "https://db.example.com/mcp",
          "auth_type": "api_key",
          "auth_token": "db-api-key-123"
        }
      ]
    }
  }'

# Redeploy agent
curl -X POST "https://dev.voice.ai/api/v1/agent/{agent_id}/deploy" \
  -H "Authorization: Bearer YOUR_API_KEY"

const headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' };

// Pause agent first
await fetch(`https://dev.voice.ai/api/v1/agent/${agentId}/pause`, { method: 'POST', headers });

// Update with MCP servers
await fetch(`https://dev.voice.ai/api/v1/agent/${agentId}`, {
  method: 'PUT',
  headers,
  body: JSON.stringify({
    config: {
      mcp_servers: [
        {
          name: 'Database Server',
          description: 'Access to customer database',
          url: 'https://db.example.com/mcp',
          auth_type: 'api_key',
          auth_token: 'db-api-key-123'
        }
      ]
    }
  })
});

// Redeploy agent
await fetch(`https://dev.voice.ai/api/v1/agent/${agentId}/deploy`, { method: 'POST', headers });

Authentication Types

No Authentication

{
  "name": "Public API Server",
  "url": "https://public-api.example.com/mcp",
  "auth_type": "none"
}

Bearer Token

{
  "name": "Authenticated Server",
  "url": "https://api.example.com/mcp",
  "auth_type": "bearer_token",
  "auth_token": "your-bearer-token"
}

API Key

{
  "name": "API Key Server",
  "url": "https://api.example.com/mcp",
  "auth_type": "api_key",
  "auth_token": "your-api-key"
}

Custom Headers

{
  "name": "Custom Auth Server",
  "url": "https://api.example.com/mcp",
  "auth_type": "custom_headers",
  "headers": {
    "X-API-Key": "custom-key",
    "X-Client-ID": "client-123",
    "Authorization": "Custom token-xyz"
  }
}

Multiple MCP Servers

Agents can connect to multiple MCP servers simultaneously.

import requests

response = requests.post(
    'https://dev.voice.ai/api/v1/agent/',
    headers={'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'},
    json={
        'name': 'Multi-Server Agent',
        'config': {
            'prompt': 'You have access to multiple external services.',
            'mcp_servers': [
                {
                    'name': 'Database',
                    'url': 'https://db.example.com/mcp',
                    'auth_type': 'bearer_token',
                    'auth_token': 'db-token'
                },
                {
                    'name': 'Calendar',
                    'url': 'https://calendar.example.com/mcp',
                    'auth_type': 'api_key',
                    'auth_token': 'cal-key'
                },
                {
                    'name': 'Analytics',
                    'url': 'https://analytics.example.com/mcp',
                    'headers': {'X-API-Key': 'analytics-key'}
                }
            ]
        }
    }
)

curl -X POST "https://dev.voice.ai/api/v1/agent/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Multi-Server Agent",
    "config": {
      "prompt": "You have access to multiple external services.",
      "mcp_servers": [
        {
          "name": "Database",
          "url": "https://db.example.com/mcp",
          "auth_type": "bearer_token",
          "auth_token": "db-token"
        },
        {
          "name": "Calendar",
          "url": "https://calendar.example.com/mcp",
          "auth_type": "api_key",
          "auth_token": "cal-key"
        }
      ]
    }
  }'

await fetch('https://dev.voice.ai/api/v1/agent/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Multi-Server Agent',
    config: {
      prompt: 'You have access to multiple external services.',
      mcp_servers: [
        {
          name: 'Database',
          url: 'https://db.example.com/mcp',
          auth_type: 'bearer_token',
          auth_token: 'db-token'
        },
        {
          name: 'Calendar',
          url: 'https://calendar.example.com/mcp',
          auth_type: 'api_key',
          auth_token: 'cal-key'
        }
      ]
    }
  })
});

Best Practices

URL Format: Use URLs ending with /mcp for recommended HTTP transport
Security: Store authentication tokens securely and never expose them in client-side code
Error Handling: MCP servers that fail to connect are logged but don’t prevent agent deployment
Testing: Test MCP server connectivity before deploying agents to production

Next Steps

Agent Quickstart - Create your first agent
API Reference - Complete agent configuration options

Get started

Text-to-Speech

Voice Agents

SDKs

Model Context Protocol - Voice Agent API

Overview

Configuration Fields

Transport Type Detection

Create Agent with MCP Servers

Update Agent with MCP Servers

Authentication Types

No Authentication

Bearer Token

API Key

Custom Headers

Multiple MCP Servers

Best Practices

Next Steps

​Overview

​Configuration Fields

​Transport Type Detection

​Create Agent with MCP Servers

​Update Agent with MCP Servers

​Authentication Types

​No Authentication

​Bearer Token

​API Key

​Custom Headers

​Multiple MCP Servers

​Best Practices

​Next Steps

Overview

Configuration Fields

Transport Type Detection

Create Agent with MCP Servers

Update Agent with MCP Servers

Authentication Types

No Authentication

Bearer Token

API Key

Custom Headers

Multiple MCP Servers

Best Practices

Next Steps