Serveur MCP

CodFlow expose un serveur distant Model Context Protocol nommé CodFlow CRM. Les clients IA peuvent lister les commandes, clients, produits et expéditions d'une boutique, et exécuter des actions d'écriture avec les mêmes permissions que l'utilisateur connecté au tableau de bord.

Le serveur est joignable à :

Environnement	URL
Production	`https://api.codflow.store/mcp`
Local	`http://localhost:8787/mcp`

L'endpoint est protégé par OAuth. Un client ne peut pas appeler un outil sans jeton d'accès valide, et le jeton porte les scopes CodFlow de l'utilisateur.

Fonctionnement de l'autorisation

Le serveur MCP utilise le modèle de ressource protégée OAuth 2.1 :

Le serveur publie les métadonnées de ressource protégée et de serveur d'autorisation aux emplacements standard OAuth well-known.
Les clients découvrent automatiquement les deux documents depuis l'endpoint MCP.
Le serveur prend en charge l'enregistrement dynamique des clients sur /oauth/register et les Client ID Metadata Documents.
L'endpoint d'autorisation est /authorize ; les jetons sont émis sur /oauth/token.
Les jetons d'accès durent 1 heure ; les jetons de rafraîchissement durent 30 jours.

Lorsqu'un client se connecte, il ouvre l'écran de consentement CodFlow. Connectez-vous avec le compte du tableau de bord dont l'agent doit utiliser les données et les permissions. L'écran affiche les scopes demandés, et le serveur n'accorde que les scopes que l'utilisateur possède réellement. Un administrateur peut accorder n'importe quel scope demandé.

Le serveur déduit sa ressource OAuth de WORKER_SELF_URL. Pour les tests locaux, assurez-vous que cette valeur correspond à l'origine utilisée par votre client (http://localhost:8787).

Connecter un client

Ouvrez les réglages MCP ou de connecteur de votre client

Ajoutez un serveur MCP distant. Utilisez l'URL de production, ou l'URL locale pendant le développement.
Démarrez la connexion

Le client découvre les métadonnées OAuth et ouvre l'écran de connexion et de consentement CodFlow.
Approuvez les scopes

Connectez-vous avec le compte sous lequel l'agent doit agir. Vérifiez les scopes. Le serveur n'en accordera pas plus que ce que le compte possède déjà.
Listez les outils

Une fois le callback terminé, demandez au client de lister les outils CodFlow. Seuls les outils autorisés par les scopes du jeton sont enregistrés, donc le modèle ne voit jamais un outil qu'il ne peut pas appeler.

Configuration du client

{
  "mcpServers": {
    "codflow": {
      "url": "https://api.codflow.store/mcp"
    }
  }
}

Utilisez la même configuration avec http://localhost:8787/mcp pour un serveur local. Le chemin exact des réglages varie selon le client ; l'URL et le flux OAuth sont identiques.

Outils

Les outils sont regroupés par domaine et filtrés par les mêmes scopes que l'API REST. Quelques exemples :

Domaine	Exemples d'outils
Clients	`listCustomers`, `getCustomerDetails`, `findCustomerByPhone`, `getCustomerOrderHistory`
Produits	`listProducts`, `getProductDetails`, `createNewProduct`, `updateProductDetails`
Commandes	`listOrders`, `getOrderDetails`, `createOrder`, `updateOrderStatus`
Expéditions	`getShipment`, `handOffOrderToCarrier`, `reportShipmentEvent`
Livraison	Chauffeurs, paiements des chauffeurs, sociétés de livraison et profils d'expédition
Catalogue	Variantes, groupes de produits, stock, offres et coupons
Vitrine	Pages d'atterrissage, avis, groupes de clients et étiquettes de clients
Référence	Wilayas et communes

Chaque outil possède un schéma d'entrée typé et, lorsqu'il renvoie des données structurées, un schéma de sortie. Le client reçoit des titres lisibles et des annotations de sécurité avec la définition de l'outil.

Permissions et sécurité

Filtrage à l'enregistrement. Un outil n'est enregistré que si le jeton possède le scope requis. Un modèle ne peut ni découvrir ni appeler un outil hors des permissions de l'utilisateur.
Contournement administrateur. Le jeton d'un administrateur peut accorder tous les scopes ; le jeton d'un membre du staff ne peut accorder que les scopes qu'il possède.
Annotations destructives. Les suppressions, ajustements de stock, changements de statut de commande, règlements et remises aux transporteurs sont marqués destructiveHint: true. Les clients MCP qui prennent en charge la confirmation devraient demander confirmation avant de les exécuter ; vérifiez les réglages de confirmation de votre client.
Piste d'audit. Les appels d'outils effectués via MCP sont enregistrés dans le journal d'activité au nom de l'utilisateur connecté.
Limitation de débit. Les appels d'outils sont limités par utilisateur ou par sujet client.
Révocation. Révoquez une connexion depuis MCP dans le tableau de bord. L'API de gestion sous-jacente se trouve sous /api/mcp :
- GET /api/mcp/me — vos connexions
- DELETE /api/mcp/connections/{clientId} — révoquer votre connexion
- GET /api/mcp/team — connexions de l'équipe (admin)
- DELETE /api/mcp/connections/{clientId}/users/{userId} — révoquer la connexion d'un utilisateur (admin)

Dépannage

Aucun outil n'apparaît. Le jeton n'a peut-être aucun scope, ou le rôle de l'utilisateur ne couvre aucun domaine d'outils. Reconnectez-vous et approuvez au moins un scope.
401 avec un challenge WWW-Authenticate. Le client n'a pas de jeton valide. Laissez-le relancer le flux OAuth ; ne collez pas une clé API du tableau de bord dans l'URL MCP.
403 lors d'un appel d'outil. Les scopes du jeton ne couvrent pas cet outil, ou le compte est devenu inactif. Vérifiez l'utilisateur dans le tableau de bord.
Un client local ne termine pas OAuth. Vérifiez que WORKER_SELF_URL correspond à l'URL configurée et que le client peut joindre http://localhost:8787.

Le serveur MCP est distinct de l'API REST. Il n'apparaît pas comme opérations dans la référence API ; utilisez ce guide pour son endpoint et son comportement OAuth.

Webhooks des transporteurs Architecture