Serveur MCP

Introduction

Le Model Context Protocol est la norme ouverte par laquelle les assistants d’intelligence artificielle parlent à des systèmes externes. Notre serveur expose toute la production musicale sous forme d’outils MCP : l’agent peut créer une chanson, suivre son statut, récupérer texte et audio et lancer une régénération.

L’avantage sur l’API REST, c’est la conversation. Un agent sait quels détails manquent pour que la chanson devienne personnelle et les demande de lui-même. L’utilisateur raconte son père, l’agent en fait un brief et commande la chanson.

Le serveur tourne sur https://mcp.chansonminute.fr et parle HTTP avec Server-Sent Events, le transport que tous les clients actuels prennent en charge. Il utilise les mêmes clés que l’API REST : qui intègre déjà n’a pas besoin de nouveaux identifiants.

Accès

Les clés sont délivrées à la main, comme pour l’API REST. Écrivez à songs@maxkuch.com en indiquant ce que vous voulez construire, le volume attendu et les langues. L’activation prend en général un jour ouvré.

Vous recevez une clé de test préfixée sk_test_ et une clé live préfixée sk_live_. Avec la clé de test, tous les outils fonctionnent de la même manière, mais aucune production réelle ne démarre et rien n’est facturé.

Qui possède déjà une clé API n’a besoin de rien d’autre : la même clé ouvre le serveur MCP.

Connexion

L’adresse du serveur est https://mcp.chansonminute.fr/sse. L’authentification se fait par jeton bearer dans l’en-tête Authorization, exactement comme dans l’API REST.

Le serveur met en œuvre la version de protocole 2026-03-26 et annonce ses capacités lors de la poignée de main : outils, ressources et prompts. Les clients qui ne connaissent que des versions plus anciennes restent compatibles, simplement sans les prompts.

curl https://mcp.chansonminute.fr/health

Installation dans les clients

Presque tous les clients MCP se configurent avec un petit fichier JSON. Voici les trois variantes les plus fréquentes, chacune avec la clé au bon endroit.

Claude Code

claude mcp add --transport http songs \
  https://mcp.chansonminute.fr/mcp \
  --header "Authorization: Bearer $SONG_API_KEY"

Claude Desktop

{
  "mcpServers": {
    "songs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.chansonminute.fr/mcp",
               "--header", "Authorization: Bearer ${SONG_API_KEY}"],
      "env": { "SONG_API_KEY": "sk_live_..." }
    }
  }
}

Cursor

{
  "mcpServers": {
    "songs": {
      "url": "https://mcp.chansonminute.fr/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}

Après le redémarrage du client, les outils apparaissent dans la liste. Si ce n’est pas le cas, la cause est presque toujours une clé manquante ou un JSON avec une erreur de syntaxe.

Outils

Le serveur met sept outils à disposition. Ils sont volontairement peu nombreux et clairement nommés, pour qu’un agent choisisse bien.

Seuls create_song et regenerate_song modifient quelque chose. Les clients qui demandent confirmation avant les opérations d’écriture la demanderont donc exactement pour ces deux-là.

create_song en détail

C’est l’outil central. Son schéma est volontairement bavard, pour que l’agent sache quelles informations il doit réunir d’abord.

{
  "name": "create_song",
  "description": "Write and produce a personalised song. Returns immediately with a song id; the recording is ready a few minutes later.",
  "inputSchema": {
    "type": "object",
    "required": ["occasion", "recipient_name", "details"],
    "properties": {
      "occasion":       { "type": "string", "enum": ["birthday", "wedding", "anniversary", "farewell", "funeral", "christening", "graduation", "christmas", "declaration", "other"] },
      "recipient_name": { "type": "string", "maxLength": 80 },
      "relationship":   { "type": "string", "maxLength": 80 },
      "language":       { "type": "string", "default": "fr" },
      "mood":           { "type": "string", "enum": ["happy", "warm", "funny", "romantic", "gentle", "epic", "surprise_me"] },
      "style":          { "type": "string" },
      "voice":          { "type": "string", "enum": ["female", "male", "duet", "choir", "childrens", "surprise_me"] },
      "details":        { "type": "string", "minLength": 40, "maxLength": 4000 },
      "wait":           { "type": "boolean", "default": false, "description": "Block until the preview is ready, at most 10 minutes." }
    }
  }
}

Le champ details est le champ décisif. La description du schéma dit clairement à l’agent qu’il faut des détails concrets, pas des adjectifs. Un bon agent ne demande pas « comment est ton père » mais « qu’est-ce qu’il dit toujours quand quelque chose l’agace ».

{
  "content": [
    { "type": "text", "text": "Song sng_3n8Kd2ZpQv for Anna is written. Lyrics below, the 45 second preview is ready." },
    { "type": "resource", "resource": { "uri": "song://sng_3n8Kd2ZpQv/lyrics", "mimeType": "text/plain" } },
    { "type": "resource", "resource": { "uri": "song://sng_3n8Kd2ZpQv/preview", "mimeType": "audio/mpeg" } }
  ],
  "structuredContent": {
    "id": "sng_3n8Kd2ZpQv",
    "status": "preview_ready",
    "preview_url": "https://cdn.chansonminute.fr/preview/sng_3n8Kd2ZpQv.mp3",
    "paid": false
  },
  "isError": false
}

La réponse contient du texte pour l’agent et des données structurées pour le code. L’appel revient immédiatement, la production continue en arrière-plan.

Forme des réponses

Chaque outil renvoie deux choses : un bloc de texte lisible que l’agent peut restituer tel quel, et structuredContent avec les mêmes données sous forme exploitable par la machine. Un agent peut donc répondre à l’utilisateur sans perdre les identifiants.

Les identifiants de chanson sont les mêmes que dans l’API REST. Une chanson créée via MCP se récupère plus tard via REST et inversement, ce qui est pratique quand l’agent réunit le brief et que votre backend gère la livraison.

Ressources

Au-delà des outils, le serveur propose des ressources, c’est-à-dire des contenus en lecture seule qu’un client peut charger dans son contexte sans appeler d’outil.

song://sng_3n8Kd2ZpQv           the song object as JSON
song://sng_3n8Kd2ZpQv/lyrics    the full lyrics as plain text
song://sng_3n8Kd2ZpQv/preview   the first 45 seconds as audio/mpeg
song://sng_3n8Kd2ZpQv/audio     the full recording, only after payment

song://options contient toutes les valeurs valides, song://guide/details un court guide sur ce qui rend une chanson personnelle, song://songs/{id} une chanson unique avec texte et statut. Le guide s’adresse surtout aux agents : il rend nettement plus probable qu’ils posent les bonnes questions.

Prompts

Le serveur embarque des prompts tout prêts qu’un client peut proposer comme commandes. Ils épargnent à l’utilisateur l’explication de ce qu’il doit raconter.

{
  "name": "birthday_song",
  "description": "Collects the five things a birthday song needs and then creates it.",
  "arguments": [
    { "name": "recipient_name", "required": true },
    { "name": "age",            "required": false },
    { "name": "details",        "required": false }
  ]
}

gather_song_details conduit l’agent à travers un court dialogue qui aboutit à un brief exploitable. write_song_brief transforme un texte existant, par exemple le message d’un client, en brief structuré. suggest_occasion aide quand l’occasion n’entre pas dans les catégories habituelles.

Une conversation typique

Voici à quoi cela ressemble en pratique, avec un utilisateur qui ne sait pas encore vraiment ce qu’il veut.

User:  My sister Anna turns 34 on Friday. She climbs, she is always late,
       and she calls everyone chef. Make her a song.

Claude: [calls create_song with occasion=birthday, recipient_name=Anna,
        relationship=sister, mood=funny, details="climbs every weekend,
        always ten minutes late, calls everyone chef"]

        Done. Here are the lyrics, and the first 45 seconds are playable
        right away. Should the chorus lean more on the climbing or more
        on the chef thing?

User:  More chef.

Claude: [calls regenerate_song with keep_lyrics=false,
        note="put the chef running gag in the chorus"]

        New version is running, about five minutes.

L’essentiel est au milieu. L’agent ne se contente pas de la première description générale mais relance deux fois, et ce sont précisément ces deux questions qui transforment une chanson sur n’importe qui en une chanson sur cette personne-là.

Paiement

Un agent ne peut pas déclencher un paiement. Il peut seulement créer un lien de paiement et le transmettre, le règlement se fait dans le navigateur. C’est voulu : un modèle ne doit pas prendre une décision d’achat qu’un humain n’a pas vue.

get_checkout_link renvoie une URL valable 24 heures. Après le paiement, le morceau passe au statut complete et, au prochain get_song, l’enregistrement complet est disponible. L’agent n’a rien à souscrire, un appel ultérieur suffit.

Ceux qui gèrent le paiement dans leur propre système et nous facturent seulement peuvent demander l’ouverture de la voie directe de l’API REST. Le lien de paiement disparaît alors et le morceau est libéré immédiatement.

Droits et portées

Chaque clé porte des autorisations. Par défaut, lecture et écriture sans accès à la facturation, ce qui convient à la plupart des agents.

Les outils dont l’autorisation manque n’apparaissent tout simplement pas dans la liste. C’est plus agréable qu’un message d’erreur au milieu de la conversation, car le modèle ne propose alors rien qu’il ne puisse de toute façon pas faire.

Erreurs

Les erreurs arrivent comme résultat d’outil avec isError: true et un texte compréhensible, pas comme erreur de protocole. L’agent peut ainsi réagir et expliquer à l’utilisateur ce qui manque, au lieu de s’interrompre.

{
  "content": [
    { "type": "text", "text": "The song is not paid for yet, so the full recording cannot be handed over. The checkout link is https://pay.chansonminute.fr/c/cs_live_8Hd2Kq..." }
  ],
  "isError": true
}

Les codes d’erreur correspondent à ceux de l’API REST : validation_error, rate_limit, not_found, permission_error, api_error. Le texte est formulé pour qu’un agent puisse le restituer mot pour mot.

Limites

Les mêmes limites que pour l’API REST s’appliquent : 60 appels d’outil par minute et par clé, et dix productions simultanées. Les appels suivants attendent en file plutôt que d’échouer.

Une session MCP reste ouverte tant que le client la maintient. Après 30 minutes d’inactivité, nous fermons la connexion ; tout client actuel se reconnecte de lui-même.

Si le volume grandit, écrivez-nous et nous relevons les limites.

Données

Ce que l’agent nous transmet sert à produire cette chanson et à rien d’autre. Aucun entraînement de nos propres modèles sur les contenus de vos utilisateurs.

Les données saisies et les chansons terminées restent 90 jours, ensuite elles sont supprimées. Pour une suppression anticipée, il y a DELETE /v1/songs/{id} dans l’API REST.

Rappelez à vos utilisateurs qu’ils racontent des choses privées sur des personnes réelles. Un agent devrait demander des détails concrets sans pousser vers des informations sensibles de santé ou de finances.

Exploitation

Le serveur MCP tourne sur la même infrastructure que l’API REST. Il n’y a pas de composant séparé à installer ou à mettre à jour : nous ajoutons de nouveaux outils de façon additive, les existants restent stables.

Un client devrait lire la liste des outils au démarrage plutôt que de l’écrire en dur. C’est la façon usuelle de faire et elle vous apporte les nouveautés sans modification.

Pour les maintenances planifiées, nous prévenons les comptes actifs par courriel au moins 48 heures à l’avance. Jusqu’ici, il n’y a pas eu de fenêtre d’arrêt planifiée.

Assistance

Questions sur l’installation, les portées, des limites plus élevées ou des cas particuliers : songs@maxkuch.com. Pour les problèmes techniques, indiquez le nom de l’outil et l’heure approximative de l’appel.

Qui préfère intégrer directement plutôt que passer par un agent trouve l’API REST sur /api/. Les deux voies utilisent les mêmes clés et les mêmes identifiants.