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

# MCP Gradium

> Choisissez des voix et générez de la parole depuis votre agent de code avec le serveur MCP hébergé de Gradium

Le MCP Gradium est un serveur [Model Context Protocol](https://modelcontextprotocol.io) hébergé à l'adresse `https://mcp.gradium.ai/mcp`. Il permet à un agent de code de parcourir les voix Gradium, de générer de la parole et de vérifier vos crédits. Vous vous connectez avec votre compte Gradium Studio, sans clé API.

## Démarrage rapide

> [tab] Claude Code
>
> Ajoutez le serveur :
>
> ```bash theme={null}
> claude mcp add --transport http --scope user gradium https://mcp.gradium.ai/mcp
> ```
>
> Ouvrez une nouvelle session Claude Code, lancez `/mcp`, sélectionnez `gradium` et choisissez **Authenticate**. Connectez-vous avec votre compte Gradium Studio dans le navigateur, puis demandez à Claude :
>
> ```text theme={null}
> Combien de crédits Gradium me reste-t-il ?
> ```
>
> `--scope user` rend le serveur disponible dans tous vos projets. Utilisez `--scope local` pour le projet en cours uniquement. Si `gradium` n'apparaît pas dans `/mcp`, la session a démarré avant l'ajout du serveur. Ouvrez-en une nouvelle et relancez `/mcp`.

> [tab] Codex
>
> Ajoutez le serveur et connectez-vous :
>
> ```bash theme={null}
> codex mcp add gradium --url https://mcp.gradium.ai/mcp
> codex mcp login gradium
> ```
>
> `codex mcp login` ouvre une fenêtre du navigateur. Connectez-vous avec votre compte Gradium Studio et autorisez l'accès, puis lancez `codex mcp list` pour vérifier que `gradium` affiche `OAuth`.

> [tab] Prompt
>
> Collez ce prompt dans Claude Code ou Codex. Votre agent ajoute le serveur, vous demande de vous connecter, choisit une voix et lit la phrase à voix haute.
>
> ```text theme={null}
> Connecte le MCP Gradium à l'adresse https://mcp.gradium.ai/mcp, puis trouve une voix amicale et lis ceci à voix haute :
> « J'ai un colis pour M. Sherlock Holmes au 221B Baker Street. Pouvez-vous le retrouver ? Le numéro de suivi est RF24, et le nom s'écrit H-O-L-M-E-S. »
> ```
>
> Si les outils Gradium n'apparaissent pas après la connexion, ouvrez une nouvelle session et collez à nouveau le prompt.

Il vous faut un compte [Gradium Studio](https://studio.gradium.ai/) et des crédits dans votre organisation pour générer de la parole. Parcourir les voix est gratuit.

## Skills Gradium pour Claude Code

Le plugin Gradium pour Claude Code regroupe le serveur MCP et quatre skills. Un skill est un ensemble d'instructions que Claude charge quand votre demande y correspond. Les skills Gradium demandent à Claude de recommander des voix uniquement à partir des métadonnées renvoyées par le serveur, de découper les textes longs et de ne jamais relancer un appel qui consomme des crédits.

### Installer le plugin

Le plugin nécessite Claude Code 2.1.281 ou une version ultérieure. Il inclut le serveur MCP : si vous l'installez, la commande `claude mcp add` n'est pas nécessaire.

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

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

Ouvrez une nouvelle session Claude Code, lancez `/mcp`, sélectionnez `plugin:gradium:gradium` et choisissez **Authenticate**, puis connectez-vous et autorisez l'accès dans le navigateur. Vous pouvez aussi vous connecter depuis votre terminal avec `claude mcp login plugin:gradium:gradium`.

Si vous avez déjà ajouté `https://mcp.gradium.ai/mcp` avec `claude mcp add`, Claude Code conserve votre entrée et ne connecte pas celle du plugin. Les skills fonctionnent quand même avec votre entrée.

Pour mettre à jour le plugin, lancez `claude plugin marketplace update gradium`, puis `claude plugin update gradium@gradium`, et ouvrez une nouvelle session.

### Ce que fait chaque skill

Claude choisit le bon skill à partir de votre demande. Vous pouvez aussi lancer un skill directement avec sa commande.

| Skill | Commande | Ce qu'il fait |
| - | - | - |
| Configuration | `/gradium:setup` | Vérifie la connexion avec un appel gratuit à `get_credits`, liste les outils exposés par le serveur et explique les erreurs de connexion, d'appartenance et d'organisation. |
| Crédits | `/gradium:credits` | Indique le solde, l'offre et la date de renouvellement de chaque organisation, et demande quelle organisation utiliser si vous en avez plusieurs. |
| Choix de voix | `/gradium:voice-casting` | Transforme votre demande en filtres `list_voices`, compare la description et les tags de chaque voix avec votre demande, et renvoie deux à quatre voix avec leur identifiant exact et les métadonnées qui justifient chaque choix. Il ne génère d'essais audio que si vous le demandez. |
| Génération de parole | `/gradium:speech-generation` | Génère un fichier WAV, vérifie qu'il se décode, le lit sur macOS sauf si vous demandez seulement le fichier, et le copie du dossier temporaire de Claude Code vers l'emplacement demandé. Pour un texte long, il découpe le script en parties d'environ 1 200 caractères, aux limites de phrases. Pour un dialogue, il garde une voix par personnage. Il peut assembler les parties en un seul fichier avec `ffmpeg`. |

Le plugin préautorise les outils gratuits (`get_credits`, `list_voices` et `get_voice`) : Claude ne demande donc pas de permission avant de vérifier les crédits ou de parcourir les voix. La synthèse vocale utilise les crédits de votre organisation et suit les paramètres d'autorisation de Claude Code.

## Codex

Si votre session ne peut pas enregistrer l'audio du MCP, ouvrez une nouvelle session avec `codex --enable code_mode` dans une version de la CLI qui prend en charge cette option.

Pour installer plutôt le plugin Gradium pour Codex, qui inclut le serveur et quatre skills pour la configuration, les crédits, le choix des voix et la synthèse vocale :

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

## Essayer

Une fois connecté, essayez ces prompts :

```text theme={null}
Trouve-moi une voix française calme pour narrer un livre audio, avec les identifiants des voix.
```

```text theme={null}
Lis « Votre rendez-vous est le mardi 1er décembre à 14 h 30, au 12 bis rue de la Paix. » avec cette voix et enregistre le fichier dans ./audio/rendez-vous.wav
```

```text theme={null}
Montre-moi les trois voix anglaises les mieux classées pour le service client.
```

```text theme={null}
Liste les voix personnalisées de mon organisation.
```

## Outils

| Outil | Ce qu'il fait | Coût |
| - | - | - |
| `list_voices` | Liste les voix du catalogue, ou les voix personnalisées de votre organisation, avec leur description, leurs tags et leur rang. | Gratuit |
| `get_voice` | Renvoie les détails d'une voix, comme son accent (locale), son genre, son âge, sa description et ses tags. | Gratuit |
| `generate_speech` | Transforme un texte en fichier WAV avec la voix choisie. | 1 crédit par caractère |
| `get_credits` | Affiche le solde, l'offre, la période de facturation et la date de renouvellement de chacune de vos organisations. | Gratuit |

### list\_voices

| Paramètre | Description |
| - | - |
| `source` | `catalog` (par défaut) pour les voix Gradium, ou `organization` pour les voix personnalisées de votre organisation. |
| `language` | Code de langue à deux lettres, par exemple `fr`. Inclut tous les accents de cette langue. |
| `locale` | Une locale précise, par exemple `fr-fr` ou `en-au`. |
| `gender` | Correspondance exacte, sans tenir compte de la casse. |
| `use_case` | Correspondance exacte sur un tag de cas d'usage, sans tenir compte de la casse, par exemple `customer service`. |
| `search` | Partie du nom ou de l'identifiant d'une voix. Ne cherche pas dans les descriptions. |
| `limit` | Nombre de voix par page, de 1 à 50. 20 par défaut. |
| `skip` | Décalage pour la page suivante. Passez la valeur `next_skip` de la réponse précédente avec les mêmes filtres. |
| `org_uid` | L'organisation à utiliser. Inutile si vous n'appartenez qu'à une organisation. Voir [Organisations](#organisations). |

La réponse contient le `org_uid` utilisé, une liste `voices` et `next_skip`, qui vaut `null` lorsqu'il n'y a plus de résultats. Chaque voix contient `voice_id`, `name`, `description`, `language`, `locale`, `gender`, `age`, `translations`, `tags`, `is_catalog`, `rank` et `is_pending`.

### get\_voice

Prend un `voice_id` et un `org_uid` facultatif, et renvoie les mêmes champs que `list_voices` pour cette voix, ainsi que le `org_uid` utilisé.

### generate\_speech

| Paramètre | Description |
| - | - |
| `text` | Le texte à prononcer, de 1 à 9 000 caractères. Au-delà d'environ 2 000 caractères, l'audio peut dépasser la taille maximale : découpez les textes longs. Voir [Textes longs](#textes-longs). |
| `voice_id` | Un identifiant de voix issu de `list_voices` ou `get_voice`. Sans ce paramètre, l'outil utilise la voix par défaut. |
| `org_uid` | L'organisation à facturer. Inutile si vous n'appartenez qu'à une organisation. Voir [Organisations](#organisations). |

Le résultat contient l'audio WAV, ainsi que le `org_uid` et le `org_name` utilisés.

### get\_credits

Ne prend aucun paramètre. Renvoie deux listes. `organizations` contient toutes les organisations que vous pouvez utiliser, avec leur `org_uid` et leur `org_name`. `orgs` contient le solde de crédits de chaque organisation qui en a un, avec `org_uid`, `org_name`, `remaining_credits`, `allocated_credits`, `billing_period`, `next_rollover_date` et `plan_name`.

## Choisir une voix

Chaque voix du catalogue a un `rank`, et `list_voices` renvoie d'abord le rang le plus bas. Sous 1, c'est une [voix phare](https://docs.gradium.ai/fr/guides/voices/flagship-voices.md). En anglais, français, allemand, espagnol et portugais, le premier résultat en est une. Un rang de 1 indique une voix recommandée, et au-dessus de 1 commence le reste du catalogue. Les voix du catalogue sans classement ont un `rank` à `null` et viennent après les voix classées. Les voix personnalisées ont aussi un `rank` à `null`, et `source: organization` les liste de la plus récente à la plus ancienne.

Ignorez les voix avec `is_pending: true`. Gradium les traite encore, et `generate_speech` les refuse.

`list_voices` renvoie des métadonnées, pas des extraits audio. Pour comparer des voix à l'oreille, demandez à votre agent de lire une phrase courte avec chacune. Chaque essai consomme des crédits.

## Organisations

Si vous appartenez à une seule organisation Gradium, les outils l'utilisent automatiquement.

Si vous appartenez à plusieurs organisations, le premier appel à `list_voices`, `get_voice` ou `generate_speech` sans `org_uid` vous demande quelle organisation utiliser. Cette demande ne consomme aucun crédit.

* Les clients qui prennent en charge les formulaires MCP, comme Claude Code, affichent un formulaire intitulé « Which Gradium organization should I use? » avec le nom de vos organisations. Si vous l'annulez, l'outil renvoie `selection_cancelled`.
* Les autres clients reçoivent un résultat avec `status: organization_selection_required` et la liste des organisations. L'agent vous montre les noms, vous demande de choisir, puis rappelle l'outil avec cet `org_uid`.

Pour choisir dès le départ, passez un `org_uid`. `get_credits` liste toutes les organisations que vous pouvez utiliser dans `organizations`. Les agents réutilisent l'organisation choisie pendant le reste de la conversation. Quand un client envoie un identifiant de conversation, le serveur retient aussi ce choix pour cette conversation pendant 30 jours.

## Sortie audio

`generate_speech` renvoie un fichier WAV mono 16 bits à 48 kHz dans le résultat de l'outil. L'outil demande aux agents d'enregistrer le WAV et de le lire, sauf si vous leur demandez de ne pas le faire. Indiquez à votre agent où enregistrer le fichier, ou précisez si vous ne voulez pas l'écouter. Le skill de génération de parole vérifie que le fichier se décode avant de vous le proposer. Si votre agent indique qu'il n'a reçu aucun audio, les crédits sont déjà consommés. Vérifiez que votre client prend en charge l'audio dans les résultats MCP avant de relancer la synthèse. Pour réécouter l'audio, utilisez le fichier enregistré.

Le MCP renvoie uniquement du WAV. Pour obtenir un MP3, demandez à votre agent de convertir le fichier en local :

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

### Textes longs

Chaque appel renvoie au maximum 16 Mio d'audio, soit environ 2 minutes et 55 secondes de WAV mono 16 bits à 48 kHz. Cela correspond à environ 2 000 caractères de texte ou plus, selon la voix et le débit de parole. Découpez les textes plus longs en parties plus courtes et générez-les une par une. Le [skill de génération de parole](#skills-gradium-pour-claude-code) le fait pour vous, en parties d'environ 1 200 caractères. Si un appel produit plus d'audio que cela, il échoue avec `Generated audio is too large for MCP. Use shorter text.` Un appel qui dure plus de 120 secondes échoue avec `Speech generation timed out.`

## Crédits

`generate_speech` utilise 1 crédit par caractère de texte, le même tarif que l'[API de synthèse vocale](https://docs.gradium.ai/fr/guides/credits.md). `list_voices`, `get_voice` et `get_credits` sont gratuits.

La description de l'outil `generate_speech` demande aux agents de ne pas relancer automatiquement un appel qui a échoué.

## Erreurs

| Message | Que faire |
| - | - |
| `Authentication required` | Votre connexion a expiré ou a été révoquée. Reconnectez-vous avec `/mcp` dans Claude Code, ou `codex mcp login gradium` dans Codex. |
| `Sign in to Gradium Studio first.` | Le compte avec lequel vous vous êtes connecté n'a pas d'utilisateur Gradium Studio actif. Connectez-vous une fois à [Studio](https://studio.gradium.ai/), puis reconnectez-vous au MCP. |
| `No active membership for this organization.` | Le `org_uid` ne correspond à aucune de vos organisations, ou votre compte n'en a aucune. Appelez `get_credits` et utilisez un `org_uid` de `organizations`. |
| `Invalid organization selection.` | L'organisation choisie dans le formulaire ne fait pas partie des vôtres. Relancez l'appel et choisissez une organisation dans la liste. |
| `Unable to read or save this chat's organization. Try again later.` | Le serveur n'a pas pu enregistrer votre choix d'organisation. Réessayez, ou passez directement `org_uid`. |
| `Voice not found in this organization.` | L'identifiant de voix n'existe pas, ou il s'agit d'une voix personnalisée d'une autre organisation. Utilisez un identifiant issu de `list_voices`. |
| `Voice is still processing. Choose another voice.` | La voix a `is_pending: true`. Choisissez une autre voix ou réessayez plus tard. |
| `Provide nonblank text to speak.` | Le `text` était vide ou ne contenait que des espaces. |
| `Speech generation failed (HTTP 402).` | L'organisation n'a plus de crédits. Vérifiez avec `get_credits`. |
| `Speech generation failed (HTTP <code>).` avec un autre code | La requête de synthèse a échoué. Réessayez plus tard. |
| `Generated audio is too large for MCP. Use shorter text.` | Découpez le texte en parties plus courtes. Voir [Textes longs](#textes-longs). |
| `Speech generation timed out.` | Réessayez avec un texte plus court. |
| `Speech generation failed on compute.` | La génération a échoué côté Gradium. Réessayez plus tard. |
| `Compute returned incomplete or invalid WAV audio.` | L'audio n'est pas arrivé complet. Réessayez. |
| `TTS is not enabled on this MCP server.` | La synthèse vocale est désactivée sur ce serveur. Parcourir les voix et vérifier les crédits fonctionnent toujours. |

## Limites

Le MCP Gradium couvre la synthèse vocale et le choix des voix. Il n'inclut pas la transcription, le design de voix, le clonage de voix ni les réglages de voix comme la vitesse. Utilisez l'[API](https://docs.gradium.ai/fr/guides/introduction.md) ou Studio pour cela.


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