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 six outils : trois sur les interviews (create-interview, update-interview, get-interview) et trois sur les 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.

Le client se connecte à cette URL avec votre clé API en query string :

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?api_key=\${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 :

{
  "mcpServers": {
    "raconte": {
      "type": "http",
      "url": "https://api.raconte.ai/api/mcp?api_key=${RACONTE_API_KEY}"
    }
  }
}

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

{
  "mcpServers": {
    "raconte": {
      "type": "streamable-http",
      "url": "https://api.raconte.ai/api/mcp?api_key=${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?api_key={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?api_key=${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?api_key=${env:RACONTE_API_KEY}"
    }
  }
}

Sauvegardez et rechargez. Les outils apparaissent dans Cascade.

Outils disponibles

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

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

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.