Serveur MCP (Claude et assistants IA)

C’est un pont sécurisé entre vos données de cave et un client compatible MCP. Après authentification, l’assistant peut appeler des outils VinoCellar en votre nom, dans le cadre de votre abonnement et des règles du compte.

L’URL publique exacte est affichée dans l’app VinoCellar, écran MCP / jetons d’accès (route interne /app/mcp), bloc « Adresse du serveur MCP ». Copiez-la telle quelle.

Sur l’app de production VinoCellar, l’hôte MCP par défaut est https://mcp.vinocellar.app . Privilégiez toujours la valeur affichée dans l’app si elle diffère (build personnalisé ou configuration future via EXPO_PUBLIC_MCP_SERVER_URL).

1. Ouvrez l’app → section MCP (ou Paramètres → VinoCellar MCP → gérer les jetons).
2. Copiez l’URL du serveur dans le bloc prévu.
3. Dans Claude Desktop (ou un autre client), ajoutez un serveur MCP et collez cette URL selon la documentation actuelle du client.
4. Lors de la première connexion, suivez l’étape OAuth dans le navigateur ; collez le jeton personnel créé dans l’app lorsque le formulaire le demande.

Le serveur MCP VinoCellar suit la spécification MCP en transport Streamable HTTP : votre client dialogue avec le point d’entrée MCP en HTTPS (ce n’est pas un catalogue REST générique à parcourir à la main).

À la première connexion, le client MCP lance un flux de type OAuth. Une fenêtre navigateur vous demande de coller le jeton d’accès personnel créé dans l’app VinoCellar ; le serveur MCP le valide auprès de l’API VinoCellar puis délivre des identifiants que le client envoie en en-tête Bearer sur les requêtes MCP suivantes.

Les jetons créés depuis l’écran MCP sont émis avec les scopes mcp:read et mcp:write pour permettre à l’assistant d’appeler les outils enregistrés par VinoCellar.

Pour un test de disponibilité simple de l’hôte (sans session MCP complète), le serveur répond à GET /ping par le texte brut pong.

Le jeton identifie votre compte auprès du serveur MCP :

1. Dans l’app, ouvrez l’écran MCP puis créez un jeton.
2. Donnez-lui un libellé clair (ex. « MacBook », « Claude Desktop », « Cursor »).
3. Copiez la valeur tout de suite : elle ne s’affiche qu’une fois.
4. Révoquez un jeton sur le même écran si un appareil est perdu ou pour couper l’accès d’un client.

Considérez les jetons comme des mots de passe : toute personne disposant du jeton et de l’URL peut accéder à votre cave via MCP jusqu’à révocation.

Voici les noms d’outils exposés aux clients MCP (identifiants exacts) :

• vinocellar_whoami — vérifier le compte lié ; la réponse JSON inclut un objet mcp (texte d’accueil, URL FAQ, indices sur les outils).
• vinocellar_help — renvoyer le même JSON d’accueil que l’objet mcp de vinocellar_whoami sans rappeler l’API profil.
• vinocellar_list_wines — inventaire large ; préférer vinocellar_search_wines pour filtrer par nom ou domaine.
• vinocellar_search_wines — recherche texte sur vos bouteilles.
• vinocellar_get_caves — lister les caves avant d’en cibler une.
• vinocellar_get_cave — disposition par casiers ; fournit les log_id pour vinocellar_move_bottle.
• vinocellar_move_bottle — déplacer une bouteille vers un autre casier ou une autre cave via le log_id renvoyé par vinocellar_get_cave.
• vinocellar_import_wine — ajouter un vin à partir de wine_data structuré (forme GeminiWineResponse) et images d’étiquette avant/arrière en base64 en option ; nécessite un abonnement MCP actif sur le compte.

Les outils MCP se limitent aux opérations d’inventaire et de cave listées ci-dessus.

L’assistant conversationnel Vino dans l’app, l’assistant mets-vins, le journal de dégustation et les autres fonctions IA ne sont pas exposés comme outils MCP distincts — utilisez l’app mobile ou le web pour ces usages.

VinoCellar s’adresse aux personnes qui utilisent un assistant compatible MCP (Claude Desktop, Cursor, etc.) : vous copiez l’URL du serveur depuis l’app et vous créez un jeton personnel.

Il n’existe pas d’application OAuth partenaire séparée ni de document OpenAPI « MCP en REST » : le contrat d’intégration est le protocole MCP (tools/list et la description/schéma de chaque outil tel que votre client les affiche).

Les crédits servent surtout aux scans photo d’étiquettes dans l’app. L’abonnement MCP est distinct : tant qu’il est actif, les appels via le serveur MCP pour les opérations prises en charge ne sont pas plafonnés par votre solde de crédits scan de la même manière.

Claude Desktop et les clients compatibles MCP avec le transport VinoCellar sont pris en charge aujourd’hui. La compatibilité ChatGPT et Gemini est prévue ; consultez les notes de version et cette FAQ pour les mises à jour.