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

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

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

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 that exposes list_voices() and list_personalities() methods directly. This allows tools designed for the OpenAI API to interact with VoiceStudio without modification.

# 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, providing a seamless interface for existing OpenAI integrations.

Direct FastMCP Client Access

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

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

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 (MCP server) and backend/api/routers/openai_compat.py (OpenAI compatibility).
• Data source: The VoiceRegistry service in 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. 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 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), 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 verify that these endpoints gracefully handle registry failures without crashing the server process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}