Connectez vos outils IA à Flowtly avec le MCP en lecture seule

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, de CORS et de transport pour l'endpoint MCP.
• Espaces de noms de ressources en lecture seule avec opérations de liste et de lecture.
• OAuth 2.0 avec Dynamic Client Registration pour une connexion en une étape.
• 16 outils en lecture seule répartis sur 10 espaces de noms de ressources.
• Charges utiles JSON-RPC, exemples de code et conseils d'intégration.

Démarrage rapide

• Étape 1 — Se connecter (OAuth) : Ajoutez https://mcp.flowtly.eu comme connecteur dans votre outil d'IA et autorisez l'accès en lecture seule. Dans Claude Code : claude mcp add --transport http flowtly https://mcp.flowtly.eu/mcp. Guide complet : Connexion des outils d'IA.
• Étape 2 — Initialiser : POST à https://mcp.flowtly.eu/mcp avec {"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05"}} — le serveur répond avec les capacités {"tools":{}}.
• Étape 3 — Lister les outils : POST {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}} pour découvrir les outils en lecture seule disponibles (par ex. invoices.list, transactions.list, counterparties.list).
• Étape 4 — Appeler un outil : POST {"jsonrpc":"2.0","id":"call-1","method":"tools/call","params":{"name":"transactions.list","arguments":{}}}. Le résultat arrive sous la forme result.content[].text (une chaîne JSON).
• 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" }
• Capacités de la réponse : {"tools":{}}
• Découvrir les outils : appelez tools/list pour obtenir les outils en lecture seule disponibles et leur schéma d'entrée JSON-Schema.

tools/list

• Méthode : tools/list — renvoie tous les outils en lecture seule disponibles pour votre connexion.
• Outils (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.
• Chaque entrée comporte un name, une description et un inputSchema JSON-Schema décrivant ses arguments.
• Exemple : {"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{}}

tools/call

• Méthode : tools/call — invoque un outil par son nom avec ses arguments.
• Params : {"name":"<tool>","arguments":{...}}, par ex. {"name":"invoices.list","arguments":{}}.
• Arguments : suivez l'inputSchema de l'outil issu de tools/list (filtres, pagination, ids). Omettez-les pour des valeurs par défaut raisonnables.
• Lecture seule : chaque outil ne fait que lire des données — il n'existe aucun outil d'écriture.
• Découverte d'abord : appelez tools/list pour voir les noms exacts des outils et les schémas d'arguments avant d'appeler.
• Pagination & filtres : passés dans arguments selon le schéma de chaque outil (par ex. plages de dates, taille de page).
• Enregistrements uniques : les outils *.get prennent un argument id et renvoient une entité ; les outils *.list renvoient des collections.
• Réponse : {"jsonrpc":"2.0","id":"...","result":{"content":[{"type":"text","text":"{...}"}]}} — analysez content[].text comme du JSON.

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.

Outils par espace de noms