Підключайте ШІ-інструменти до Flowtly через MCP лише для читання

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

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

Що всередині

• Правила автентифікації, CORS та транспорту для MCP-ендпоїнта.
• Простори імен ресурсів лише для читання з операціями списку та читання.
• OAuth 2.0 із Dynamic Client Registration для підключення в один крок.
• 16 інструментів лише для читання у 10 просторах імен ресурсів.
• JSON-RPC пейлоади, приклади коду та поради з інтеграції.

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

• Крок 1 — Підключення (OAuth): Додайте https://mcp.flowtly.eu як конектор у вашому інструменті ШІ та авторизуйте доступ лише для читання. У Claude Code: claude mcp add --transport http flowtly https://mcp.flowtly.eu/mcp. Повний посібник: Підключення інструментів ШІ.
• Крок 2 — Ініціалізація: Здійсніть POST-запит до https://mcp.flowtly.eu/mcp з {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}} — сервер відповідає можливостями {"tools":{}}.
• Крок 3 — Перелік інструментів: Здійсніть POST-запит {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}}, щоб виявити доступні інструменти лише для читання (наприклад, invoices.list, transactions.list, counterparties.list).
• Крок 4 — Виклик інструмента: Здійсніть POST-запит {"jsonrpc":"2.0","id":"call-1","method":"tools/call","params":{"name":"transactions.list","arguments":{}}}. Результат надходить як result.content[].text (рядок JSON).
• Усі запити використовують 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" }
• Можливості у відповіді: {"tools":{}}
• Виявлення інструментів: викличте tools/list, щоб отримати доступні інструменти лише для читання та їхні вхідні дані за схемою JSON-Schema.

tools/list

• Метод: tools/list — повертає кожен інструмент лише для читання, доступний для вашого підключення.
• Інструменти (16): invoices.list/get, transactions.list, bankAccounts.list/get, counterparties.list/get, suppliers.list, contracts.list/get/paymentScheduleLines, attachments.list/get, costGroups.list, taxGroups.list, projects.list.
• Кожен запис має name, description та inputSchema у форматі JSON-Schema, що описує його аргументи.
• Приклад: {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}}

tools/call

• Метод: tools/call — викликає інструмент за назвою з його аргументами.
• Params: {"name":"<tool>","arguments":{...}}, наприклад {"name":"invoices.list","arguments":{}}.
• Аргументи: дотримуйтесь inputSchema інструмента з tools/list (фільтри, пагінація, ids). Пропустіть для розумних значень за замовчуванням.
• Лише читання: кожен інструмент лише читає дані — інструментів запису немає.
• Спочатку виявлення: викличте tools/list, щоб побачити точні назви інструментів та схеми аргументів перед викликом.
• Пагінація & фільтри: передаються всередині arguments за схемою кожного інструмента (наприклад, діапазони дат, розмір сторінки).
• Окремі записи: інструменти *.get приймають аргумент id та повертають одну сутність; інструменти *.list повертають колекції.
• Відповідь: {"jsonrpc":"2.0","id":"...","result":{"content":[{"type":"text","text":"{...}"}]}} — розберіть content[].text як JSON.

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

• { "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.
• Пагінація: Налаштування за замовчуванням застосовуються автоматично для кожного простору імен. Перевизначте за допомогою явних параметрів запиту за потреби.

Інструменти за простором імен