Skip to main content

Documentation Index

Fetch the complete documentation index at: https://voice.ai/llms.txt

Use this file to discover all available pages before exploring further.

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}')

​
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)

​
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'}
                }
            ]
        }
    }
)

​
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