Configurer le serveur MCP

Raconte expose un serveur Model Context Protocol en Streamable HTTP. N’importe quel client compatible MCP peut piloter le produit avec huit outils : quatre sur les interviews (list-interviews, create-interview, update-interview, get-interview) et quatre sur les invitations (list-invitations, create-invitation, update-invitation, get-invitation).

Ce guide montre comment le brancher dans les clients les plus courants. Pour le rôle de chaque outil et des exemples de workflows, voir le guide d’utilisation et la référence du serveur MCP.

Avant de commencer

Il vous faut :

1. Un compte Raconte sur une organisation où vous pouvez créer des clés API.
2. Une clé API. Allez dans Paramètres → Clés API, créez-en une, copiez-la (la clé en clair n’est affichée qu’une fois).
3. L’URL du serveur MCP. En production : https://api.raconte.ai/api/mcp. Remplacez par votre propre domaine si vous auto-hébergez.

Créez la clé depuis Paramètres → Clés API :

Récupérez ensuite l’URL et une configuration prête à coller depuis Paramètres → MCP :

Le client se connecte à cette URL avec votre clé API en header bearer :

Authorization: Bearer VOTRE_CLE_API

Tous les clients ci-dessous acceptent un bloc headers, sauf Claude Desktop, dont les connecteurs personnalisés ne prennent qu’une URL. Pour celui-là, et pour tout client soumis à la même limite, la clé passe en paramètre de requête :

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

Mettre la clé dans un .env

La plupart des clients savent injecter une variable du shell dans la config MCP au démarrage, ce qui permet de garder la clé dans un .env sans qu’elle apparaisse jamais dans la config elle-même.

1. Mettez RACONTE_API_KEY=... dans un fichier .env (ou dans votre profil shell, ou dans un .envrc projet chargé par direnv).
2. Assurez-vous que le shell qui lance le client exporte bien la variable. Avec direnv, c’est automatique. Avec un .env brut, sourcez-le (set -a; source .env; set +a) ou utilisez un wrapper type dotenv autour de la commande.
3. Référencez la variable depuis la config avec la syntaxe attendue par votre client (chaque section ci-dessous l’utilise).

Ajoutez .env à .gitignore. Seul le nom de la variable se retrouve dans la config.

Claude Desktop

Claude Desktop lit sa configuration dans ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows).

Ajoutez une entrée sous mcpServers :

{
  "mcpServers": {
    "raconte": {
      "type": "streamable-http",
      "url": "https://api.raconte.ai/api/mcp?api_key=VOTRE_CLE_API"
    }
  }
}

Redémarrez Claude Desktop. Les outils raconte apparaissent dans le sélecteur d’outils.

Claude Code (CLI)

Le plus rapide est la commande claude mcp add. Depuis n’importe quel dossier :

claude mcp add --transport http raconte "https://api.raconte.ai/api/mcp" \
  --header "Authorization: Bearer \${RACONTE_API_KEY}"

Utilisez --scope user pour rendre le serveur disponible dans tous vos projets, ou --scope project pour committer un fichier .mcp.json à la racine du dépôt et le partager avec l’équipe.

Vous pouvez aussi éditer ~/.claude.json (scope user) ou .mcp.json (scope projet) à la main. Claude Code expanse ${VAR} depuis le shell parent, dans l’URL comme dans les headers :

{
  "mcpServers": {
    "raconte": {
      "type": "http",
      "url": "https://api.raconte.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${RACONTE_API_KEY}" }
    }
  }
}

La variable doit être exportée dans le shell qui lance Claude Code. Un .env posé dans le dépôt n’est pas lu par le client, et un ${RACONTE_API_KEY} non substitué arrive au serveur comme une clé invalide.

Puis claude mcp list confirme que le serveur est bien connecté.

Cursor

Cursor lit MCP dans ~/.cursor/mcp.json (global) ou .cursor/mcp.json à la racine du projet. Il expanse ${env:VAR} dans url comme dans headers :

{
  "mcpServers": {
    "raconte": {
      "type": "streamable-http",
      "url": "https://api.raconte.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${env:RACONTE_API_KEY}" }
    }
  }
}

Ouvrez Settings → MCP & Integrations pour vérifier que Cursor voit le serveur, puis activez les outils que l’agent peut appeler.

Opencode

Opencode lit ~/.config/opencode/config.json (ou opencode.json à la racine du projet). Il interpole avec {env:VAR} :

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "raconte": {
      "type": "remote",
      "url": "https://api.raconte.ai/api/mcp",
      "headers": { "Authorization": "Bearer {env:RACONTE_API_KEY}" },
      "enabled": true
    }
  }
}

Redémarrez Opencode. Les outils raconte deviennent accessibles à tous les modèles qui supportent le tool-use.

VS Code (GitHub Copilot Chat)

VS Code 1.99+ supporte MCP via .vscode/mcp.json par workspace, ou mcp.json dans votre profil utilisateur. Le plus propre est un input prompté de type password, que VS Code stocke dans son secret-storage :

{
  "inputs": [
    {
      "id": "raconteApiKey",
      "type": "promptString",
      "description": "Clé API Raconte",
      "password": true
    }
  ],
  "servers": {
    "raconte": {
      "type": "http",
      "url": "https://api.raconte.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${input:raconteApiKey}" }
    }
  }
}

${env:RACONTE_API_KEY} fonctionne aussi si vous préférez la variante variable d’environnement. Ouvrez le panneau Copilot Chat, passez en mode Agent, et les outils raconte apparaissent dans le sélecteur.

Windsurf

Dans Windsurf, ouvrez Settings → Cascade → MCP servers ou éditez ~/.codeium/windsurf/mcp_config.json. Le format supporte ${env:VAR} comme Cursor :

{
  "mcpServers": {
    "raconte": {
      "serverUrl": "https://api.raconte.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${env:RACONTE_API_KEY}" }
    }
  }
}

Sauvegardez et rechargez. Les outils apparaissent dans Cascade.

Outils disponibles

Une fois le serveur connecté, votre client peut appeler huit outils, tous limités à l’organisation propriétaire de la clé API et tous renvoyant du JSON :

• list-interviews, create-interview, update-interview, get-interview pour parcourir, créer, modifier et lire les interviews.
• list-invitations, create-invitation, update-invitation, get-invitation pour parcourir les invitations, inviter des participants et lire leurs transcripts.

Les deux outils list-* renvoient les résultats du plus récent au plus ancien, acceptent une recherche search et se paginent avec limit et offset.

Voir le guide d’utilisation pour des exemples et des workflows de bout en bout, et la référence du serveur MCP pour la liste complète des paramètres de chaque outil.

Dépannage

Si un appel renvoie une erreur d’authentification, la clé API a probablement été révoquée ou n’a jamais eu accès à l’organisation. Régénérez-en une dans Paramètres → Clés API et mettez la variable à jour.

Si vous auto-hébergez Raconte, remplacez https://api.raconte.ai par votre propre domaine d’API. Le chemin reste /api/mcp.