Посібник із конектора MCP
Навіщо конектор
Конектор MCP (Model Context Protocol) з'єднує ІІ-асистента, як-от Claude, з вашою компанією в Staff Flow. Ви говорите з ним звичайною мовою: він читає графік, години, відмітки, а також може створювати зміни, оголошення чи затверджувати запити — відповідно до наданих прав.
Приклади: «Хто працює в суботу в локації Центр?», «Постав Марію на касу в понеділок з 8:00 до 16:00», «Скільки годин відпрацювала команда у вересні?», «Затверди відпустку Павла», «Повідом команду Ранок, що інвентаризація в суботу».
Підключити ChatGPT, Claude чи інший асистент без ключа
В асистенті додайте конектор (або застосунок) з адресою https://app.staff-flow.cloud/api/v1/mcp і натисніть «Підключити». Відкриється сторінка Staff Flow: увійдіть, виберіть компанію й натисніть «Дозволити». Готово, без ключа (вхід OAuth, токени з обмеженим терміном, що оновлюються самі).
Компанія вирішує, хто може це робити: привілей «Користуватися своїм ШІ-асистентом» для ролі чи людини (Ролі та привілеї). Асистент має саме привілеї людини; керівник локації читає лише свої локації. Якщо права змінюються, асистент одразу це враховує.
Кожен бачить і відключає своїх асистентів у Налаштування → ШІ-асистенти; власник бачить усіх у Налаштування компанії → Доступ до API → Підключені застосунки.
Що потрібно (API-ключ)
Для програми або конектора на вашому комп'ютері: API-ключ вашої компанії (Налаштування → Доступ до API → Новий ключ). Читання графіка, годин, відсутностей і компанії потребує опції «доступ до API»; запис і читання відміток, зарплати, запитів, опитувань і підписів — «API Pro».
Повний ключ показується лише раз: зберігайте його як пароль. Ключ можна відкласти, змінити його права чи відкликати будь-коли — асистент одразу втрачає доступ.
Підключення асистента
Адреса конектора: https://app.staff-flow.cloud/api/v1/mcp (транспорт HTTP). Ключ передається в заголовку «Authorization: Bearer …» (або «X-Api-Key»).
Claude Code (термінал):
claude mcp add --transport http staff-flow https://app.staff-flow.cloud/api/v1/mcp \
--header "Authorization: Bearer sfk_xxxxxxxx_yyyyyyyy…"
Claude Desktop або будь-яка програма, що запускає локальні конектори (файл claude_desktop_config.json, потрібен Node.js):
{
"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…"}
}
}
}
Інша програма з підтримкою MCP: вкажіть адресу й заголовок вище. Для розробника кожне повідомлення — запит JSON-RPC 2.0 методом 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"}}}
Права ключа
Кожна функція має право читання («x:read») і, де потрібно, право запису («x»), яке включає читання. Асистент бачить лише дозволені інструменти; інструмент поза правами повертає помилку 403, і нічого не відбувається.
Права: catalog (компанія: локації, посади, команди, мінімум людей), members (працівники), shifts (графік), publish (публікація), absences, requests (запити), news (оголошення), clock (відмітки), payroll (зарплата), polls (опитування), signatures (стан підписів).
Порада: давайте кожному асистенту мінімум. Для асистента, що готує графік без публікації: shifts і members:read. Для асистента із зарплати: clock:read і payroll:read.
30 інструментів
| Інструмент | Що робить | Право ключа | Параметри (* обов'язково) |
|---|---|---|---|
| get_company | Назва, часовий пояс, локації, посади, команди та їхні учасники. | catalog:read | — |
| list_members | Люди (поточні й колишні): SF ID, табельний номер, посада, роль, дати. | members:read | — |
| get_roles | Ієрархія ролей: назви, ранги, привілеї. | members:read | — |
| get_shifts | Опубліковані зміни за період. | shifts:read | from, to |
| get_hours | Опубліковані години на людину. | shifts:read | from, to |
| get_coverage_gaps | Проміжки, де бракує людей. | shifts:read | from, to |
| get_absences | Затверджені відпустки й недоступності. | absences:read | from, to |
| create_shifts | Створює зміни як чернетки; «publish» публікує лише їх. Повідомляє про накладання, відсутності й правила. | shifts (+ publish) | shifts*[day*, start*, end*, person | team, site, position, note, location], publish, force |
| update_shift | Змінює зміну: лише передані поля; вона знову стає чернеткою. | shifts (+ publish) | id*, day, start, end, person, site, position, note, location, publish, force |
| delete_shift | Видаляє зміну. | shifts (+ publish) | id*, publish |
| publish_schedule | Публікує передані зміни («shifts»), інакше всі чернетки: працівники отримують сповіщення. | publish | shifts, force |
| import_employees | Додає працівників: кожен отримує код і QR-код запрошення. «dryRun» — перегляд без створення. | members | rows*[name*, number, position, site], dryRun |
| list_invitations | Запрошення в очікуванні (код, посилання на QR-код). | members | — |
| set_employee_profile | Табельний номер і/або звичайна посада; відсутнє поле не змінюється. | members | person*, employeeNumber, position |
| add_to_team | Додає людину до команди. | members | team*, person* |
| remove_from_team | Видаляє людину з команди. | members | team*, person* |
| create_site | Створює локацію, за потреби в межах батьківської. | catalog | name*, parent |
| create_position | Створює посаду. | catalog | name* |
| create_team | Створює команду. | catalog | name* |
| add_coverage_rule | Мінімальна кількість людей за днями й годинами. | catalog | weekdays*, start*, end*, min*, site, position, label |
| post_announcement | Публікує оголошення, за потреби з кінцевим терміном. | news | body*, title, audience, endsAt |
| list_pending_requests | Запити в очікуванні: обміни, відпустки, недоступності. | requests:read | — |
| decide_request | Затверджує або відхиляє запит. | requests | id*, approve* |
| get_clock_events | Відмітки за період (термінал, телефон, ручне введення). | clock:read | from, to |
| get_timesheet | Табель: заплановані й відмічені хвилини, відпустки. | clock:read | from, to |
| add_clock_event | Вносить забуту відмітку (зберігається в історії). | clock | person*, at*, kind* (in | out), note |
| get_payroll_preview | Орієнтовний розрахунок зарплати (не розрахунковий лист). | payroll:read | from, to, planned |
| list_polls | Опитування та результати. | polls:read | — |
| create_poll | Створює опитування для всіх або вибраних людей. | polls | question*, options* (2–10), multi, anonymous, closesAt, audience |
| list_signatures | Стан підписів: підписано, відхилено, в очікуванні. | signatures:read | — |
Як вказувати людей, місця й час
Людина: її ідентифікатор SF (SF-…), видимий у профілі та в list_members, або табельний номер. Локація, посада чи команда: точна назва або ідентифікатор.
Дати: РРРР-ММ-ДД. Час: «ГГ:ХХ»; кінець раніше за початок означає наступний день (22:00 → 06:00). Відмітка й кінцевий термін: дата й час ISO 8601 (2026-10-26T07:58:00+01:00). Усе — у часовому поясі компанії.
Період (from, to): без «from» — від створення компанії; без «to» — до сьогодні.
Аудиторія оголошення чи опитування (audience): «everyone»: true або списки «sites», «positions», «teams», «roles», «users». Без аудиторії оголошення бачать усі.
Приклад змін для create_shifts (людина, команда, вільна зміна з місцем):
{
"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
}
Чернетки й публікація
Зміни, створені чи змінені асистентом, стають чернетками: керівники бачать їх у застосунку, коригують і публікують. Працівники нічого не бачать до публікації.
З правом «publish» асистент може публікувати: «publish»: true у create_shifts, update_shift чи delete_shift публікує лише ці зміни; publish_schedule з «shifts» — лише передані. Інші чернетки не змінюються. Без цього права публікацію буде відхилено (403).
Кожне створення чи зміна повертає проблеми («warnings»): накладання з іншою зміною людини тут чи в іншій компанії, затверджена відсутність, порушене правило. Якщо вони є, публікацію відхилено, зміна лишається чернеткою: асистент попереджає й публікує з «force»: true лише після вашого підтвердження.
Помилки
| Код | Значення |
|---|---|
| 400 | Неправильні дані: дата, час, відсутнє поле, невідома людина, локація, посада чи команда, кінцевий термін у минулому. Для цього елемента нічого не створено. |
| 401 | Ключ відсутній, неправильний або відкликаний. |
| 402 | Потрібна опція неактивна («доступ до API» або «API Pro»). |
| 403 | Ключ не має потрібного права. |
| 404 | Зміну, запит чи елемент не знайдено. |
| 429 | Забагато викликів: повторіть після вказаної затримки. |
Асистент отримує помилку зрозумілим текстом («Error 403: …») і може пояснити її або виправити запит.
Історія та безпека
Кожен виклик асистента записується в Налаштування → Доступ до API → Журнали: дата, ключ, зрозуміла дія, результат, IP-адреса, а для змін — до і після. Записи також з'являються в історії компанії з назвою ключа.
Асистент ніколи не отримує паролі, e-mail працівників, зображення підписів чи IP-адреси підписантів. Дані проходять через вибраного вами асистента: перевірте його умови, перш ніж підключати компанію.