Connecter un assistant IA (MCP)
Comment laisser Claude, ChatGPT ou tout autre agent travailler avec votre Norka via le Model Context Protocol.
Norka parle MCP (le Model Context Protocol). Une fois un assistant connecté, vous pouvez lui demander « qui arrive vendredi ? » ou lui dire « réserve l’Appartement 2 pour les Novák du 3 au 7 août », et il s’en charge, avec les mêmes règles et notifications que l’application.
L’adresse du serveur est la même pour tous les clients :
https://mcp.mojenorka.cz/mcp
1. Créer un jeton API
- Dans Norka, ouvrez Paramètres → Jetons API et cliquez sur Créer un jeton.
- Nommez-le d’après l’endroit où vous l’utiliserez (par exemple « Claude Desktop ») et choisissez un Périmètre :
| Périmètre | Ce que l’assistant peut faire |
|---|---|
Lecture (read) | voir le calendrier, les séjours, les voyageurs, les séjours impayés et la configuration |
Écriture (write) | en plus, réserver et modifier des séjours, assigner le ménage, envoyer un lien de check-in |
Administration (admin) | en plus, modifier la configuration : logements, codes de porte, saisons, flux |
- Le jeton n’est affiché qu’une seule fois. Copiez-le ; Norka n’en conserve que l’empreinte. Vous pouvez le révoquer à tout moment.
Commencez par le périmètre Lecture. N’accordez l’écriture ou l’administration à un jeton qu’une fois que vous savez à quoi l’assistant l’utilise.
2. Ajouter le serveur à votre client
Le jeton est envoyé dans un en-tête Authorization: Bearer … classique.
Claude Desktop
Ouvrez Settings → Developer → Edit Config et ajoutez :
{
"mcpServers": {
"norka": {
"url": "https://mcp.mojenorka.cz/mcp",
"headers": { "Authorization": "Bearer nrk_…" }
}
}
}
Redémarrez Claude Desktop. Norka apparaît parmi les outils.
Claude Code
claude mcp add --transport http norka https://mcp.mojenorka.cz/mcp \
--header "Authorization: Bearer nrk_…"
ChatGPT, Cursor et les autres
Dans les paramètres du client, ajoutez un serveur MCP distant (parfois appelé connecteur) avec l’adresse ci-dessus et l’en-tête Authorization. Les étapes exactes varient d’un client à l’autre, mais ces deux valeurs suffisent.
Vérifier que ça fonctionne
Demandez à l’assistant : « Appelle whoami. » Il répond avec l’espace de travail que représente le jeton et les outils dont il dispose.
3. Ce que l’assistant peut faire
Les outils visibles par un assistant dépendent du périmètre du jeton. En voici une sélection :
| Outil | Périmètre | Rôle |
|---|---|---|
get_movements | read | qui arrive et qui part un jour donné |
check_availability | read | quels logements sont libres pour un séjour, et ce qui bloque |
search_reservations | read | les séjours par date, logement, statut ou nom |
get_reservation | read | un séjour en détail, code de porte compris |
list_guests | read | qui fait partie d’un séjour |
get_estate_statistics | read | chiffre d’affaires et taux d’occupation d’un logement, par mois |
get_estate_pricing | read | la grille tarifaire d’un logement : prix de base, prix par saison, règles tarifaires et l’année à venir nuit par nuit |
get_price_quote | read | le coût d’un séjour à des dates données selon la grille tarifaire |
list_unpaid | read | les séjours impayés, y compris en retard |
get_attention | read | ce qui demande une action maintenant |
preview_transfer | read | ce que changerait le déplacement d’un séjour vers un autre appartement |
list_collisions | read | deux séjours qui réclament le même logement |
list_inquiries | read | les demandes du widget de réservation qui attendent une réponse |
list_booking_widgets | read | les widgets de réservation de vos sites : ce qu’ils proposent, leur apparence, les sites autorisés et le code à coller |
create_reservation, update_reservation | write | réserver ou modifier un séjour |
block_dates | write | bloquer les dates d’un appartement pour des travaux |
transfer_reservation | write | déplacer un séjour vers un autre appartement |
resolve_collision | write | régler un chevauchement en annulant l’un des deux séjours concernés |
update_reservation_estate | write | le prix, le coût du ménage ou le code de porte d’un logement d’un séjour, ou indiquer que personne ne fait le ménage après |
add_guest, update_guest | write | le registre des voyageurs d’un séjour |
assign_cleaner, mark_cleaning_complete | write | le ménage après un séjour |
send_checkin_link | write | envoyer par e-mail au voyageur son lien de check-in en ligne, et par SMS si les SMS sont activés |
add_note | write | ajouter une note à l’historique du séjour |
list_invoices | read | toutes les factures et tous les avoirs, filtrés, avec leur total |
get_invoices | read | si un séjour a besoin d’une facture, son montant et ce qui a déjà été émis |
issue_invoice | write | émettre la facture du séjour au client principal, numérotée et définitive |
send_invoice | write | envoyer la facture au client par e-mail, avec le PDF |
accept_inquiry, decline_inquiry | write | accepter une demande venue du site (le séjour est confirmé et le voyageur reçoit une confirmation), ou la refuser, libérer les dates et prévenir le voyageur par e-mail |
create_estate, update_season, create_pin_code | admin | modifier les logements (un nouveau logement exige une capacité, beds et extra_beds), les saisons et les codes de porte, y compris la liste de ménage par pièce (cleaning_checklist) ; update_estate peut aussi désactiver un logement, qui n’est alors plus proposé ni compté dans le taux d’occupation ; un logement nouveau ou réactivé au-delà de la limite de la formule est refusé |
set_season_price, create_rate_rule, update_rate_rule | admin | le prix d’un logement par saison, et un prix fixe ou une remise pour des dates précises |
create_booking_widget, update_booking_widget | admin | créer ou modifier un widget de réservation : logements proposés, sites autorisés, nuits minimum, affichage des prix et des avis, désactivation, couleurs en code hexadécimal (accent, free, busy), arrondi et taille (compact, regular, large) ; supprimer un widget et renouveler son jeton restent dans l’application |
Chaque réponse contient un lien vers la page de l’application dont elle provient, pour que vous puissiez vérifier.
Ce que l’assistant ne peut volontairement pas faire
- Supprimer quoi que ce soit. Ni réservations, ni logements, ni voyageurs, ni membres.
- Il n’annule pas de factures. Une annulation ou un avoir se fait par vous dans l’application.
- Créer ou révoquer des jetons, pour qu’un jeton divulgué ne puisse pas se renouveler lui-même.
- Gérer les membres ou supprimer l’espace de travail. Cela exige une session connectée dans l’application.
- Voir les coordonnées des voyageurs, sauf sur demande nominative pour un voyageur précis ; les listes ne contiennent que les noms.
- S’emballer. Chaque outil a un quota d’appels ; un assistant coincé dans une boucle reçoit une erreur lisible et ne casse rien.
Questions fréquentes
Puis-je avoir plusieurs jetons ? Oui. Un jeton par client est une bonne habitude : chacun peut ainsi être révoqué séparément.
Le jeton fonctionne-t-il en dehors de MCP ? Oui, la REST API accepte le même jeton. Le périmètre s’applique de la même façon : un jeton en lecture est refusé pour toute requête qui modifie quelque chose.
Je veux essayer le serveur sans assistant.
Utilisez l’outil officiel MCP Inspector : npx @modelcontextprotocol/inspector, puis saisissez l’adresse du serveur et l’en-tête avec le jeton.