Copier pour l’IA

Serveur MCP (Model Context Protocol)

Le standard ouvert pour mettre des outils financiers à la disposition de l’intelligence artificielle agentique.

Qu’est-ce que MCP ?

Le Model Context Protocol (MCP) est un standard universel qui permet aux assistants d’intelligence artificielle de se connecter à des sources de données sécurisées.

En configurant le serveur MCP de Cord, vous permettez à des agents comme Claude ou à des assistants intégrés aux IDE (comme Cursor) d’interagir naturellement avec votre entreprise.

Questions que vous pouvez poser à l’IA une fois connectée :

• « Extrais les besoins du PDF joint et génère un devis dans Cord pour ce client. »
• « Passe en revue les devis expirés des 30 derniers jours et rédige-moi des e-mails de relance cordiaux. »
• « Cherche le client Distribuidora El Zarco et prépare un brouillon avec ces 3 lignes. »

Configurer la connexion

L’authentification de votre client IA se fait avec votre clé API Cord standard (sk_live_… / sk_test_…) — la même que celle qu’utilise l’API REST.

1. Allez dans Paramètres › MCP dans l’interface de Cord. Cet onglet se trouve dans la section Développeurs de l’index des Paramètres, qui apparaît lorsque vous activez le Mode développeur dans Votre compte › Préférences.
2. Un tableau d’état en haut de la page vous indique si vous avez déjà une clé active et, si un client IA est déjà connecté, quand il l’a utilisée pour la dernière fois. Si vous n’en avez pas, le bouton « Créer une clé pour MCP » génère une clé en écriture avec les groupes de lecture et d’écriture de brouillons, sans quitter la page — elle est collée automatiquement dans la configuration ci-dessous. Copiez-la à ce moment-là : elle ne sera plus affichée. Pour choisir des groupes ou des outils isolés, ou pour autoriser les actions à effet externe, créez ou modifiez la clé dans l’onglet Clés API du Cord Workbench (voir droits par outil).
3. Copiez la configuration JSON du client MCP affichée à l’écran.
4. Collez cette configuration à l’emplacement local correspondant à votre client (par exemple, le fichier claude_desktop_config.json si vous utilisez l’application Claude for Desktop).

Deux façons de vous connecter

Streamable HTTP (recommandé) — POST https://cordhq.app/api/mcp avec l’en-tête Authorization: Bearer sk_live_…. Sans session : chaque message JSON-RPC est une requête HTTP indépendante. C’est ce qu’attendent la plupart des clients MCP modernes.

HTTP + SSE (ancien mode, conservé pour les clients plus anciens) — GET https://cordhq.app/api/mcp/sse ouvre une connexion de longue durée et indique où envoyer les messages (POST /api/mcp/message?sessionId=…). Chaque message POST doit porter le même Authorization: Bearer que celui utilisé pour ouvrir la session — le sessionId de l’URL ne suffit pas (il circule en clair et peut se retrouver exposé dans les journaux de proxys intermédiaires), et la clé doit appartenir à la même organisation que celle qui a ouvert la session.

Droits par outil

Chaque outil appartient à un groupe et à une ressource, selon le même modèle que les clés restreintes :

Groupe	Outils	Clé sans liste
Lecture	listar_cotizaciones, detalle_cotizacion, cartera_vencida, resumen_negocio, buscar_cliente, listar_productos, listar_facturas, detalle_factura, listar_workflows_manuales, listar_eventos, estado_configuracion, validar_datos_fiscales, validar_apariencia	Autorisés
Écriture de brouillons	crear_cotizacion_borrador, crear_factura_borrador, crear_cliente, crear_tarea, registrar_promesa_pago, proponer_configuracion	Autorisés avec une clé en écriture
Actions à effet externe	enviar_cotizacion, aprobar_cotizacion, rechazar_cotizacion, registrar_pago_cotizacion, actualizar_cliente, correr_workflow, simular_evento	Bloqués : seulement avec un droit explicite, et chaque appel attend une validation

Quand vous créez ou modifiez une clé dans l’onglet Clés API du Workbench, vous choisissez des groupes entiers ou, dans un groupe, des outils isolés. Un groupe couvre aussi les outils que Cord y ajoutera plus tard ; un outil isolé, seulement lui-même. Une clé sans liste, comme toutes celles créées avant les droits par outil, garde la lecture et les brouillons selon son niveau et ne peut demander aucune action à effet externe tant que personne ne l’y autorise.

• Le niveau prime toujours : une clé en lecture seule n’utilise pas les brouillons même s’ils sont dans sa liste, et une clé restreinte (rk_) applique le niveau de chaque ressource à chaque outil (listar_facturas demande facturas: read ; crear_cotizacion_borrador, cotizaciones: write).
• tools/list ne renvoie que ce que la clé peut appeler. Si un client en appelle un autre, la réponse est une erreur d’outil qui indique lequel manque et où l’autoriser.
• contexto_cuenta et buscar_documentacion sont toujours disponibles : ils identifient le compte et cherchent dans cette documentation, sans données clients.

actualizar_cliente fait partie des actions à effet externe même s’il n’écrit à personne : Cord utilise l’e-mail et les données fiscales du client pour envoyer relances, factures récurrentes et recouvrement sans autre vérification, donc les modifier a un effet en dehors de Cord.

Actions soumises à validation

Une action à effet externe ne s’exécute pas quand l’agent l’appelle, même si la clé l’autorise et que le client MCP ne demande pas de confirmation. Cord enregistre une demande et répond :

{
  "estado": "pendiente_de_aprobacion",
  "aprobacion_id": "7c1e4b2a-5d3f-4a8e-9b6c-2f1d0e3a4b5c",
  "aprobacion_url": "https://cordhq.app/app/ajustes/mcp/solicitudes?modo=vivo#sol-7c1e4b2a-5d3f-4a8e-9b6c-2f1d0e3a4b5c",
  "vence": "2026-10-18T16:04:00.000Z",
  "mensaje": "No se ejecutó todavía: una persona con acceso a Cord tiene que aprobarla. …"
}

1. L’agent partage aprobacion_url avec l’utilisateur.
2. Dans Paramètres › MCP › Demandes, une personne ayant le droit Paramètres et le droit de l’action dans l’app (Devis pour envoyer ou enregistrer un paiement, Validations pour approuver ou refuser, Clients pour mettre à jour un client, Devis ou Recouvrement pour un workflow selon son objet, Paramètres pour simuler un webhook) voit le document, ce qui changerait et les données envoyées par l’agent, puis valide ou refuse.
3. À la validation, Cord exécute l’action une seule fois, avec le même gestionnaire que d’habitude. Deux personnes qui valident en même temps ne l’exécutent pas deux fois. Refuser n’exécute rien.
4. Pour connaître le résultat, l’agent répète l’appel avec la même idempotency_key : la réponse indique estado ejecutada (avec ce que l’action a renvoyé dans resultado), fallida (avec le motif dans error), rechazada ou vencida.

La demande expire après 72 heures sans décision. Répéter le même appel avec les mêmes arguments renvoie la demande en attente au lieu d’en créer une autre, et une organisation reçoit au plus 30 demandes par heure. Si la clé est révoquée, expire ou perd l’outil avant la décision, la demande ne peut plus être validée. Avec une clé de test, la demande vit dans l’environnement de test et le lien l’indique avec ?modo=prueba.

Outils disponibles

Outil	Effet	Droit
listar_cotizaciones	Liste les devis, avec un filtre facultatif par statut.	lecture
detalle_cotizacion	Détail complet d’un devis : lignes, totaux, chronologie.	lecture
cartera_vencida	Créances ÉCHUES : montant, ancienneté, détail par client.	lecture
resumen_negocio	KPI, entonnoir de conversion, prévision du pipeline, utilisation de l’offre.	lecture
buscar_cliente	Recherche dans l’annuaire par entreprise, contact, RFC ou e-mail. Chaque client inclut language, la langue de ses documents (null = celle de l’organisation). Paginé.	lecture
listar_productos	Catalogue de produits (id, SKU, nom, unité, prix catalogue). Paginé.	lecture
crear_cotizacion_borrador	Crée un devis en BROUILLON (sans l’envoyer). Idempotent si vous transmettez idempotency_key.	brouillons
listar_facturas	Liste les factures de Cord Invoicing avec leur solde et leur statut (draft|open|paid|void|uncollectible|overdue). Filtre par statut, par client ou par texte libre. Paginé.	lecture
detalle_factura	Détail complet d’UNE facture : lignes, émetteur, destinataire, taxes, taux de change déclaré, solde et paiements reçus.	lecture
crear_factura_borrador	Crée une facture en BROUILLON pour un client, sans devis préalable. Disponible dans toutes les offres, y compris l’offre Gratuite.	brouillons
enviar_cotizacion	Demande d’envoyer au client un devis en brouillon (e-mail avec le lien), dans la langue des documents du client. Attend une validation. Dans l’offre Gratuite, consomme l’un des envois du mois.	avec validation
aprobar_cotizacion	Demande de marquer comme approuvé un devis envoyé ou consulté. Attend une validation.	avec validation
rechazar_cotizacion	Demande de marquer comme refusé un devis envoyé ou consulté. Attend une validation.	avec validation
registrar_pago_cotizacion	Demande d’enregistrer qu’un devis approuvé a été payé en dehors de Cord ; à l’exécution, annule ses paiements en ligne en attente. Accepte metodo_pago. Attend une validation.	avec validation
crear_cliente	Crée un client (entreprise, contact, e-mail, téléphone, identifiant fiscal, conditions, pays et langue des documents : es, en, pt, fr, de ou null).	brouillons
actualizar_cliente	Demande de modifier les coordonnées d’un client, language compris. Ne met à jour que ce que vous envoyez ; ne touche jamais au crédit, au niveau ni à la remise. Ce qui a déjà été envoyé garde sa langue. Attend une validation.	avec validation
crear_tarea	Crée une tâche de suivi : titulo (obligatoire), date d’échéance fecha au format YYYY-MM-DD, cotizacion_id et factura_id facultatifs. Elle est créée sans responsable et avec une priorité normale ; ces valeurs se modifient dans l’application.	brouillons
registrar_promesa_pago	Enregistre la date à laquelle le client a promis de payer un devis. N’encaisse rien.	brouillons
listar_workflows_manuales	Liste les workflows actifs « Vous le lancez », par objet (quote ou invoice).	lecture
correr_workflow	Demande de lancer un workflow « Vous le lancez » sur jusqu’à 50 devis ou factures, avec la version publiée et ses règles. Attend une validation ; à l’exécution, indique le nombre d’exécutions démarrées.	avec validation
listar_eventos	Historique de l’activité (devis, factures, clients, tâches, promesses), filtrable par type ou par objet. Paginé.	lecture
contexto_cuenta	Entreprise, pays, devise, langue, fuseau horaire, offre, et si la clé est de test ou live. À appeler en premier.	lecture
proponer_configuracion	Propose un profil, une marque, des taxes, un catalogue et des modèles à partir du site web, d’une description ou de la liste de prix (base64, jusqu’à 3 Mo). N’applique rien : renvoie review_url pour qu’une personne l’approuve.	brouillons
estado_configuracion	État d’une proposition (propuesto, aplicado, descartado, fallido) et résultat par section.	lecture
validar_datos_fiscales	Valide le RFC, le régime fiscal, l’usage du CFDI et le code postal (Mexique), le NIF/NIE/CIF (Espagne) ou l’EIN (États-Unis) avec les mêmes règles qu’à l’émission.	lecture
validar_apariencia	Valide un objet appearance d’Elements et indique quelles clés Cord écarterait.	lecture
simular_evento	Demande de déclencher un webhook de test via le véritable moteur d’envoi. Clés de test uniquement. Attend une validation.	avec validation
buscar_documentacion	Recherche dans cette documentation et renvoie les pages les plus pertinentes avec un extrait et l’URL.	lecture

Chaque outil déclare les annotations MCP standard (readOnlyHint, idempotentHint, destructiveHint) dans tools/list. Les outils de lecture sont readOnlyHint: true et ceux qui changent le statut d’un devis sont destructiveHint: true. La confirmation ne dépend plus du respect de ces annotations par le client MCP : Cord n’exécute aucune action à effet externe tant qu’une personne ne l’a pas validée (voir actions soumises à validation). Aucun outil n’émet ni ne scelle de facture : cela reste une action qu’une personne déclenche depuis l’app ou l’API.

Aucun outil ne modifie directement les paramètres du compte : proponer_configuracion laisse une proposition qu’une personne disposant du droit Paramètres vérifie et approuve dans Cord, comme celle que génèrent l’onboarding ou cord setup.

Chaque outil déclare un outputSchema et répond avec structuredContent (le JSON validable) en plus du texte. Les montants sont accompagnés de leur devise dans moneda : ne supposez jamais des pesos.

Pagination

listar_cotizaciones, buscar_cliente, listar_productos, listar_facturas et listar_eventos renvoient des pages, et non la table entière. Il existe deux formes de réponse.

buscar_cliente et listar_productos renvoient la liste dans items, avec total, has_more, next_cursor et la devise dans moneda ; listar_cotizaciones renvoie total, has_more et next_cursor avec la liste dans cotizaciones, et la devise figure sur chaque devis :

{
  "items": [ { "id": "9a1c3e5f-7b2d-4f6a-8c0e-1d3b5f7a9c2e", "empresa": "Distribuidora El Zarco" } ],
  "total": 47,
  "moneda": "MXN",
  "has_more": true,
  "next_cursor": "20"
}

listar_facturas et listar_eventos ne renvoient que la liste (dans facturas ou eventos) et next_cursor, sans total ni has_more :

{
  "eventos": [ { "id": "6b0e2f4a-8c1d-4e3b-9a5f-7d2c0e8b1a46", "type": "quote.approved" } ],
  "next_cursor": "MjAyNi0wOS0xNFQxODozMjowNC4xMjMwMDBafDZiMGUyZjRhLThjMWQtNGUzYi05YTVmLTdkMmMwZThiMWE0Ng"
}

Dans tous les cas, rappelez le même outil en passant cursor: next_cursor pour obtenir la page suivante. next_cursor vaut null lorsqu’il n’y a plus de résultats.

Appels répétables sans risque (idempotence)

crear_cotizacion_borrador, crear_cliente, crear_tarea, registrar_promesa_pago et les sept actions à effet externe acceptent un idempotency_key facultatif — un identifiant unique que vous générez (un UUID, par exemple). Si votre client MCP doit répéter l’appel faute de réponse à temps (expiration réseau), répétez la MÊME idempotency_key : Cord renvoie le résultat du premier appel au lieu de répéter l’action. Pour une action à effet externe, la même clé renvoie l’état actuel de sa demande (en attente, exécutée, refusée…). Réutiliser la même clé avec d’autres arguments renvoie une erreur, et pour les autres outils la clé expire au bout de 24 heures.

{
  "name": "crear_cotizacion_borrador",
  "arguments": {
    "idempotency_key": "a1b2c3d4-…",
    "cliente_id": "9a1c3e5f-7b2d-4f6a-8c0e-1d3b5f7a9c2e",
    "items": [{ "descripcion": "Installation", "cantidad": 1, "precio_unitario": 4500 }]
  }
}

Sans idempotency_key, l’outil fonctionne normalement — chaque appel crée un nouveau brouillon (ce champ n’est pas obligatoire, il est simplement recommandé si votre client relance automatiquement les appels).

Outils sécurisés

Cord expose des « outils » (tools) à l’IA de manière contrôlée. Cela signifie que l’IA n’a pas d’accès brut et illimité à votre base de données : elle ne peut invoquer que les endpoints que Cord a approuvés et catégorisés, en héritant des droits associés à la clé API.

Limites, mesure et activité

Chaque appel réel (pas les notifications de protocole comme notifications/initialized) compte comme un appel à l’API REST dans le quota d’utilisation de votre offre. Toute requête HTTP au serveur MCP, notifications comprises, compte dans les limites par minute de l’API (600 par clé secrète et 120 par IP d’origine), et les outils qui changent le statut d’un devis partagent en outre la limite de 120 par minute et par organisation ; voir le tableau des limites. Chaque appel apparaît dans l’onglet Journaux du Cord Workbench avec l’outil appelé (par ex. /mcp/tools/call:listar_productos) — vous voyez ainsi exactement ce que fait votre agent, avec quelle clé et à quel moment. Vous pouvez filtrer ce journal par méthode ou par statut, ou rechercher mcp dans la route pour isoler uniquement ce qu’a fait l’IA.

Les actions à effet externe laissent une trace complète : chaque appel apparaît dans Journaux avec la clé qui l’a fait, la décision apparaît dans Paramètres › Journal d’audit avec la personne qui a validé ou refusé, et l’action exécutée est auditée comme faite par cette clé.