Guia do conector MCP
Esta página existe em francês, ucraniano e inglês: eis a versão inglesa.
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.