Guida al connettore MCP
Questa pagina esiste in francese, ucraino e inglese: ecco la versione inglese.
What the connector does
The MCP (Model Context Protocol) connector links an AI assistant, such as Claude, to your company in Staff Flow. You talk to it normally: it reads the schedule, hours and clock-ins, and can create shifts, post announcements or approve requests, depending on the rights you give it.
Examples: “Who works on Saturday at the Centre site?”, “Put Marie on the till Monday from 8 to 4”, “How many hours did the team work in September?”, “Approve Paul's leave”, “Tell the Morning team the stocktake is on Saturday”.
Connect ChatGPT, Claude or another assistant, without a key
In the assistant, add a connector (or app) with the address https://app.staff-flow.cloud/api/v1/mcp, then tap “Connect”. A Staff Flow page opens: sign in, choose the company, then “Allow”. It is linked, with no key to copy (OAuth sign-in, tokens that expire and renew on their own).
The company decides who may do it: the “Use their own AI assistant” privilege, per role or per person (Roles and privileges). The assistant has exactly the person's privileges; a site manager only reads their sites. If their rights change, the assistant follows at once.
Everyone finds and disconnects their assistants in Settings → AI assistants; the owner sees them all in Settings → API access → Connected apps.
What you need (API key)
For software, or a connector started on your computer: an API key for your company (Settings → API access → New key). Reading the schedule, hours, absences and company needs the “API access” option; writing, and reading clock-ins, payroll, requests, polls and signatures, needs “API Pro”.
The full key is shown only once: keep it like a password. You can set it aside, change its rights or revoke it at any time: the assistant loses access at once.
Connecting the assistant
Connector address: https://app.staff-flow.cloud/api/v1/mcp (HTTP transport). The key goes in the “Authorization: Bearer …” header (or “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, or any app that runs local connectors (claude_desktop_config.json file, with Node.js installed):
{
"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…"}
}
}
}
Other MCP-compatible software: give it the address and header above. For developers, each message is a JSON-RPC 2.0 POST request:
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"}}}
Key rights
Each feature has a read right (“x:read”) and, where useful, a write right (“x”) that includes reading. The assistant only sees the tools its key allows; a tool outside its rights returns a 403 error and nothing is done.
Rights: catalog (company: sites, positions, teams, staffing rules), members (employees), shifts (schedule), publish, absences, requests, news (announcements), clock (clock-ins), payroll, polls, signatures (signature tracking).
Tip: give each assistant the minimum. For an assistant that prepares the schedule without publishing it: shifts and members:read. For a payroll assistant: clock:read and payroll:read.
The 30 tools
| Tool | What it does | Key right | Parameters (* required) |
|---|---|---|---|
| get_company | Name, time zone, sites, positions, teams and their members. | catalog:read | — |
| list_members | People (current and former): SF ID, employee number, position, role, dates. | members:read | — |
| get_roles | Role hierarchy: names, ranks, privileges. | members:read | — |
| get_shifts | Published shifts over the period. | shifts:read | from, to |
| get_hours | Published hours per person. | shifts:read | from, to |
| get_coverage_gaps | Time slots short of people. | shifts:read | from, to |
| get_absences | Approved leave and unavailability. | absences:read | from, to |
| create_shifts | Creates shifts as drafts; “publish” publishes only those. Reports overlaps, absences and legal limits. | shifts (+ publish) | shifts*[day*, start*, end*, person | team, site, position, note, location], publish, force |
| update_shift | Edits a shift: only the given fields change; it goes back to draft. | shifts (+ publish) | id*, day, start, end, person, site, position, note, location, publish, force |
| delete_shift | Deletes a shift. | shifts (+ publish) | id*, publish |
| publish_schedule | Publishes the given shifts (“shifts”), otherwise all drafts: employees are notified. | publish | shifts, force |
| import_employees | Adds employees: each gets an invitation code and QR code. “dryRun”: preview without creating anything. | members | rows*[name*, number, position, site], dryRun |
| list_invitations | Pending invitations (code, QR code link). | members | — |
| set_employee_profile | Employee number and/or usual position; an omitted field is kept. | members | person*, employeeNumber, position |
| add_to_team | Adds a person to a team. | members | team*, person* |
| remove_from_team | Removes a person from a team. | members | team*, person* |
| create_site | Creates a site, optionally under a parent site. | catalog | name*, parent |
| create_position | Creates a position (job). | catalog | name* |
| create_team | Creates a team. | catalog | name* |
| add_coverage_rule | Minimum number of people per weekday and time slot. | catalog | weekdays*, start*, end*, min*, site, position, label |
| post_announcement | Posts an announcement, with a deadline if needed. | news | body*, title, audience, endsAt |
| list_pending_requests | Pending requests: swaps, leave, unavailability. | requests:read | — |
| decide_request | Approves or refuses a request. | requests | id*, approve* |
| get_clock_events | Clock-ins over the period (kiosk, phone, manual entry). | clock:read | from, to |
| get_timesheet | Timesheet: planned and clocked minutes, leave. | clock:read | from, to |
| add_clock_event | Enters a forgotten clock-in or clock-out (kept in the history). | clock | person*, at*, kind* (in | out), note |
| get_payroll_preview | Indicative payroll preview (not a payslip). | payroll:read | from, to, planned |
| list_polls | Polls and results. | polls:read | — |
| create_poll | Creates a poll for everyone or a chosen audience. | polls | question*, options* (2–10), multi, anonymous, closesAt, audience |
| list_signatures | Signature tracking: signed, declined, pending. | signatures:read | — |
Naming people, places and times
A person: their SF ID (SF-…), shown in their profile and in list_members, or their employee number. A site, position or team: its exact name or its id.
Dates: YYYY-MM-DD. Times: “HH:MM”; an end before the start means the next day (22:00 → 06:00). Clock-ins and deadlines: ISO 8601 date and time (2026-10-26T07:58:00+01:00). Everything is in the company time zone.
Period (from, to): without “from”, since the company was created; without “to”, up to today.
Audience of an announcement or poll: “everyone”: true, or lists of “sites”, “positions”, “teams”, “roles”, “users”. With no audience, the announcement goes to everyone.
Example shifts for create_shifts (a person, a team, an open shift with a place):
{
"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
}
Drafts and publishing
Shifts created or edited by the assistant arrive as drafts: managers see them in the app, adjust them, then publish. Employees see nothing before publishing.
With the “publish” right, the assistant can publish: “publish”: true in create_shifts, update_shift or delete_shift publishes only those shifts; publish_schedule with “shifts” publishes those. Other drafts in progress stay untouched. Without the right, publishing is refused (403).
Each creation or edit returns its problems (“warnings”): overlap with another shift of the person, here or in another company, approved absence, legal limit exceeded. If there are any, publishing is refused and the shift stays a draft: the assistant tells you, and publishes with “force”: true only after you confirm.
Errors
| Code | Meaning |
|---|---|
| 400 | Invalid data: date, time, missing field, unknown person, site, position or team, deadline in the past. Nothing is created for that item. |
| 401 | Key missing, wrong or revoked. |
| 402 | Required option not active (“API access” or “API Pro”). |
| 403 | The key does not have the right needed. |
| 404 | Shift, request or item not found. |
| 429 | Too many calls: try again after the delay given. |
The assistant receives the error in plain text (“Error 403: …”) and can explain it to you or fix its request.
History and security
Every call from the assistant is logged in Settings → API access → Logs: date, key, plain-language action, result, IP address, and the before and after of an edit. Writes also appear in the company history with the key name.
The assistant never gets passwords, employees' e-mail addresses, signature images or signers' IP addresses. Data goes through the assistant you choose: check its terms before connecting your company.