Passer au contenu principal
Le MCP Gradium est un serveur Model Context Protocol 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

Ajoutez le serveur :
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 :
--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.
Il vous faut un compte Gradium Studio 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.
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. 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 :

Essayer

Une fois connecté, essayez ces prompts :

Outils

list_voices

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

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

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

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 ou Studio pour cela.