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

# Model Context Protocol - Voice Agent API

> Connect MCP servers to your Voice.ai agents to extend their capabilities with external tools and data. Learn to configure transports, authentication, and multiple server connections

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

<Info>
  **Prerequisites**: [API key](/docs/guides/authentication), MCP server endpoint URL
</Info>

## 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.

<CodeGroup>
  ```python Python theme={null}
  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}')
  ```

  ```bash cURL theme={null}
  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"
          }
        ]
      }
    }'
  ```

  ```typescript TypeScript theme={null}
  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}`);
  ```
</CodeGroup>

## Update Agent with MCP Servers

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```bash cURL theme={null}
  # 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"
  ```

  ```typescript TypeScript theme={null}
  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 });
  ```
</CodeGroup>

## Authentication Types

### No Authentication

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

### Bearer Token

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

### API Key

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

### Custom Headers

```json theme={null}
{
  "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.

<CodeGroup>
  ```python Python theme={null}
  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'}
                  }
              ]
          }
      }
  )
  ```

  ```bash cURL theme={null}
  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"
          }
        ]
      }
    }'
  ```

  ```typescript TypeScript theme={null}
  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'
          }
        ]
      }
    })
  });
  ```
</CodeGroup>

## 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](/docs/guides/voice-agents/quickstart) - Create your first agent
* [API Reference](/docs/api-reference) - Complete agent configuration options