Démarrage rapide MCP

Cette page vous mène de « pas de jeton » à « le serveur MCP est joignable » en trois étapes. Ensuite, choisissez une page de configuration de client pour le brancher dans Claude Desktop, Cursor, ChatGPT ou n8n.

1. Générer un jeton

Dans Paramètres → Jetons API, cliquez sur Créer un jeton. Nommez-le d'après le client que vous allez connecter (p. ex. Claude Desktop). Copiez la valeur — Qyvo ne l'affiche que pendant 90 secondes.

Le jeton fonctionne à la fois pour /api/v1/* et /mcp. Voir Authentification pour le modèle complet de jeton.

2. Vérifier le handshake

Vous pouvez appeler le serveur MCP directement avec curl pour confirmer qu'il est joignable et que votre jeton est accepté. Le premier message dans toute session MCP est initialize :

curl -X POST https://www.qyvo.io/mcp \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "curl-smoke", "version": "1" }
    }
  }'

Une réponse réussie inclut le nom du serveur Qyvo, la version 1.0.0, et les capacités (tools, prompts, resources) :

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": { "listChanged": false },
      "prompts": { "listChanged": false },
      "resources": { "listChanged": false }
    },
    "serverInfo": { "name": "Qyvo", "version": "1.0.0" }
  }
}

Un 401 signifie que le jeton est erroné. Un 404 est un problème de version de déploiement — ouvrez un ticket.

3. Lister les outils

Dans la même session, enchaînez avec tools/list pour confirmer que les 35 outils sont exposés :

curl -X POST https://www.qyvo.io/mcp \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Vous recevrez le catalogue avec la description de chaque outil, son schéma d'entrée et ses annotations IsDestructive / IsReadOnly. Voir Référence des outils : Contacts pour la version lisible.

4. Connecter un client

Choisissez le client que vous utiliserez :

• Claude Desktop — déposez une configuration JSON dans claude_desktop_config.json
• Cursor — Settings → MCP → Add server
• ChatGPT — quand le support MCP arrivera
• n8n — installez n8n-nodes-qyvo depuis le registre community, ou câblez le nœud MCP Client directement

Dépannage

• 401 Unauthorized — jeton révoqué, expiré, ou le scope mcp a été supprimé. Générez-en un nouveau.
• 404 / Personal access client not found — serveur obsolète. Attendez le prochain déploiement.
• No workspace context available — l'utilisateur derrière le jeton n'a pas de tenant. Vérifiez la configuration de l'espace de travail dans Paramètres → Espace de travail.
• Outils listés mais send_message renvoie Meta 132012 / 132001 — la langue du template n'a pas de traduction APPROVED. Ouvrez Paramètres → WhatsApp → Templates et resynchronisez.