Serveur MCP

Le serveur MCP de Raconte : outils, paramètres et exemples de payloads.

Raconte expose un serveur Model Context Protocol en Streamable HTTP. N’importe quel client compatible MCP (Claude Desktop, Claude Code, Cursor, Opencode, VS Code Copilot Chat, Windsurf) peut piloter le produit avec six outils : trois sur les interviews, trois sur les invitations.

Vous cherchez la configuration des clients ? Lisez le guide de configuration MCP. Cette page sert de référence pour les outils eux-mêmes.

Endpoint et authentification

L’endpoint MCP est https://api.raconte.ai/api/mcp. L’authentification se fait via une clé API passée en query string :

https://api.raconte.ai/api/mcp?api_key=VOTRE_CLE_API

Les clés API se créent depuis Paramètres → API dans l’app et sont rattachées à une organisation. L’endpoint et une configuration client prête à coller sont aussi disponibles depuis Paramètres → MCP. Chaque appel d’outil s’exécute sur cette organisation ; les ressources d’autres organisations ne sont jamais retournées.

create-interview

Crée une interview vocale IA. Sans invitees, une seule invitation partageable READY est créée (son url est le lien à partager manuellement). Avec invitees, une invitation est créée par invité à la place (pas d’invitation vide), et chaque invité est envoyé par email immédiatement. Un échec d’envoi n’arrête pas les autres et est remonté par invitation (sent/error). La réponse renvoie toujours les invitations créées dans invitations.

Paramètre	Type	Requis	Description
`prompt`	string	oui	Prompt de l’interview décrivant les questions à poser
`locale`	enum	non	Langue de l’interview. Par défaut, la langue par défaut de l’organisation si omise
`title`	string	non	Titre personnalisé optionnel
`intro`	string	non	Message d’introduction optionnel affiché au destinataire
`firstMessage`	string	non	Premier message optionnel prononcé par l’IA au démarrage
`invitees`	array	non	Invités à créer et envoyer tout de suite. Chaque item supporte `name`, `email` (email requis)

Exemple de réponse sans invitees : une seule invitation partageable, champs destinataire null et sent: false (rien n’a été envoyé) :

{
  "interviewId": "12345678-1234-1234-1234-1234567890ab",
  "invitations": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "slug": "K9pQ2mWxYz",
      "status": "ready",
      "name": null,
      "email": null,
      "url": "https://raconte.ai/i/K9pQ2mWxYz",
      "sent": false,
      "error": null
    }
  ]
}

Avec invitees, invitations contient une entrée par invité à la place, chacune avec ses name/email et son résultat d’envoi sent/error.

update-interview

Patch d’une interview. Seuls les champs fournis sont mis à jour. Passez archived: true pour archiver (ou false pour restaurer).

Paramètre	Type	Requis	Description
`interviewId`	uuid	oui	UUID de l’interview à mettre à jour
`title`	string	non	Nouveau titre
`prompt`	string	non	Nouveau prompt (10 caractères minimum)
`intro`	string	non	Nouveau message d’introduction affiché à l’invité
`firstMessage`	string	non	Nouveau premier message prononcé par l’IA au démarrage
`locale`	enum	non	Nouvelle langue de l’interview
`maxMinutes`	number	non	Durée maximum par appel, en minutes. Les silences ne sont pas comptés.
`maxResponses`	number	non	Nombre maximum d’échanges (tours de parole de l’invité) avant l’arrêt de l’interview
`disableOrgSystemPrompt`	boolean	non	Si true, ne préfixe pas le prompt système de l’organisation
`archived`	boolean	non	Archiver (true) ou restaurer (false) l’interview

Exemple de réponse :

{
  "id": "12345678-1234-1234-1234-1234567890ab",
  "title": "Feedback bêta",
  "prompt": "Demande aux gens ce qu'ils ont aimé...",
  "intro": "Merci de prendre deux minutes !",
  "firstMessage": "Bonjour, merci de répondre à cette interview.",
  "locale": "fr",
  "maxMinutes": 15,
  "maxResponses": 100,
  "archivedAt": null,
  "createdAt": "2026-05-29T10:14:22.123Z",
  "updatedAt": "2026-05-29T11:02:05.880Z"
}

get-interview

Récupère une interview par id avec toutes ses invitations et leurs transcripts complets.

Paramètre	Type	Requis	Description
`interviewId`	uuid	oui	UUID de l’interview à récupérer

Exemple de réponse :

{
  "id": "12345678-1234-1234-1234-1234567890ab",
  "title": "Feedback bêta",
  "prompt": "Demande aux gens ce qu'ils ont aimé...",
  "intro": "Merci de prendre deux minutes !",
  "firstMessage": "Bonjour, merci de répondre à cette interview.",
  "locale": "fr",
  "maxMinutes": 15,
  "maxResponses": 100,
  "archivedAt": null,
  "createdAt": "2026-05-29T10:14:22.123Z",
  "updatedAt": "2026-05-29T11:02:05.880Z",
  "invitations": [
    {
      "id": "abcdef12-3456-7890-abcd-ef1234567890",
      "interviewId": "12345678-1234-1234-1234-1234567890ab",
      "slug": "K9pQ2mWxYz",
      "status": "completed",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "summary": "L'invitée a apprécié l'onboarding et bute sur l'export.",
      "archivedAt": null,
      "createdAt": "2026-05-29T10:14:22.123Z",
      "updatedAt": "2026-05-29T10:31:40.500Z",
      "url": "https://raconte.ai/i/K9pQ2mWxYz",
      "messages": [
        { "role": "assistant", "content": "Bonjour ! Qu'avez-vous préféré ?", "sentiment": null, "createdAt": "2026-05-29T10:20:00.000Z" },
        { "role": "user", "content": "L'onboarding était fluide.", "sentiment": "positive", "createdAt": "2026-05-29T10:20:30.000Z" }
      ]
    }
  ]
}

create-invitation

Crée une ou plusieurs invitations pour une interview existante. Chaque invitation est envoyée immédiatement par email. Un échec d’envoi n’arrête pas les autres et est remonté par invitation (sent/error).

Paramètre	Type	Requis	Description
`interviewId`	uuid	oui	UUID de l’interview à laquelle inviter des personnes
`invitees`	array	oui	Liste d’invités. Chaque item supporte `name`, `email`. Chaque invité doit avoir un email

Exemple de réponse :

{
  "invitations": [
    {
      "id": "abcdef12-...",
      "slug": "K9pQ2mWxYz",
      "status": "ready",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "url": "https://raconte.ai/i/K9pQ2mWxYz",
      "sent": true,
      "error": null
    }
  ]
}

update-invitation

Patch d’une invitation. Passez status: "cancelled" pour la désactiver (ou "ready" pour réactiver une invitation annulée, ou rouvrir une invitation terminée, qui passe alors au statut reopened pour que l’invité puisse la reprendre depuis son lien) et archived: true pour la supprimer (soft-delete ; false la restaure). Donner une nouvelle valeur à email renvoie l’invitation à cette valeur ; un échec d’envoi est remonté (sent/error) sans faire échouer la mise à jour.

Paramètre	Type	Requis	Description
`invitationId`	uuid	oui	UUID de l’invitation à mettre à jour
`name`	string	non	Nouveau nom d’invité (`null` pour effacer)
`email`	string	non	Nouvel email d’invité (`null` pour effacer ; une nouvelle valeur renvoie l’invitation)
`status`	enum	non	`"cancelled"` désactive une READY ; `"ready"` réactive une CANCELLED ou rouvre une COMPLETED (elle passe en `reopened` pour que l’invité la reprenne)
`archived`	boolean	non	Archiver (true) ou restaurer (false). L’archivage est un soft-delete.

Exemple de réponse (les champs sent/error ne sont présents que si un destinataire a changé) :

{
  "id": "abcdef12-3456-7890-abcd-ef1234567890",
  "interviewId": "12345678-1234-1234-1234-1234567890ab",
  "slug": "K9pQ2mWxYz",
  "status": "ready",
  "name": "Jane Doe",
  "email": "jane.new@example.com",
  "summary": null,
  "archivedAt": null,
  "createdAt": "2026-05-29T10:14:22.123Z",
  "updatedAt": "2026-05-29T12:00:00.000Z",
  "url": "https://raconte.ai/i/K9pQ2mWxYz",
  "sent": true,
  "error": null
}

get-invitation

Récupère une invitation par id avec son status et son transcript complet (messages, rôle et sentiment).

Paramètre	Type	Requis	Description
`invitationId`	uuid	oui	UUID de l’invitation à récupérer

Exemple de réponse :

{
  "id": "abcdef12-3456-7890-abcd-ef1234567890",
  "interviewId": "12345678-1234-1234-1234-1234567890ab",
  "slug": "K9pQ2mWxYz",
  "status": "completed",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "summary": "L'invitée a apprécié l'onboarding et bute sur l'export.",
  "archivedAt": null,
  "createdAt": "2026-05-29T10:14:22.123Z",
  "updatedAt": "2026-05-29T10:31:40.500Z",
  "url": "https://raconte.ai/i/K9pQ2mWxYz",
  "messages": [
    { "role": "assistant", "content": "Bonjour ! Qu'avez-vous préféré ?", "sentiment": null, "createdAt": "2026-05-29T10:20:00.000Z" },
    { "role": "user", "content": "L'onboarding était fluide.", "sentiment": "positive", "createdAt": "2026-05-29T10:20:30.000Z" }
  ]
}

Cycle de vie d’une invitation, en résumé

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
    COMPLETED --> REOPENED: status ready
    REOPENED --> IN_PROGRESS: l'invité reprend
    REOPENED --> COMPLETED: complete
    READY --> ARCHIVED: archived true
    ARCHIVED --> READY: archived false
    COMPLETED --> [*]

get-interview et get-invitation incluent le transcript des invitations COMPLETED. Le résumé arrive peu après la fin de l’appel ; si vous lisez le transcript juste à la fin, attendez-vous à summary: null pendant quelques secondes.