Skip to main content
The Gradium MCP is a hosted Model Context Protocol 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

Add the server:
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:
--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.
You need a Gradium Studio 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.
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. 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:

Try it

Once you’re signed in, try these prompts:

Tools

list_voices

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

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

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 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. list_voices, get_voice and get_credits are free. The generate_speech tool description tells agents not to retry a failed call automatically.

Errors

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 or Studio for those.