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

# MCP

> Connect Supertone TTS to Claude, Cursor, Claude Code, VS Code, and Windsurf via the Model Context Protocol — install, tools, and troubleshooting.

Integrate Supertone TTS with Claude, Cursor, and other MCP-compatible clients. The Supertone MCP server exposes the Text-to-Speech API as a set of composable [Model Context Protocol](https://modelcontextprotocol.io) tools, so an AI agent can discover voices, preview samples, estimate cost, clone voices, and synthesize speech — and chain those steps into multi-step workflows on its own.

Source: [supertone-inc/supertone-mcp](https://github.com/supertone-inc/supertone-mcp).

## What you can do

* **Synthesize speech** with control over voice, language, speed, pitch, and emotion style.
* **Discover voices** by language, gender, age, use case, or style — and preview samples before committing.
* **Clone and manage** custom voices from a local audio file.
* **Track usage** — check credit balance and usage history.
* **Stitch audio** — merge multiple clips into one file, with optional silence gaps or crossfades.

## Prerequisites

* [`uv`](https://docs.astral.sh/uv/) installed (provides `uvx`), or Python with `pip`.
* A Supertone API key from the [Developer Console](https://console.supertoneapi.com).

## Install

Every client runs the same server — `uvx supertone-mcp` — with your API key passed as an environment variable. Pick your client below.

<Tabs>
  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project), then fill in your API key:

    ```json theme={"dark"}
    {
      "mcpServers": {
        "supertone-tts": {
          "command": "uvx",
          "args": ["supertone-mcp"],
          "env": { "SUPERTONE_API_KEY": "your-api-key-here" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add the server to `claude_desktop_config.json`, then restart Claude Desktop:

    ```json theme={"dark"}
    {
      "mcpServers": {
        "supertone-tts": {
          "command": "uvx",
          "args": ["supertone-mcp"],
          "env": { "SUPERTONE_API_KEY": "your-api-key-here" }
        }
      }
    }
    ```

    Config file location:

    | OS      | Path                                                              |
    | ------- | ----------------------------------------------------------------- |
    | macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
    | Windows | `%APPDATA%\Claude\claude_desktop_config.json`                     |
  </Tab>

  <Tab title="Claude Code">
    One command from your terminal:

    ```bash theme={"dark"}
    claude mcp add supertone-tts -e SUPERTONE_API_KEY=your-api-key-here -- uvx supertone-mcp
    ```

    Add `-s user` to make it available across all your projects.
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json` in your workspace (note the top-level `servers` key):

    ```json theme={"dark"}
    {
      "servers": {
        "supertone-tts": {
          "command": "uvx",
          "args": ["supertone-mcp"],
          "env": { "SUPERTONE_API_KEY": "your-api-key-here" }
        }
      }
    }
    ```

    Then enable the server from the MCP view and use it in Copilot Chat's **Agent** mode.
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={"dark"}
    {
      "mcpServers": {
        "supertone-tts": {
          "command": "uvx",
          "args": ["supertone-mcp"],
          "env": { "SUPERTONE_API_KEY": "your-api-key-here" }
        }
      }
    }
    ```

    Reload the server list in Windsurf's Cascade panel.
  </Tab>
</Tabs>

## Environment variables

| Variable                 | Required | Default                   | Purpose                                 |
| ------------------------ | -------- | ------------------------- | --------------------------------------- |
| `SUPERTONE_API_KEY`      | Yes      | —                         | Authentication                          |
| `SUPERTONE_MCP_VOICE_ID` | No       | Aiden (multilingual)      | Default `voice_id` for `text_to_speech` |
| `SUPERTONE_OUTPUT_DIR`   | No       | `~/supertone-tts-output/` | Where generated audio files are saved   |

## Tools

The server exposes its capabilities as composable building blocks the agent can chain.

<AccordionGroup>
  <Accordion title="Speech synthesis">
    | Tool               | Description                                                                      |
    | ------------------ | -------------------------------------------------------------------------------- |
    | `text_to_speech`   | Generate audio with control over speed, pitch, emotion style, and output format. |
    | `predict_duration` | Estimate synthesis duration and credit cost before generating.                   |
  </Accordion>

  <Accordion title="Voice discovery">
    | Tool            | Description                                                        |
    | --------------- | ------------------------------------------------------------------ |
    | `search_voice`  | Filter preset voices by language, gender, age, use case, or style. |
    | `get_voice`     | Retrieve full details for a voice.                                 |
    | `preview_voice` | Fetch sample audio URLs to evaluate a voice.                       |
  </Accordion>

  <Accordion title="Voice cloning">
    | Tool                  | Description                                          |
    | --------------------- | ---------------------------------------------------- |
    | `clone_voice`         | Create a cloned voice from a local WAV/MP3 (≤ 3 MB). |
    | `search_custom_voice` | List and filter your cloned voices.                  |
    | `get_custom_voice`    | Fetch details for a cloned voice.                    |
    | `edit_custom_voice`   | Update a cloned voice's name or description.         |
    | `delete_custom_voice` | Permanently remove a cloned voice (irreversible).    |
  </Accordion>

  <Accordion title="Usage & credits">
    | Tool                 | Description                         |
    | -------------------- | ----------------------------------- |
    | `get_credit_balance` | Check remaining credits.            |
    | `get_usage_history`  | View usage over a time window.      |
    | `get_voice_usage`    | Usage metrics for a specific voice. |
  </Accordion>

  <Accordion title="Audio editing">
    | Tool                | Description                                                                                                                                                                                  |
    | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `merge_audio_files` | Merge two or more local audio files into one — plain concatenation, silence gaps (`gap_ms`), or crossfade blending (`crossfade_ms`). Useful for stitching multiple `text_to_speech` outputs. |
  </Accordion>
</AccordionGroup>

### Key `text_to_speech` parameters

* `text` (required), `voice_id`, `language`, `output_format` (`mp3` / `wav`)
* `model` — e.g. `sona_speech_2_flash`, `sona_speech_1`
* `speed` (0.5–2.0), `pitch_shift` (−24 to +24 semitones), `style`
* `output_mode` (`files` / `resources` / `both`), `autoplay` (default `false`), `streaming` (`sona_speech_1` only)

These are per-call parameters, so the agent controls output mode, autoplay, and model on each invocation.

### Key `merge_audio_files` parameters

* `input_paths` (required) — two or more local audio file paths, in order. (A single path is returned unchanged.)
* `gap_ms` — silence inserted between clips, in milliseconds.
* `crossfade_ms` — crossfade blend between clips, in milliseconds. **Mutually exclusive with `gap_ms`.**
* `output_format` — override the output format. By default it's auto-detected: all inputs sharing an extension → that extension; mixed → `mp3`. Differing sample rates or channel counts are normalized automatically before merging.

ffmpeg is bundled via `imageio-ffmpeg`, so merging works out of the box with `uvx supertone-mcp` — no system ffmpeg install required.

## Example workflows

<CardGroup cols={1}>
  <Card title="Discover → preview → estimate → synthesize" icon="wand-magic-sparkles">
    *"Find a calm Korean female voice, let me hear a sample, check the cost, then make this announcement as mp3."*

    Chains `search_voice()` → `preview_voice()` → `predict_duration()` + `get_credit_balance()` → `text_to_speech()`.
  </Card>

  <Card title="Clone and use immediately" icon="clone">
    *"Create a cloned voice from \~/recordings/sample.wav named MyVoice, then read this greeting with it and play it."*

    Chains `clone_voice()` → `get_custom_voice()` → `text_to_speech(autoplay=true)`.
  </Card>

  <Card title="Narrate a script and stitch it together" icon="layer-group">
    *"Generate each paragraph of this script, then merge them into one mp3 with a short pause between each."*

    Chains `text_to_speech()` per segment → `merge_audio_files(gap_ms=...)`.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The client doesn't list the Supertone tools">
    Make sure the config file is valid JSON and the client was fully restarted. Most clients only load MCP servers at startup.
  </Accordion>

  <Accordion title="uvx: command not found">
    Install `uv` (which provides `uvx`): see [the uv install guide](https://docs.astral.sh/uv/getting-started/installation/). Alternatively `pip install supertone-mcp` and set the `command` to `supertone-mcp`.
  </Accordion>

  <Accordion title="Authentication errors">
    Confirm `SUPERTONE_API_KEY` is set in the server's `env` block (not just your shell) and is valid. Get a key from the [Developer Console](https://console.supertoneapi.com).
  </Accordion>

  <Accordion title="Where did my audio go?">
    With `output_mode: files`, audio is written to `SUPERTONE_OUTPUT_DIR` (default `~/supertone-tts-output/`). Set `autoplay: true` to also play it immediately.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="CLI" icon="terminal" href="/en/docs/developer-tools/cli">
    The same capabilities from your terminal and scripts.
  </Card>

  <Card title="Custom voices" icon="clone" href="/en/docs/core-concepts/custom-voices">
    How voice cloning works on Supertone.
  </Card>
</CardGroup>