# How to List Available Voices and Personalities Using the VoiceStudio MCP Server

> Learn how to list available voices and personalities using the VoiceStudio MCP server. Access voice profiles and personality configurations via GET endpoints with proper authentication.

- Repository: [Palash Debnath/VoiceStudio](https://github.com/debpalash/VoiceStudio)
- Tags: how-to-guide
- Published: 2026-09-09

---

**The VoiceStudio MCP server exposes `GET /mcp/list_voices` and `GET /mcp/list_personalities` endpoints that return JSON arrays of voice profiles and personality configurations when authenticated with the `X-OmniVoice-Client-Id` header.**

VoiceStudio provides a Multilingual Conversational Platform (MCP) server that catalogs synthetic voice profiles and their associated personalities through a JSON-RPC-style HTTP interface. This guide explains how to list available voices and personalities using the MCP server, referencing the actual implementation in the `debpalash/VoiceStudio` repository.

## MCP Server Architecture and Voice Registry

The MCP server implementation resides in [`backend/mcp_server.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/mcp_server.py) and initializes lazily to conserve resources. When the first request hits any MCP endpoint, the server instantiates a `FastMCP` instance around line 329. The server relies on the `VoiceRegistry` service defined in [`backend/services/plugin_sdk.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/services/plugin_sdk.py) to retrieve voice and personality data.

Voice profiles represent individual voice configurations (ID, name, language), while personalities define behavioral contexts that map to specific voice profiles. Both data types are serialized and returned through dedicated HTTP endpoints.

## HTTP API Endpoints for Voice Discovery

### List Voices Endpoint

Send a `GET` request to `/mcp/list_voices` to retrieve the complete catalog of available voice profiles.

```bash
curl -s -H "X-OmniVoice-Client-Id: my-client" \
     http://localhost:8000/mcp/list_voices | jq .

```

The endpoint returns an array of voice-profile objects containing identifiers, display names, and language codes. In [`backend/mcp_server.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/mcp_server.py), the `list_voices` coroutine (around line 483) handles this request by iterating over stored `VoiceProfile` objects from the registry.

### List Personalities Endpoint

Send a `GET` request to `/mcp/list_personalities` to retrieve personality configurations.

```bash
curl -s -H "X-OmniVoice-Client-Id: my-client" \
     http://localhost:8000/mcp/list_personalities | jq .

```

This endpoint returns personality objects including IDs, descriptions, and their mappings to voice profiles. The implementation builds this list from `Personality` entries that reference specific voice profiles in the registry.

## OpenAI-Compatible Python SDK

VoiceStudio provides an OpenAI compatibility layer in [`backend/api/routers/openai_compat.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/openai_compat.py) that exposes `list_voices()` and `list_personalities()` methods directly. This allows tools designed for the OpenAI API to interact with VoiceStudio without modification.

```python

# Using the built‑in OpenAI‑compatible client

import omv  # VoiceStudio’s Python SDK

client = omv.OpenAICompat()
voices = client.list_voices()          # -> list of dicts

personalities = client.list_personalities()  # -> list of dicts

print(voices, personalities)

```

The `list_voices()` wrapper is implemented around line 683 in [`backend/api/routers/openai_compat.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/openai_compat.py), providing a seamless interface for existing OpenAI integrations.

## Direct FastMCP Client Access

For applications requiring direct MCP protocol access, use the FastMCP client:

```python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP()
voices = await mcp.list_voices()
personalities = await mcp.list_personalities()

```

This approach bypasses the HTTP layer and communicates directly with the MCP server instance.

## Configuration and Environment Setup

The MCP server binds to the address and port defined by the `OMNIVOICE_MCP_PORT` environment variable, defaulting to port `8000`. To disable the MCP server entirely (useful for testing), set `OMNIVOICE_MCP_DISABLE=1`.

All requests must include the `X-OmniVoice-Client-Id` header, which the server validates during request processing (see lines 7-10 in [`backend/mcp_server.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/mcp_server.py)). The client SDK automatically injects this header when using the `omv` package.

## Error Handling and Degraded States

If the voice registry fails to load, both endpoints return HTTP 500 errors with a diagnostic `note` field explaining the failure. When the MCP server is not started or transport is misconfigured, the endpoints respond with a clear "MCP transport could not be configured" message.

Integration tests in [`tests/test_mcp_mount.py`](https://github.com/debpalash/VoiceStudio/blob/main/tests/test_mcp_mount.py) assert the presence of `list_voices` and `list_personalities` in the MCP tool surface, ensuring these endpoints remain available across versions. For examples of degraded state handling, see [`tests/test_truthful_degraded_state.py`](https://github.com/debpalash/VoiceStudio/blob/main/tests/test_truthful_degraded_state.py).

## Summary

- **Primary endpoints**: Use `GET /mcp/list_voices` and `GET /mcp/list_personalities` to retrieve catalog data.
- **Authentication**: Include the `X-OmniVoice-Client-Id` header with all requests.
- **Implementation files**: Core logic resides in [`backend/mcp_server.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/mcp_server.py) (MCP server) and [`backend/api/routers/openai_compat.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/openai_compat.py) (OpenAI compatibility).
- **Data source**: The `VoiceRegistry` service in [`backend/services/plugin_sdk.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/services/plugin_sdk.py) provides the underlying voice and personality data.
- **Environment control**: Configure `OMNIVOICE_MCP_PORT` for custom ports or `OMNIVOICE_MCP_DISABLE=1` to disable the server.

## Frequently Asked Questions

### What authentication is required to list voices via the MCP server?

All requests to the list endpoints must include the `X-OmniVoice-Client-Id` header containing a valid client identifier. The server validates this header during request processing in [`backend/mcp_server.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/mcp_server.py). When using the Python SDK, this header is automatically managed by the `omv` client.

### Can I use the OpenAI compatibility layer instead of raw HTTP requests?

Yes. The [`backend/api/routers/openai_compat.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/api/routers/openai_compat.py) file implements OpenAI-compatible wrappers that expose `list_voices()` and `list_personalities()` methods. Import the `omv` module and use `omv.OpenAICompat()` to access these methods with familiar OpenAI SDK patterns.

### What happens if the MCP server is not running when I make a request?

If the server is disabled via `OMNIVOICE_MCP_DISABLE=1` or fails to initialize, the endpoints return a "MCP transport could not be configured" error message. The FastMCP instance loads lazily (around line 329 in [`backend/mcp_server.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/mcp_server.py)), so transport errors typically indicate configuration or dependency issues rather than runtime timeouts.

### How does the server handle corrupted or missing voice registry data?

If the `VoiceRegistry` service cannot load voice profiles or personality definitions, the endpoints return HTTP 500 status codes with a `note` field containing diagnostic information. The integration tests in [`tests/test_mcp_mount.py`](https://github.com/debpalash/VoiceStudio/blob/main/tests/test_mcp_mount.py) verify that these endpoints gracefully handle registry failures without crashing the server process.