Запускайте безпечніших агентів із документацією Flowtly MCP

Як залишатися в курсі

1. Запускайте команду синхронізації після виходу оновлень MCP.
2. Перезапускайте стек агентів, щоб підхопити зміни можливостей.
3. Додайте цю сторінку в закладки, щоб мати актуальні рекомендації Flowtly MCP.

Що всередині

• Правила автентифікації та API-ключів для MCP-ендпоїнтів.
• Схеми ресурсів для бази знань, блогу, релізів, інвесторів і оновлень продукту.
• JSON-RPC пейлоади та поради щодо запису/читання для агентів.
• 14 логічних зведень для обчислювальної аналітики.
• JSON-RPC пейлоади, приклади коду та поради з інтеграції.

Швидкий старт

• Крок 1 — Отримайте токен: Перейдіть до Flowtly Workspace → Agent Tokens і згенеруйте клієнтський токен.
• Крок 2 — Ініціалізувати: Здійсніть POST-запит до https://mcp.flowtly.eu/mcp з {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Крок 3 — Прочитати дані: Здійсніть POST-запит {"jsonrpc":"2.0","id":"read-1","method":"resources/work-times/read","params":{"uri":"/api/work-times"}}
• Крок 4 — Записати дані: Здійсніть POST-запит {"jsonrpc":"2.0","id":"write-1","method":"resources/work-times/write","params":{"uri":"/api/work-times","contents":[{"text":"{\"date\":\"2026-04-03\",\"seconds\":3600,\"project\":\"/projects/1\",\"description\":\"Support\"}"}]}}
• Усі запити використовують Authorization: Bearer <YOUR_TOKEN> та Content-Type: application/json.

Транспорт і автентифікація

• Ендпоїнти: POST /mcp (вхід JSON-RPC), GET /health (liveness), POST /api/chat (проксі консолі; потрібен Authorization: Bearer )
• Заголовки: Authorization Bearer token (переважно; fallback на FLOWTLY_API_KEY), optional instance header передається далі
• Content-Type: application/json
• Body: JSON-RPC 2.0 { "jsonrpc": "2.0", "id": "...", "method": "...", "params": {...} }
• CORS: Облікові дані дозволені лише з https://workspace.flowtly.eu. Ніколи не комбінуйте Access-Control-Allow-Origin: * з Access-Control-Allow-Credentials: true.
• Вихідний API: https://api.flowtly.eu — сервер MCP проксує всі запити до Flowtly REST API.

initialize

• Узгоджує можливості та простори імен.
• Приклад params: { "protocolVersion": "2024-11-05" }
• Повертає можливості (list, read, write) і простори імен (work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests).
• Доступні простори імен: work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, budget-groups, budgets, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests.

resources/list

• Метод: resources/{namespace}/list (простір імен за замовчуванням: work-times, якщо не вказано)
• Простори імен включають work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests.
• Повертає URI для кожного простору імен (див. розклад нижче).
• Приклад: {"jsonrpc":"2.0","id":"list-1","method":"resources/projects/list","params":{}}

resources/read

• Метод: resources/{namespace}/read (простір імен за замовчуванням: work-times).
• Params включають uri, напр., /api/work-times
• allowPrefixes дозволяє збіги між просторами імен; {current} розвʼязується як /api/employees/me.
• Деякі ресурси додають значення за замовчуванням (work-times додає межі дат; employees додають itemsPerPage; holidays/vacations додають дефолти пагінації).
• Responsibilities проходять до 10 @id посилань, щоб збагачувати title/name.
• Логічний простір імен повертає серверні зведення замість сирих пейлоадів.
• Повертає payload contents з базового Flowtly API.
• Відповідь: {"jsonrpc":"2.0","id":"...","result":{"contents":[{"uri":"...","text":"{...}","mimeType":"application/json"}]}}

resources/write

• Лише ресурси з allowWrite приймають записи; POST, якщо URI не закінчується на id (тоді PATCH з application/merge-patch+json).
• /api/.../create примусово робить POST навіть якщо є id; можна перевизначити тип через params.contentType.
• Допоміжний logical write: resources/logical/write підтримує /logical/recruiting/resource-requests/update?id= та /logical/recruiting/resource-request-candidates/update?id= (PATCH).
• Угода IRI: params.uri використовує шляхи /api/..., але посилання на сутності всередині JSON-даних повинні використовувати вихідні IRI (наприклад, "project": "/projects/1", а не "/api/projects/1").
• Простори імен, що підтримують запис: work-times, holidays (holiday-requests), transactions, transaction-attachments, suppliers (contractors), budgets, budget-groups, candidates, candidate-notes, resource-requests, resource-request-candidates.
• Допоміжні функції логічного запису: resources/logical/write підтримує /logical/work-times/log (POST до /api/work-times), /logical/recruiting/resource-requests/update?id=<id> та /logical/recruiting/resource-request-candidates/update?id=<id> (PATCH).

Вбудовані агенти

• Агент співробітника (employee): Щоденні операції — запис робочого часу, перевірка відпусток, перегляд призначень. Доступ: будь-який автентифікований користувач (обмежений токеном/екземпляром).
• Агент менеджера (manager): Підтримка менеджера проєкту/інженера — ставки, штат, витрати, затвердження. Потрібна роль: project_manager або admin.
• Виконавчий агент (executive): Огляди для керівництва — KPI, бюджети, зведення, затвердження. Потрібна роль: admin, executive, director, vp або c-level.
• Агент менеджера з персоналу (hr): Управління персоналом та відпустками — залишки відпусток, історія відпусток, командні свята. Доступ: будь-який автентифікований користувач.
• Агент бухгалтерії (accountancy): Фінансові запити — список транзакцій, підсумкові суми. Ніколи не відображає URL-адреси вкладень. Доступ: будь-який автентифікований користувач.
• Агент рекрутера (recruiter): Рекрутинг — список відкритих вакансій, пошук/створення кандидатів, прикріплення до вакансій, додавання приміток. Потрібна роль: candidates_manager, admin або recruiter.
• Агент адаптації (onboarding): Допомога новим користувачам — допомога з налаштуванням, навігація, відповіді на запитання «де знайти X». Доступ: будь-який автентифікований користувач.
• Технічний агент (tech): Технічне налаштування — запити облікових даних MCP/ChatGPT. Створює облікові дані клієнта для кожного користувача після схвалення адміністратором. Доступ: відкритий для всіх ролей (буде посилений).
• Вибір агента: Використовуйте employee для особистих завдань; hr для відпусток/відгулів; manager для штатного розкладу/витрат; executive для KPI; accountancy для фінансів; recruiter для кандидатів; onboarding для налаштування.
• Модель доступу: Перевірка ролей використовує ролі/повноваження/дозволи Flowtly. Обмежені агенти відмовляють у діях, якщо жодна необхідна роль не відповідає. Усі агенти використовують лише інструмент MCP API — без зовнішніх сервісів.

Логічний простір імен (/logical/*)

• Зведення лише для читання: work-times, employees, projects, employee-work-times, project-rates, transactions, project-profitability.
• Зведення рекрутингу: company-onboarding/status, recruiting/open-roles, recruiting/candidates.
• Зведення відпусток: logical/holidays.
• Приклад: /logical/work-times/summary підтримує date[after]/date[before] (за замовчуванням останні 7 днів).
• Ставки проєкту: /logical/project-rates/summary — тарифні картки та огляд ставок для виставлення рахунків.
• Транзакції: /logical/transactions/summary — загальні витрати, категоризація та тенденції.
• Прибутковість проєкту: /logical/project-profitability/summary — дохід проти витрат на проєкт.
• Бюджетні групи: /logical/budget-groups/summary — розподіл бюджетних груп та стан використання бюджету.
• Бюджети: /logical/budgets/summary — використання індивідуального бюджету та сповіщення.
• Адаптація компанії: /logical/company-onboarding/status — прогрес налаштування робочого простору та очікувані кроки.
• Відкриті вакансії: /logical/recruiting/open-roles — незаповнені запити ресурсів та етап найму.
• Кандидати: /logical/recruiting/candidates — розподіл кандидатів за етапами найму.
• Свята: /logical/holidays — агреговані дані про відпустки та доступність команди.
• Журнал робочого часу (запис): /logical/work-times/log — POST створює запис про робочий час через /api/work-times.

Кешування та продуктивність

• Логічний кеш Redis: Необов'язковий кеш для логічних читань. Може використовувати спільний Redis з основним API для схем анулювання.
• Змінні середовища: MCP_LOGICAL_CACHE_ENABLED (автоматично вмикається, коли існує URL Redis), MCP_LOGICAL_CACHE_REDIS_URL (резервні варіанти: REDIS_URL, CACHE_REDIS_URL).
• Формат ключа: Префікс mcp:logical:v1: — обмежений екземпляром + принципалом, включає нормалізований логічний URI. Налаштувати префікс через MCP_LOGICAL_CACHE_PREFIX.
• TTL: 86400 секунд (24 години). Налаштувати через MCP_LOGICAL_CACHE_TTL_SECONDS.

Форма помилки

• { "jsonrpc": "2.0", "id": "...", "error": { "code": -32000, "message": "Upstream Flowtly API failed", "data": { "status": 502 } } }
• Поширені коди помилок: -32700 (помилка розбору), -32600 (недійсний запит), -32601 (метод не знайдено), -32000 (збій вихідного API).
• Поле data.status відображає HTTP-код стану з вихідного API Flowtly, коли він доступний.

Нотатки

• allowPrefixes дозволяє resources/read приймати URI, що починаються з дозволених префіксів.
• OpenAPI-стиль довідника доступний у public/mcp/openapi.json.
• Контракти намірів LLM: Шаблони маршрутизатора + менеджера, задокументовані в docs/llm-intent-architecture.md, реалізовані в packages/agent/src/intents/contract.ts.
• Пагінація: Налаштування за замовчуванням застосовуються автоматично для кожного простору імен. Перевизначте за допомогою явних параметрів запиту за потреби.

resources/list за простором імен