Guide du connecteur MCP
À quoi sert le connecteur
Le connecteur MCP (Model Context Protocol) relie un assistant IA, comme Claude, à votre entreprise dans Staff Flow. Vous lui parlez normalement : il lit le planning, les heures, les pointages, et peut créer des services, des annonces ou valider des demandes, selon les droits que vous lui donnez.
Exemples : « Qui travaille samedi au site Centre ? », « Mets Marie à la caisse lundi de 8 h à 16 h », « Combien d'heures a fait l'équipe en septembre ? », « Valide le congé de Paul », « Annonce à l'équipe Matin que l'inventaire est samedi ».
Connecter ChatGPT, Claude ou un autre assistant, sans clé
Dans l'assistant, ajoutez un connecteur (ou une application) avec l'adresse https://app.staff-flow.cloud/api/v1/mcp, puis touchez « Connecter ». Une page Staff Flow s'ouvre : connectez-vous, choisissez l'entreprise, puis « Autoriser ». C'est relié, sans clé à copier (connexion OAuth, jetons qui expirent et se renouvellent tout seuls).
L'entreprise choisit qui peut le faire : privilège « Utiliser son assistant IA », par rôle ou par personne (Rôles et privilèges). L'assistant a exactement les privilèges de la personne ; un responsable de site ne lit que ses sites. Si ses droits changent, l'assistant suit aussitôt.
Chacun retrouve et déconnecte ses assistants dans Réglages → Assistants IA ; le patron les voit tous dans Configurations → Accès API → Applications connectées.
Ce qu'il faut (clé API)
Pour un logiciel, ou un connecteur lancé sur votre ordinateur : une clé API de votre entreprise (Configurations → Accès API → Nouvelle clé). La lecture du planning, des heures, des absences et de l'entreprise demande l'option « accès API » ; l'écriture et la lecture du pointage, de la paie, des demandes, des sondages et des signatures demandent « API Pro ».
La clé complète ne s'affiche qu'une fois : gardez-la comme un mot de passe. Vous pouvez la mettre de côté, changer ses droits ou la révoquer à tout moment : l'assistant perd aussitôt l'accès.
Brancher l'assistant
Adresse du connecteur : https://app.staff-flow.cloud/api/v1/mcp (transport HTTP). La clé passe dans l'en-tête « Authorization: Bearer … » (ou « X-Api-Key »).
Claude Code (terminal) :
claude mcp add --transport http staff-flow https://app.staff-flow.cloud/api/v1/mcp \
--header "Authorization: Bearer sfk_xxxxxxxx_yyyyyyyy…"
Claude Desktop, ou tout logiciel qui lance des connecteurs locaux (fichier claude_desktop_config.json, avec Node.js installé) :
{
"mcpServers": {
"staff-flow": {
"command": "npx",
"args": ["mcp-remote", "https://app.staff-flow.cloud/api/v1/mcp",
"--header", "Authorization:${AUTH_HEADER}"],
"env": {"AUTH_HEADER": "Bearer sfk_xxxxxxxx_yyyyyyyy…"}
}
}
}
Autre logiciel compatible MCP : donnez l'adresse et l'en-tête ci-dessus. Pour un développeur, chaque message est une requête JSON-RPC 2.0 en POST :
POST https://app.staff-flow.cloud/api/v1/mcp
Authorization: Bearer sfk_…
Content-Type: application/json
{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {"name": "get_shifts", "arguments": {"from": "2026-10-05", "to": "2026-10-11"}}}
Droits de la clé
Chaque fonction a un droit de lecture (« x:read ») et, quand c'est utile, un droit d'écriture (« x ») qui donne aussi la lecture. L'assistant ne voit que les outils permis par sa clé ; un outil hors droit renvoie une erreur 403 et rien n'est fait.
Droits : catalog (entreprise : sites, postes, équipes, créneaux), members (salariés), shifts (planning), publish (publier), absences, requests (demandes), news (annonces), clock (pointage), payroll (paie), polls (sondages), signatures (suivi des signatures).
Conseil : donnez à chaque assistant le minimum. Pour un assistant qui prépare le planning sans le publier : shifts et members:read. Pour un assistant de paie : clock:read et payroll:read.
Les 30 outils
| Outil | Ce qu'il fait | Droit de la clé | Paramètres (* obligatoire) |
|---|---|---|---|
| get_company | Nom, fuseau horaire, sites, postes, équipes et leurs membres. | catalog:read | — |
| list_members | Personnes (actuelles et parties) : SF ID, matricule, poste, rôle, dates. | members:read | — |
| get_roles | Hiérarchie des rôles : noms, rangs, privilèges. | members:read | — |
| get_shifts | Services publiés de la période. | shifts:read | from, to |
| get_hours | Heures publiées par personne. | shifts:read | from, to |
| get_coverage_gaps | Créneaux où il manque du monde. | shifts:read | from, to |
| get_absences | Congés et indisponibilités validés. | absences:read | from, to |
| create_shifts | Crée des services, en brouillon ; « publish » publie seulement ceux-là. Signale chevauchements, absences et règles légales. | shifts (+ publish) | shifts*[day*, start*, end*, person | team, site, position, note, location], publish, force |
| update_shift | Modifie un service : seuls les champs donnés changent ; il repasse en brouillon. | shifts (+ publish) | id*, day, start, end, person, site, position, note, location, publish, force |
| delete_shift | Supprime un service. | shifts (+ publish) | id*, publish |
| publish_schedule | Publie les services donnés (« shifts »), sinon tous les brouillons : les salariés sont prévenus. | publish | shifts, force |
| import_employees | Ajoute des salariés : chacun reçoit un code et un QR code d'invitation. « dryRun » : aperçu sans rien créer. | members | rows*[name*, number, position, site], dryRun |
| list_invitations | Invitations en attente (code, lien du QR code). | members | — |
| set_employee_profile | Matricule et/ou poste habituel ; un champ absent est gardé. | members | person*, employeeNumber, position |
| add_to_team | Ajoute une personne à une équipe. | members | team*, person* |
| remove_from_team | Retire une personne d'une équipe. | members | team*, person* |
| create_site | Crée un site, éventuellement sous un site parent. | catalog | name*, parent |
| create_position | Crée un poste (métier). | catalog | name* |
| create_team | Crée une équipe. | catalog | name* |
| add_coverage_rule | Nombre minimum de personnes par jour et par plage horaire. | catalog | weekdays*, start*, end*, min*, site, position, label |
| post_announcement | Publie une annonce, avec date butoir si besoin. | news | body*, title, audience, endsAt |
| list_pending_requests | Demandes en attente : échanges, congés, indisponibilités. | requests:read | — |
| decide_request | Valide ou refuse une demande. | requests | id*, approve* |
| get_clock_events | Pointages de la période (borne, téléphone, saisie). | clock:read | from, to |
| get_timesheet | Feuille de temps : minutes prévues, pointées, congés. | clock:read | from, to |
| add_clock_event | Saisit un pointage oublié (gardé dans l'historique). | clock | person*, at*, kind* (in | out), note |
| get_payroll_preview | Aperçu indicatif de la paie (pas une fiche de paie). | payroll:read | from, to, planned |
| list_polls | Sondages et résultats. | polls:read | — |
| create_poll | Crée un sondage pour tous ou pour un public choisi. | polls | question*, options* (2–10), multi, anonymous, closesAt, audience |
| list_signatures | Suivi des signatures : signé, refusé, en attente. | signatures:read | — |
Désigner les personnes, lieux et heures
Une personne : son identifiant SF (SF-…), visible dans son profil et dans list_members, ou son matricule. Un site, un poste ou une équipe : son nom exact ou son identifiant.
Dates : AAAA-MM-JJ. Heures : « HH:MM » ; une fin avant le début signifie le lendemain (22:00 → 06:00). Pointage et date butoir : date et heure ISO 8601 (2026-10-26T07:58:00+01:00). Tout est dans le fuseau horaire de l'entreprise.
Période (from, to) : sans « from », depuis la création de l'entreprise ; sans « to », jusqu'à aujourd'hui.
Public d'une annonce ou d'un sondage (audience) : « everyone »: true, ou des listes « sites », « positions », « teams », « roles », « users ». Sans public, l'annonce va à tout le monde.
Exemple de services pour create_shifts (une personne, une équipe, un service libre avec un lieu) :
{
"shifts": [
{"day": "2026-10-20", "start": "07:00", "end": "15:00", "person": "M-0007",
"site": "Centre", "position": "Barista", "note": "Inventaire"},
{"day": "2026-10-20", "start": "22:00", "end": "06:00", "team": "Nuit"},
{"day": "2026-10-21", "start": "09:00", "end": "12:00",
"location": {"lat": 48.8584, "lng": 2.2945, "label": "12 rue du Chantier"}}
],
"publish": false
}
Brouillons et publication
Les services créés ou modifiés par l'assistant arrivent en brouillon : les responsables les voient dans l'application, les ajustent, puis publient. Les salariés ne voient rien avant la publication.
Avec le droit « publish », l'assistant peut publier : « publish »: true dans create_shifts, update_shift ou delete_shift publie seulement ces services ; publish_schedule avec « shifts » publie ceux-là. Les autres brouillons en cours ne bougent pas. Sans ce droit, la demande de publication est refusée (403).
Chaque création ou modification renvoie ses problèmes (« warnings ») : chevauchement avec un autre service de la personne, ici ou dans une autre entreprise, absence validée, règle légale dépassée. S'il y en a, la publication est refusée et le service reste en brouillon : l'assistant vous prévient, et ne publie avec « force »: true qu'après votre confirmation.
Erreurs
| Code | Signification |
|---|---|
| 400 | Donnée invalide : date, heure, champ manquant, personne, site, poste ou équipe inconnu, date butoir passée. Rien n'est créé pour l'élément en cause. |
| 401 | Clé absente, fausse ou révoquée. |
| 402 | Option nécessaire inactive (« accès API » ou « API Pro »). |
| 403 | La clé n'a pas le droit demandé. |
| 404 | Service, demande ou élément introuvable. |
| 429 | Trop d'appels : réessayez après le délai indiqué. |
L'assistant reçoit l'erreur en clair (« Error 403: … ») et peut vous l'expliquer ou corriger sa demande.
Historique et sécurité
Chaque appel de l'assistant est noté dans Configurations → Accès API → Journaux : date, clé, action en clair, résultat, adresse IP, avec l'avant et l'après d'une modification. Les écritures apparaissent aussi dans l'historique de l'entreprise avec le nom de la clé.
L'assistant n'obtient jamais les mots de passe, les adresses e-mail des salariés, les images de signature ni les adresses IP des signataires. Les données passent par l'assistant que vous choisissez : vérifiez ses conditions avant d'y brancher votre entreprise.