Utiliser le serveur MCP

Exemples concrets pour créer des interviews, inviter des participants et lire les transcripts depuis votre agent IA.

Une fois le serveur MCP branché dans votre client (voir le guide de configuration), votre agent IA dispose de huit outils pour piloter Raconte : quatre sur les interviews et quatre sur les invitations. Ce guide montre comment vous en servir au quotidien, avec des exemples de demandes formulées en langage naturel.

Pour la liste complète des paramètres de chaque outil, gardez la référence du serveur MCP sous la main.

Les huit outils en un coup d’œil

Côté interview :

list-interviews : parcourt les interviews de l’organisation, de la plus récente à la plus ancienne.
create-interview : crée une interview vocale IA (et sa première invitation).
update-interview : modifie une interview existante, ou l’archive.
get-interview : récupère une interview avec toutes ses invitations et leurs transcripts.

Côté invitation :

list-invitations : parcourt les invitations et leurs résumés, sur toute l’organisation ou dans une seule interview.
create-invitation : ajoute une ou plusieurs invitations à une interview existante.
update-invitation : modifie une invitation, l’annule ou l’archive.
get-invitation : récupère une invitation avec son transcript complet.

Comment formuler vos demandes

Vous parlez à votre agent en langage naturel ; c’est lui qui choisit l’outil et remplit les paramètres. Les exemples ci-dessous donnent une formulation type et montrent ce qui se passe derrière.

Exemple 1, créer une interview et l’envoyer

« Crée une interview de feedback produit en français qui demande aux gens ce qu’ils ont aimé, ce qui les a freinés, et ce qu’ils aimeraient voir ensuite. Envoie-la à jane@example.com. »

L’agent appelle create-interview avec un prompt, un locale et un invitees contenant jane@example.com. Une invitation est créée pour cette invitée et envoyée immédiatement :

{
  "interviewId": "12345678-1234-1234-1234-1234567890ab",
  "invitations": [
    { "slug": "M3nB7vCxQa", "status": "ready", "name": "Jane", "url": "https://raconte.ai/i/M3nB7vCxQa", "sent": true, "error": null }
  ]
}

Sans invitees, l’agent crée une seule invitation partageable (destinataire null) et vous récupérez son url dans invitations pour l’envoyer vous-même.

Exemple 2, inviter plusieurs participants

« Invite ces personnes à l’interview 12345678-1234-1234-1234-1234567890ab : Jane (jane@example.com), Marc (marc@example.com) et le 06 12 34 56 78. »

L’agent appelle create-invitation avec le tableau invitees. Chaque invité a besoin d’un email, et est envoyé immédiatement. Le résultat indique par invitation si l’envoi a réussi (sent) ou pourquoi il a échoué (error), sans bloquer les autres :

{
  "invitations": [
    { "slug": "K9pQ2mWxYz", "status": "ready", "name": "Jane", "url": "https://raconte.ai/i/K9pQ2mWxYz", "sent": true, "error": null },
    { "slug": "M3nB7vCxQa", "status": "ready", "name": "Marc", "url": "https://raconte.ai/i/M3nB7vCxQa", "sent": false, "error": "email: adresse invalide" }
  ]
}

Exemple 3, partager un lien sans l’envoyer

« Donne-moi un lien d’invitation pour cette interview, je l’enverrai moi-même. »

Chaque interview porte déjà une invitation READY partageable : son url, retournée par create-interview, se colle dans votre propre email, un QR code ou un canal Slack. create-invitation, lui, envoie toujours dès qu’un email est fourni.

Exemple 4, lire les transcripts

« Montre-moi les réponses à l’interview 12345678-1234-1234-1234-1234567890ab. »

L’agent appelle get-interview, qui renvoie l’interview avec ses invitations et, pour celles qui sont completed, le transcript complet (messages, rôle, sentiment) plus un résumé. Pour ne lire qu’un seul participant, get-invitation avec l’id de l’invitation suffit.

Le résumé arrive avec un court délai

Le résumé et les sentiments sont produits juste après la fin de l’appel. Si vous lisez un transcript dans les secondes qui suivent le raccrochage, attendez-vous à summary: null le temps que la passe d’insights se termine.

Exemple 5, mettre à jour, annuler, archiver

« Rallonge la durée max de cette interview à 15 minutes et change son titre en “Feedback bêta”. »

L’agent appelle update-interview ; seuls les champs cités changent. Le même outil archive une interview avec archived: true (et la restaure avec false).

Côté invitation, update-invitation gère le cycle de vie :

status: "cancelled" désactive un lien encore ready (et "ready" le réactive).
archived: true supprime l’invitation en douceur (soft delete), false la restaure.
donner une nouvelle valeur à email renvoie l’invitation à cette adresse (le résultat porte alors sent/error).

Exemple 6, retrouver une interview existante

« Liste mes trois dernières interviews. »

L’agent appelle list-interviews avec limit: 3. Les résultats arrivent de la plus récente à la plus ancienne, chacun avec un extrait du prompt et ses compteurs d’invitations, de quoi identifier celle que vous visez avant d’enchaîner sur get-interview :

{
  "total": 26,
  "limit": 3,
  "offset": 0,
  "hasMore": true,
  "interviews": [
    { "id": "12345678-...", "title": "Retours bêta", "promptExcerpt": "Demande aux gens ce qu'ils ont aimé...", "invitationsCount": 12, "completedCount": 7 }
  ]
}

Les deux outils de liste acceptent une recherche search (titre et prompt pour les interviews ; destinataire, résumé et titre de l’interview pour les invitations) et se paginent avec limit et offset, total et hasMore indiquant à l’agent s’il reste une page. Pour balayer les réponses de toute une organisation sans connaître les identifiants d’interview, list-invitations suffit : chaque ligne porte son interviewTitle et son résumé IA.

Cycle de vie d’une invitation

stateDiagram-v2
    state "Archivée (soft delete)" as ARCHIVED
    [*] --> READY: create-invitation
    READY --> IN_PROGRESS: envoi ou ouverture du lien
    IN_PROGRESS --> COMPLETED: dernier message puis raccrochage
    READY --> CANCELLED: status cancelled
    CANCELLED --> READY: status ready
    READY --> ARCHIVED: archived true
    ARCHIVED --> READY: archived false
    COMPLETED --> [*]

Bonnes pratiques

Une clé, une organisation. Chaque appel s’exécute sur l’organisation de la clé API. Les interviews et invitations des autres organisations ne sont jamais retournées.
Travaillez avec les ids. create-interview renvoie l’interviewId et les invitations créées (invitations[].id), create-invitation renvoie les invitations créées : gardez ces ids pour enchaîner avec get-* et update-* plus tard. Si vous les avez perdus, list-interviews et list-invitations les retrouvent.
Laissez l’agent enchaîner. Une demande comme « crée l’interview, invite ces dix personnes, puis résume-moi les réponses dès qu’elles arrivent » se traduit naturellement en create-interview → create-invitation → get-interview.

Besoin du détail d’un paramètre ? Tout est dans la référence du serveur MCP.