VoiceStudioVoiceStudio
Esc

Guides

AI Agents & MCP

Give AI coding assistants and workflows direct access to VoiceStudio using the Model Context Protocol.

VoiceStudio includes a built-in Model Context Protocol (MCP) server that exposes speech synthesis, voice cloning, transcription, and design capabilities directly to AI agents. It is mounted on the running backend at /mcp, meaning there is no extra server to start once VoiceStudio is open. This integration enables tools like Claude Code, Cursor, Codex CLI, and other agent frameworks to speak, listen, and manage voices locally.

Connecting to the MCP Server#

Streamable HTTP (Modern Clients)#

Point your MCP client directly at the mounted HTTP endpoint:

http://localhost:3900/mcp/

Be sure to keep the trailing slash, as /mcp/ works across all VoiceStudio versions.

You can download ready-made client configuration files (such as .mcp.json for Claude Code or .cursor/mcp.json for Cursor) from the desktop app under the Integrations tab.

For the Codex CLI, the configuration uses Streamable HTTP with static headers:

TOML
[mcp_servers.voicestudio]
url = "http://127.0.0.1:3900/mcp/"
http_headers = { "X-OmniVoice-Client-Id" = "codex-cli" }

For Hermes Agent, add the server to your ~/.hermes/config.yaml file:

YAML
mcp_servers:
  voicestudio:
    url: "http://127.0.0.1:3900/mcp/"
    headers:
      X-OmniVoice-Client-Id: "hermes"

Accessing Over a Local Network

If your agent runs on a different machine on your local network:

  1. Turn on Settings → Sharing → Local network in VoiceStudio.
  2. Use the displayed LAN IP and share port, adding the /mcp/ suffix.
  3. Pass the shown access PIN as the X-OmniVoice-Pin header.
TOML
[mcp_servers.voicestudio]
url = "http://192.168.1.50:3901/mcp/"
http_headers = { "X-OmniVoice-Pin" = "123456", "X-OmniVoice-Client-Id" = "codex-cli" }

Only use HTTP network sharing on a trusted local area network. HTTP transmits the PIN and voice traffic in clear text. For untrusted networks, use an encrypted tunnel such as Tailscale.

DNS Rebinding Guard

The MCP SDK rejects non-localhost Host headers by default. If running inside Docker, using a hostname, or connecting via a manually bound server, set the OMNIVOICE_MCP_ALLOWED_HOSTS environment variable to a comma-separated list of permitted host patterns (e.g., host.containers.internal:*,192.168.1.50:*).

stdio (Legacy/Standard Clients)#

For clients that only support stdio transport, use the bundled shim to proxy stdio traffic to the mounted HTTP endpoint. Add the following to your client's MCP configuration:

JSON
{
  "mcpServers": {
    "omnivoice": {
      "command": "python",
      "args": ["-m", "backend.mcp_shim"],
      "cwd": "/path/to/VoiceStudio",
      "env": { "OMNIVOICE_PORT": "3900", "OMNIVOICE_CLIENT_ID": "claude-code" }
    }
  }
}

If your backend is hosted elsewhere, configure OMNIVOICE_HOST and OMNIVOICE_PORT, or use OMNIVOICE_URL for full secure paths (e.g., https://gpu-box/voicestudio). Pass OMNIVOICE_API_KEY when backend authentication is required. The shim requires a local VoiceStudio source checkout to run.

Output Modes and Security Boundaries#

LLM agents incur significant token costs when transferring raw audio data inside their context window. VoiceStudio provides environment variables to configure how files are transferred and where they are saved.

Variable Values Effect
OMNIVOICE_MCP_OUTPUT_MODE resources (default) · files · both resources returns a base64-encoded WAV inline. files returns a URL to the rendered audio, and writes a file to the configured base path. both returns both the inline base64 and the file/URL.
OMNIVOICE_MCP_TIMEOUT_S seconds (default: dynamically calculated) Configures a fixed timeout for MCP tools. Unset, the server calculates timeouts dynamically based on backend task queue limits.
OMNIVOICE_MCP_BASE_PATH a directory The security boundary. File-path arguments are refused unless this is set. Relative paths resolve against it, and absolute paths must lie within it.

Audio Formats#

WAV is the default output format. In files or both mode, you can specify format="ogg" or format="opus" to retrieve Opus-in-Ogg compressed audio. This requires ffmpeg to be installed on the backend.

Shared Directories#

If your agent and VoiceStudio run in different containers or filesystem namespaces, mount a single shared directory at the exact same path in both environments, and set OMNIVOICE_MCP_BASE_PATH to this directory. Setting OMNIVOICE_MCP_OUTPUT_MODE=files keeps audio out of the LLM context while providing paths the agent can immediately play or process.

Exposed Tools and Resources#

The MCP server exposes the following tools to connected agents:

Voice Generation & Synthesis#

  • generate_speech: Synthesizes text to speech.
    • text: The input text.
    • language: ISO language code or 'Auto' (omit to use the voice profile's saved language).
    • profile_id: Specific voice profile ID. If omitted, the agent's bound voice is used.
    • instruct: Style instructions (e.g., 'whisper', 'excited').
    • speed: Speed multiplier (0.5–2.0, default 1.0).
    • steps: Diffusion steps (8 for fast, 16 for balanced, 32 for quality).
    • format: 'wav' (default), 'ogg', or 'opus'.

Voice Cloning & Design#

  • clone_voice: Creates a voice profile from reference audio.
    • name: Friendly name for the clone.
    • ref_audio_base64 or ref_audio_path: The reference audio (5–30 seconds of clean speech). Pass exactly one.
    • ref_text: Optional transcript of the reference audio.
    • language: Language of reference audio.
  • describe_voice: Parses a text description (e.g., "elderly man with a deep voice and a british accent") to show how it maps to voice-design attributes. Saves nothing.
  • design_voice: Creates a new stable voice profile from a text description.

Transcription & Utilities#

  • transcribe: Converts audio to text.
    • audio_base64 or audio_path: The audio source. Pass exactly one.
    • language: Optional language hint.
  • list_voices: Returns a JSON list of saved voice profiles.
  • list_personalities: Lists built-in voice presets (e.g., News Anchor, Casual).
  • list_languages: Returns supported languages.
  • check_health: Returns system status and the active GPU device.

Resources#

Agents can read these system resources like files:

  • voice://{profile_id}: Retrieves the JSON metadata for a specific voice.
  • history://recent: Retrieves a JSON list of the 20 most recent generation items.

Per-Agent Voices#

You can assign a unique voice to each agent client ID, so that your IDE terminal assistant sounds different from your coding workspace assistant.

The voice resolution precedence on every generate_speech call is:

  1. An explicit profile_id argument passed by the agent.
  2. The agent's configured client ID binding.
  3. VoiceStudio's system-wide default voice.

Manage these bindings through the REST API using loopback calls:

Bash
# List all current agent bindings
curl http://localhost:3900/api/mcp/bindings

# Bind a client ID to a specific voice profile
curl -X PUT http://localhost:3900/api/mcp/bindings \
  -H 'Content-Type: application/json' \
  -d '{"client_id":"claude-code","label":"Claude Code","profile_id":"<voice-profile-id>"}'

# Remove a binding
curl -X DELETE http://localhost:3900/api/mcp/bindings/claude-code

For more details on voice verification and cloning, see the Voice Cloning & Gallery guide.

Disabling the MCP Server#

To completely skip mounting the /mcp routes and disable the MCP server, start your VoiceStudio backend with this environment variable:

Bash
OMNIVOICE_MCP_DISABLE=1
Documentation written with Docup