Se connecter avec MCP | VillaSlot Documentation

MCP relie votre agent, comme Claude Code, aux données de VillaSlot. Vous vous connectez à votre compte, choisissez une organisation et autorisez les accès proposés. Votre agent peut alors consulter vos villas et, selon les droits accordés, créer des clients et des réservations.

Connecter votre client

Ajoutez cette URL de serveur dans votre client MCP :

https://www.villaslot.io/api/mcp

Lancez la connexion OAuth, connectez-vous avec votre mot de passe ou Google, puis vérifiez l’application, les droits et l’organisation avant d’autoriser. Une application enregistrée dynamiquement est indiquée comme non vérifiée. Les clients publics utilisent PKCE ; offline_access maintient la connexion par renouvellement. Le jeton d’accès expire après 15 minutes.

Choisissez explicitement l’organisation d’équipe sur l’écran de consentement. Votre dernière organisation active est présélectionnée seulement si vous y avez encore un rôle d’équipe ; sinon, choisissez-en une, même si elle est seule. Votre organisation active dans le navigateur ne change pas. L’autorisation reste liée au choix ; une reconnexion crée un nouveau grant. Les appartenances, suspensions et révocations sont vérifiées à chaque requête.

Claude Code

Avec Claude Code installé, lancez ces commandes dans votre terminal :

bash

claude mcp add --transport http --scope user villaslot https://www.villaslot.io/api/mcp
claude mcp login villaslot

Le navigateur s’ouvre pour la connexion OAuth. Connectez-vous à VillaSlot, choisissez l’organisation, vérifiez les droits demandés, puis cliquez sur Autoriser. La portée user rend cette configuration disponible dans tous vos projets sur cette machine.

Ouvrez ensuite Claude Code :

bash

claude

Dans la conversation Claude Code, saisissez /mcp pour vérifier le serveur villaslot. Si votre version ne propose pas claude mcp login, utilisez également /mcp, sélectionnez villaslot, puis lancez son authentification.

Codex

Avec la CLI Codex installée, ajoutez le serveur :

bash

codex mcp add villaslot --url https://www.villaslot.io/api/mcp

Codex peut proposer la connexion OAuth dès l’ajout. Si elle n’a pas été effectuée, lancez :

bash

codex mcp login villaslot

Dans le navigateur, connectez-vous à VillaSlot, choisissez l’organisation et cliquez sur Autoriser après avoir vérifié les droits. Ouvrez ensuite une nouvelle session :

bash

codex

Dans Codex, saisissez /mcp pour afficher les serveurs disponibles. Cette connexion OAuth ne demande pas de clé API VillaSlot ni d’en-tête Authorization à copier.

Vérifier la connexion

Dans Claude Code ou Codex, demandez :

Use the villaslot MCP to list my villas.
State which organization you are using. Do not change any data.

Vérifiez que le nom renvoyé correspond à l’organisation autorisée. Une session déjà ouverte peut nécessiter un redémarrage pour charger le nouveau serveur.

Pour une instance locale ou auto-hébergée, remplacez l’URL des commandes par celle de cette instance, suivie de /api/mcp (par exemple http://localhost:3088/api/mcp). Utilisez un nom distinct, comme villaslot-local, dans les commandes d’ajout et de connexion. Un serveur local dont les connexions sortantes sont bloquées peut nécessiter un client OAuth préenregistré plutôt que la découverte automatique du client.

Références : MCP dans Claude Code et MCP dans Codex.

Outils

Tool	Scope
`list_villas`	`mcp:read`
`get_villa`	`mcp:read`
`list_bookings`	`mcp:read`
`get_booking`	`mcp:read`
`list_customers`	`mcp:read`
`get_customer`	`mcp:read`
`get_availability`	`mcp:read`
`create_customer`	`mcp:customers`
`create_booking`	`mcp:bookings`
`create_overnight_booking`	`mcp:bookings`

Entrées et résultats

Les listes acceptent limit (25 par défaut, 100 maximum), offset (0–10000) et search (200 caractères maximum). list_villas accepte status : active, archived ou all. list_bookings accepte axis : UPCOMING ou RECENT, et un propertyId facultatif.

get_availability accepte kind: HOURLY, une villa, une date locale et une durationMinutes prise en charge ; ou kind: OVERNIGHT avec checkInDay et checkOutDay. Un séjour est limité à 366 nuits et respecte le minimum de l’organisation. Les dates suivent son fuseau horaire, renvoyé lorsque pertinent. Les montants sont des entiers en unité monétaire mineure, accompagnés de la devise : aucune conversion implicite par 100.

create_customer accepte un nom, et facultativement email, téléphone et notes. create_booking accepte les identifiants villa/client, date, minute de début, durée et statut (HOLD ou CONFIRMED) ; prix et pourcentage d’acompte sont facultatifs. create_overnight_booking exige un priceAmount total, les identifiants villa/client, dates d’arrivée/départ et statut. Le total n’est pas calculé depuis le tarif par nuit.

Les créations appliquent les mêmes permissions, quotas, prix, buffers, disponibilités et règles de conflit Airbnb que l’application. Elles ne sont pas idempotentes : ne relancez pas automatiquement une création dont le résultat est incertain. Relisez d’abord les données. Chaque résultat identifie l’organisation autorisée. Les jetons de lien client, secrets de paiement et agrégats financiers ne sont pas exposés.

Si un droit personnel est désactivé, réactivez-le puis enregistrez : aucune reconnexion n’est nécessaire. Une autorisation révoquée demande une nouvelle connexion et un nouveau consentement. Si vous avez quitté l’équipe, un rôle d’équipe doit d’abord être rétabli pour cette organisation. Relancez une demande de consentement expirée depuis le client. Inscription, liens magiques et codes de secours ne sont pas pris en charge dans ce parcours OAuth.

Droits personnels, plafond et applications

Dans Compte → Agents MCP, retrouvez les applications, leurs hôtes de redirection, scopes et organisations. La révocation déconnecte une application de toutes vos organisations immédiatement, jetons d’accès et de renouvellement compris. Elle reste accessible après le départ de toutes les équipes. Une reconnexion ne réactive jamais les anciens jetons.

Les trois interrupteurs contrôlent la lecture, la création de réservations et celle de clients pour toutes vos applications. Enregistrez pour appliquer les changements au prochain appel, sans reconnexion. Scopes OAuth, permissions d’équipe et limites du forfait restent applicables. Un droit désactivé renvoie MCP_RIGHTS_DENIED, sans boucle de connexion.

Pour bloquer la lecture, ouvrez Compte → Agents MCP, désactivez Lire les données, puis cliquez sur Enregistrer. Le prochain appel est refusé immédiatement. Révoquer une application est une action distincte : elle la déconnecte de toutes vos organisations autorisées.

Le plafond quotidien s’applique séparément dans chaque organisation, toutes applications confondues : vide signifie illimité, zéro interdit les créations. Chaque client, shooting ou nuitée effectivement créé compte pour une unité ; la lecture ne compte pas. Une erreur de réponse ou d’activité après validation ne retire pas la création du compteur. MCP_DAILY_LIMIT indique que le plafond personnel est atteint. Le jour est celui du fuseau de l’organisation à l’admission de l’appel (UTC si absent). Un fuseau invalide bloque les créations, mais pas les paramètres ni la révocation.