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

# Gradium MCP

> Choose voices and generate speech from your coding agent with the hosted Gradium MCP server

The Gradium MCP is a hosted [Model Context Protocol](https://modelcontextprotocol.io) server at `https://mcp.gradium.ai/mcp`. It lets a coding agent browse Gradium voices, generate speech and check your credits. You sign in with your Gradium Studio account, so you don't need an API key.

## Quick start

> [tab] Claude Code
>
> Add the server:
>
> ```bash theme={null}
> claude mcp add --transport http --scope user gradium https://mcp.gradium.ai/mcp
> ```
>
> Start a new Claude Code session, run `/mcp`, select `gradium` and choose **Authenticate**. Sign in with your Gradium Studio account in the browser, then ask Claude:
>
> ```text theme={null}
> How many Gradium credits do I have left?
> ```
>
> `--scope user` makes the server available in every project. Use `--scope local` for the current project only. If `gradium` doesn't appear in `/mcp`, the session started before you added the server. Start a new one and run `/mcp` again.

> [tab] Codex
>
> Add the server and sign in:
>
> ```bash theme={null}
> codex mcp add gradium --url https://mcp.gradium.ai/mcp
> codex mcp login gradium
> ```
>
> `codex mcp login` opens a browser window. Sign in with your Gradium Studio account and approve access, then run `codex mcp list` to check that `gradium` shows `OAuth`.

> [tab] Prompt
>
> Paste this into Claude Code or Codex. Your agent adds the server, asks you to sign in, picks a voice and reads the line aloud.
>
> ```text theme={null}
> Connect the Gradium MCP at https://mcp.gradium.ai/mcp, then find a friendly voice and read this aloud:
> "I’ve got a parcel for Mr. Sherlock Holmes at 221B Baker Street. Could you look it up? The tracking code is RF24, and the surname is spelled H-O-L-M-E-S."
> ```
>
> If the Gradium tools don't show up after you sign in, start a new session and paste the prompt again.

You need a [Gradium Studio](https://studio.gradium.ai/) account, and credits in your organization to generate speech. Browsing voices is free.

## Gradium skills for Claude Code

The Gradium plugin for Claude Code bundles the MCP server with four skills. A skill is a set of instructions that Claude loads when your request matches it. The Gradium skills tell Claude to recommend voices only from the metadata the server returns, to split long scripts, and never to retry a call that uses credits.

### Install the plugin

The plugin needs Claude Code 2.1.281 or later. It includes the MCP server, so you can skip `claude mcp add` if you install it.

```bash theme={null}
claude plugin marketplace add gradium-ai/skills
```

```bash theme={null}
claude plugin install gradium@gradium
```

Start a new Claude Code session, run `/mcp`, select `plugin:gradium:gradium` and choose **Authenticate**, then sign in and approve access in the browser. You can also sign in from your terminal with `claude mcp login plugin:gradium:gradium`.

If you already added `https://mcp.gradium.ai/mcp` with `claude mcp add`, Claude Code keeps your entry and doesn't connect the plugin's copy. The skills still work with your entry.

To update the plugin later, run `claude plugin marketplace update gradium`, then `claude plugin update gradium@gradium`, and start a new session.

### What each skill does

Claude picks the right skill from your request. You can also run a skill directly with its command.

| Skill | Command | What it does |
| - | - | - |
| Setup | `/gradium:setup` | Checks the connection with one free `get_credits` call, lists the tools the server exposes, and explains sign-in, membership and organization errors. |
| Credits | `/gradium:credits` | Reports the balance, plan and rollover date for each organization, and asks which organization to use when you belong to more than one. |
| Voice selection | `/gradium:voice-casting` | Turns your brief into `list_voices` filters, compares each voice's description and tags with the brief, and returns two to four voices with their exact IDs and the metadata that supports each pick. It generates auditions only when you ask. |
| Speech generation | `/gradium:speech-generation` | Generates a WAV, checks that it decodes, plays it on macOS unless you ask for the file only, and copies it from Claude Code's temporary folder to your requested location. For long text, it splits the script into parts of about 1,200 characters at sentence boundaries. For dialogue, it keeps one voice per speaker. It can join the parts into one file with `ffmpeg`. |

The plugin pre-approves the free tools (`get_credits`, `list_voices` and `get_voice`), so Claude doesn't ask for permission before checking credits or browsing voices. Speech generation uses organization credits and follows Claude Code's approval settings.

## Codex

If your session cannot save MCP audio, start a new session with `codex --enable code_mode` on a CLI version that supports it.

To install the Gradium plugin for Codex instead, which includes the server and four skills for setup, credits, voice selection and speech generation:

```bash theme={null}
codex plugin marketplace add gradium-ai/skills
codex plugin add gradium@gradium
```

## Try it

Once you're signed in, try these prompts:

```text theme={null}
Find me a calm French voice to narrate an audiobook, with voice IDs.
```

```text theme={null}
Read "Votre rendez-vous est le mardi 1er décembre à 14 h 30, au 12 bis rue de la Paix." aloud with that voice and save it as ./audio/rendez-vous.wav
```

```text theme={null}
Show me the three best-ranked English voices for customer support.
```

```text theme={null}
List my organization's custom voices.
```

## Tools

| Tool | What it does | Cost |
| - | - | - |
| `list_voices` | Lists catalog voices, or your organization's custom voices, with their description, tags and rank. | Free |
| `get_voice` | Returns one voice's details, such as its accent (locale), gender, age, description and tags. | Free |
| `generate_speech` | Turns text into a WAV file with the voice you choose. | 1 credit per character |
| `get_credits` | Shows the balance, plan, billing period and rollover date for each of your organizations. | Free |

### list\_voices

| Parameter | Description |
| - | - |
| `source` | `catalog` (default) for Gradium voices, or `organization` for your organization's custom voices. |
| `language` | Two-letter language code, such as `fr`. Matches every accent of that language. |
| `locale` | A specific locale, such as `fr-fr` or `en-au`. |
| `gender` | Exact match, case-insensitive. |
| `use_case` | Exact match on a use-case tag, case-insensitive, such as `customer service`. |
| `search` | Substring of a voice name or ID. It doesn't search descriptions. |
| `limit` | Number of voices per page, from 1 to 50. Defaults to 20. |
| `skip` | Offset for the next page. Pass the `next_skip` value from the previous response with the same filters. |
| `org_uid` | The organization to use. Leave it out if you belong to one organization. See [Organizations](#organizations). |

The response contains the `org_uid` it used, a `voices` list and `next_skip`, which is `null` when there are no more results. Each voice includes `voice_id`, `name`, `description`, `language`, `locale`, `gender`, `age`, `translations`, `tags`, `is_catalog`, `rank` and `is_pending`.

### get\_voice

Takes a `voice_id` and an optional `org_uid`, and returns the same fields as `list_voices` for that voice, plus the `org_uid` it used.

### generate\_speech

| Parameter | Description |
| - | - |
| `text` | The text to speak, from 1 to 9,000 characters. Above about 2,000 characters the audio can pass the size cap, so split long text. See [Long scripts](#long-scripts). |
| `voice_id` | A voice ID from `list_voices` or `get_voice`. Leave it out to use the default voice. |
| `org_uid` | The organization to bill. Leave it out if you belong to one organization. See [Organizations](#organizations). |

The result holds the WAV audio, plus the `org_uid` and `org_name` it used.

### get\_credits

Takes no parameters. Returns two lists. `organizations` holds every organization you can use, with its `org_uid` and `org_name`. `orgs` holds the credit balance of each organization that has one, with its `org_uid`, `org_name`, `remaining_credits`, `allocated_credits`, `billing_period`, `next_rollover_date` and `plan_name`.

## Choose a voice

Every catalog voice has a `rank`, and `list_voices` returns the lowest rank first. Below 1 is a [flagship voice](https://docs.gradium.ai/guides/voices/flagship-voices.md). In English, French, German, Spanish and Portuguese, the top result is one. A rank of 1 is a recommended voice, and above 1 is the rest of the catalog. Unranked catalog voices have a `null` rank and come after the ranked ones. Custom voices also have a `null` rank, and `source: organization` lists them newest first.

Skip voices with `is_pending: true`. Gradium is still processing them, and `generate_speech` rejects them.

`list_voices` returns metadata, not audio samples. To compare voices by ear, ask your agent to read a short line with each one. Each audition uses credits.

## Organizations

If you belong to one Gradium organization, the tools use it automatically.

If you belong to more than one, the first call to `list_voices`, `get_voice` or `generate_speech` without an `org_uid` asks which organization to use. Asking uses no credits.

* Clients that support MCP forms, such as Claude Code, show a form titled "Which Gradium organization should I use?" with your organization names. If you cancel it, the tool returns `selection_cancelled`.
* Other clients get a result with `status: organization_selection_required` and the list of organizations. The agent shows you the names, asks you to choose, then calls the tool again with that `org_uid`.

To choose up front, pass an `org_uid`. `get_credits` lists every organization you can use under `organizations`. Agents reuse the organization you picked for the rest of the chat. When a client sends a chat ID, the server also remembers the choice for that chat for 30 days.

## Audio output

`generate_speech` returns 48 kHz, 16-bit mono WAV audio in the tool result. The tool tells agents to save the WAV and play it, unless you ask them not to. Tell your agent where to save the file, or say if you don't want playback. The speech generation skill checks that the file decodes before offering it. If your agent says it got no audio back, the credits are already spent. Check that your client supports audio in MCP results before you generate again. To replay, use the saved file.

The MCP returns WAV only. To get MP3, ask your agent to convert the file locally:

```bash theme={null}
ffmpeg -i speech.wav -codec:a libmp3lame -q:a 2 speech.mp3
```

### Long scripts

Each call returns at most 16 MiB of audio, about 2 minutes and 55 seconds of 48 kHz, 16-bit mono WAV. That's roughly 2,000 characters of text or more, depending on the voice and speaking rate. Split longer scripts into parts below that size and generate them one by one. The [speech generation skill](#gradium-skills-for-claude-code) does this for you, in parts of about 1,200 characters. If a call returns more audio than that, it fails with `Generated audio is too large for MCP. Use shorter text.` A call that runs longer than 120 seconds fails with `Speech generation timed out.`

## Credits

`generate_speech` uses 1 credit per character of text, the same rate as the [text-to-speech API](https://docs.gradium.ai/guides/credits.md). `list_voices`, `get_voice` and `get_credits` are free.

The `generate_speech` tool description tells agents not to retry a failed call automatically.

## Errors

| Message | What to do |
| - | - |
| `Authentication required` | Your sign-in expired or was revoked. Sign in again with `/mcp` in Claude Code, or `codex mcp login gradium` in Codex. |
| `Sign in to Gradium Studio first.` | The account you signed in with has no active Gradium Studio user. Sign in to [Studio](https://studio.gradium.ai/) once, then sign in to the MCP again. |
| `No active membership for this organization.` | The `org_uid` isn't one of your organizations, or your account has none. Call `get_credits` and use an `org_uid` from `organizations`. |
| `Invalid organization selection.` | The organization chosen in the form isn't one of yours. Run the call again and pick an organization from the list. |
| `Unable to read or save this chat's organization. Try again later.` | The server couldn't store your organization choice. Try again, or pass `org_uid` directly. |
| `Voice not found in this organization.` | The voice ID doesn't exist, or it's a custom voice from another organization. Use an ID from `list_voices`. |
| `Voice is still processing. Choose another voice.` | The voice has `is_pending: true`. Pick another voice or try later. |
| `Provide nonblank text to speak.` | The `text` was empty or only spaces. |
| `Speech generation failed (HTTP 402).` | The organization is out of credits. Check `get_credits`. |
| `Speech generation failed (HTTP <code>).` with another code | The speech request failed. Try again later. |
| `Generated audio is too large for MCP. Use shorter text.` | Split the text into shorter parts. See [Long scripts](#long-scripts). |
| `Speech generation timed out.` | Retry with shorter text. |
| `Speech generation failed on compute.` | Generation failed on Gradium's side. Try again later. |
| `Compute returned incomplete or invalid WAV audio.` | The audio didn't arrive complete. Try again. |
| `TTS is not enabled on this MCP server.` | Speech generation is turned off on this server. Browsing voices and checking credits still work. |

## Limits

The Gradium MCP covers text-to-speech and choosing voices. It doesn't include speech-to-text, voice design, voice cloning or voice settings such as speed. Use the [API](https://docs.gradium.ai/guides/introduction.md) or Studio for those.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.