Déployez des agents plus sûrs avec la documentation Flowtly MCP

Rester à jour

1. Exécutez la commande de synchro après chaque mise à jour MCP.
2. Redémarrez votre stack d’agents pour appliquer les nouvelles capacités.
3. Ajoutez cette page en favori pour les dernières informations MCP.

Contenu

• Règles d’authentification et clés API pour les endpoints MCP.
• Schémas des ressources pour la base de connaissances, le blog, les release notes, les investisseurs et les mises à jour produit.
• Payloads JSON-RPC et conseils de lecture/écriture pour les agents.
• 14 résumés logiques pour les analyses calculées.
• Charges utiles JSON-RPC, exemples de code et conseils d'intégration.

Démarrage rapide

• Étape 1 — Obtenir un jeton : Naviguez vers Flowtly Workspace → Agent Tokens et générez un jeton client.
• Étape 2 — Initialiser : POST à https://mcp.flowtly.eu/mcp avec {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}}
• Étape 3 — Lire les données : POST {"jsonrpc":"2.0","id":"read-1","method":"resources/work-times/read","params":{"uri":"/api/work-times"}}
• Étape 4 — Écrire des données : 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\"}"}]}}
• Toutes les requêtes utilisent Authorization: Bearer <YOUR_TOKEN> et Content-Type: application/json.

Transport et authentification

• Endpoints : POST /mcp (entrée JSON-RPC), GET /health (liveness), POST /api/chat (proxy console ; nécessite Authorization: Bearer )
• Headers : Authorization Bearer token (préféré ; bascule sur FLOWTLY_API_KEY), l’en-tête instance est optionnel et transmis
• Content-Type : application/json
• Body : JSON-RPC 2.0 { "jsonrpc": "2.0", "id": "...", "method": "...", "params": {...} }
• CORS : Les identifiants sont autorisés uniquement depuis https://workspace.flowtly.eu. Ne jamais combiner Access-Control-Allow-Origin: * avec Access-Control-Allow-Credentials: true.
• API en amont : https://api.flowtly.eu — le serveur MCP proxyfie toutes les requêtes vers l'API REST de Flowtly.

initialize

• Négocie les capacités et namespaces.
• Exemple de params : { "protocolVersion": "2024-11-05" }
• Retourne les capacités (list, read, write) et les namespaces (work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests).
• Espaces de noms disponibles : 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

• Méthode : resources/{namespace}/list (namespace par défaut : work-times si omis)
• Les namespaces incluent work-times, projects, employees, vacations, holidays, responsibilities, cost-groups, logical, project-rates, transactions, transaction-attachments, suppliers, organization, candidates, resource-requests.
• Renvoie les URIs par namespace (voir le détail ci-dessous).
• Exemple : {"jsonrpc":"2.0","id":"list-1","method":"resources/projects/list","params":{}}

resources/read

• Méthode : resources/{namespace}/read (namespace par défaut : work-times).
• Params incluent uri, ex. /api/work-times
• allowPrefixes autorise les correspondances cross-namespace ; {current} pointe vers /api/employees/me.
• Certaines ressources ajoutent des valeurs par défaut (work-times ajoute des bornes de dates ; employees ajoute itemsPerPage ; holidays/vacations ajoutent des valeurs de pagination).
• Responsibilities suit jusqu’à 10 liens @id pour enrichir titre/nom.
• Le namespace logical renvoie des synthèses serveur plutôt que des payloads bruts.
• Renvoie le payload contents de l’API Flowtly sous-jacente.
• Réponse : {"jsonrpc":"2.0","id":"...","result":{"contents":[{"uri":"...","text":"{...}","mimeType":"application/json"}]}}

resources/write

• Seules les ressources avec allowWrite acceptent l’écriture ; POST sauf si l’URI se termine par un id (dans ce cas PATCH avec application/merge-patch+json).
• /api/.../create force un POST même si un id est présent ; vous pouvez forcer le type via params.contentType.
• Assistant d’écriture logical : resources/logical/write gère /logical/recruiting/resource-requests/update?id= et /logical/recruiting/resource-request-candidates/update?id= (PATCH).
• Convention IRI : params.uri utilise les chemins /api/..., mais les références d'entités au sein des charges utiles JSON doivent utiliser des IRI en amont (par exemple "project": "/projects/1", et non "/api/projects/1").
• Espaces de noms inscriptibles : work-times, holidays (holiday-requests), transactions, transaction-attachments, suppliers (contractors), budgets, budget-groups, candidates, candidate-notes, resource-requests, resource-request-candidates.
• Assistants d'écriture logique : resources/logical/write prend en charge /logical/work-times/log (POST à /api/work-times), /logical/recruiting/resource-requests/update?id=<id> et /logical/recruiting/resource-request-candidates/update?id=<id> (PATCH).

Agents intégrés

• EmployeeAgent (employee) : Opérations quotidiennes — enregistrer les heures de travail, vérifier les vacances, voir les affectations. Accès : tout utilisateur authentifié (délimité par jeton/instance).
• ManagerAgent (manager) : Support pour les chefs de projet/ingénieurs — tarifs, personnel, coûts, approbations. Nécessite : rôle de project_manager ou d'administrateur.
• ExecutiveAgent (executive) : Aperçus pour la direction — KPI, budgets, consolidations, approbations. Nécessite : rôle d'administrateur, d'exécutif, de directeur, de vice-président ou de direction générale.
• HRManagerAgent (hr) : RH et congés — soldes de vacances, historique des congés, jours fériés de l'équipe. Accès : tout utilisateur authentifié.
• AccountancyAgent (accountancy) : Requêtes financières — lister les transactions, résumer les montants. Ne jamais afficher les URL de pièces jointes. Accès : tout utilisateur authentifié.
• RecruiterAgent (recruiter) : Recrutement — lister les postes ouverts, rechercher/créer des candidats, attacher à des postes, ajouter des notes. Nécessite : rôle de candidates_manager, d'administrateur ou de recruteur.
• OnboardingAgent (onboarding) : Guide pour les nouveaux utilisateurs — aide à la configuration, navigation, réponses à "où trouver X". Accès : tout utilisateur authentifié.
• TechAgent (tech) : Configuration technique — demandes d'identifiants MCP/ChatGPT. Génère des identifiants client par utilisateur après approbation de l'administrateur. Accès : ouvert à tous les rôles (sera renforcé).
• Sélection d'agent : Utilisez employee pour les tâches personnelles ; hr pour les congés/vacances ; manager pour le personnel/les coûts ; executive pour les KPI ; accountancy pour les finances ; recruiter pour les candidats ; onboarding pour la configuration.
• Modèle d'accès : Les vérifications de rôle utilisent les rôles/autorités/permissions de Flowtly. Les agents restreints refusent les actions lorsqu'aucun rôle requis ne correspond. Tous les agents utilisent uniquement l'outil API MCP — pas de services externes.

Namespace logical (/logical/*)

• Synthèses en lecture seule : work-times, employees, projects, employee-work-times, project-rates, transactions, project-profitability.
• Synthèses recrutement : company-onboarding/status, recruiting/open-roles, recruiting/candidates.
• Synthèses congés : logical/holidays.
• Exemple : /logical/work-times/summary supporte date[after]/date[before] (7 derniers jours par défaut).
• Tarifs de projet : /logical/project-rates/summary — fiches tarifaires et aperçu des tarifs de facturation.
• Transactions : /logical/transactions/summary — totaux des dépenses, catégorisation et tendances.
• Rentabilité des projets : /logical/project-profitability/summary — revenus versus coûts par projet.
• Groupes budgétaires : /logical/budget-groups/summary — allocations des groupes budgétaires et état de consommation.
• Budgets : /logical/budgets/summary — utilisation individuelle du budget et alertes.
• Intégration de l'entreprise : /logical/company-onboarding/status — progression de la configuration de l'espace de travail et étapes en attente.
• Postes ouverts : /logical/recruiting/open-roles — demandes de ressources non pourvues et pipeline de recrutement.
• Candidats : /logical/recruiting/candidates — répartition des candidats par étape du pipeline.
• Jours fériés : /logical/holidays — données agrégées sur les congés et disponibilité de l'équipe.
• Journal des temps de travail (écriture) : /logical/work-times/log — POST crée une entrée de temps de travail via /api/work-times.

Mise en cache et performances

• Cache logique Redis : Cache optionnel pour les lectures logiques. Peut partager Redis avec l'API principale pour les schémas d'invalidation.
• Variables d'environnement : MCP_LOGICAL_CACHE_ENABLED (activé automatiquement si l'URL Redis existe), MCP_LOGICAL_CACHE_REDIS_URL (valeurs de remplacement : REDIS_URL, CACHE_REDIS_URL).
• Format de clé : Préfixe mcp:logical:v1: — délimité par instance + principal, inclut un URI logique normalisé. Configurez le préfixe via MCP_LOGICAL_CACHE_PREFIX.
• TTL : 86400 secondes (24 heures). Configurez via MCP_LOGICAL_CACHE_TTL_SECONDS.

Forme des erreurs

• { "jsonrpc": "2.0", "id": "...", "error": { "code": -32000, "message": "Upstream Flowtly API failed", "data": { "status": 502 } } }
• Codes d'erreur courants : -32700 (erreur d'analyse), -32600 (requête invalide), -32601 (méthode introuvable), -32000 (défaillance de l'API en amont).
• Le champ data.status reflète le code de statut HTTP de l'API Flowtly en amont lorsqu'il est disponible.

Notes

• allowPrefixes permet à resources/read d’accepter les URIs qui commencent par les préfixes autorisés.
• Référence type OpenAPI disponible dans public/mcp/openapi.json.
• Contrats d'intention LLM : Modèles de routeur + gestionnaire documentés dans docs/llm-intent-architecture.md, implémentés dans packages/agent/src/intents/contract.ts.
• Pagination : Les valeurs par défaut sont appliquées automatiquement par espace de noms. Outrepassez avec des paramètres de requête explicites si nécessaire.

resources/list par namespace