HOLCO MCP · Documentation développeur

Intégrer un client MCP

Un point d’entrée pour découvrir les outils autorisés, transmettre une demande structurée et traiter ses résultats.

Endpoint et authentification

Le point d’entrée client est https://mcp.holco.co/. Les appels utilisent HTTP POST et des messages JSON-RPC 2.0. Fournir Authorization: Bearer <CLE_HOLCO> dans le transport ; la clé HOLCO n’est pas un jeton Pennylane, Microsoft ou Qonto. Les connexions éditeurs sont gérées séparément.

L’ancienne URL /mcp/pennylane/mcp/v1 est une route de compatibilité machine. La documentation humaine est désormais sous /mcp/docs/. Déplacer la documentation ne change pas l’endpoint MCP.

Initialiser puis découvrir

Envoyer initialize avec la version du protocole et l’identité du client. Le serveur négocie les versions 2025-06-18, 2025-03-26 et 2024-11-05. Suivre le cycle d’initialisation MCP de votre bibliothèque, puis demander tools/list. Le service actuel fonctionne sans identifiant de session Mcp-Session-Id à conserver.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "integration-demo", "version": "1.0.0" }
  }
}

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }

Ne pas coder la liste des outils à partir des noms d’éditeurs. Le catalogue authentifié dépend de l’identité et peut exposer les familles de capacités, des noms historiques ou un routeur. Lire les descriptions et inputSchema effectivement retournés. La référence des outils facilite cette lecture et fournit un registre JSON téléchargeable.

Appeler une action

Lorsque le catalogue expose holco_comptabilite et l’action balance, envoyer un appel tools/call avec les paramètres requis par le schéma et le dossier autorisé. L’exemple ci-dessous illustre la structure ; compléter les arguments métier à partir du catalogue du compte.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "holco_comptabilite",
    "arguments": { "action": "balance", "source": "pennylane" }
  }
}

Le client doit demander ou résoudre le dossier lorsque le contexte ne suffit pas. Ne pas attribuer arbitrairement une demande au premier dossier retourné.

Lire les erreurs à trois niveaux

  1. HTTP : gérer notamment authentification, refus, requête invalide et indisponibilité du service. Un 401 demande de vérifier l’accès ; le répéter indéfiniment ne le répare pas.
  2. JSON-RPC : examiner l’objet error et son code, même si une réponse HTTP a été reçue.
  3. Résultat d’outil : un HTTP 200 peut contenir result.isError. Ne pas convertir ce résultat en donnée comptable vide ou en conclusion positive.

Distinguer dépassement de quota, périmètre interdit, donnée absente et résultat partiel dans la restitution. Pour une lecture idempotente, appliquer une reprise bornée avec délai croissant et aléa, en respectant les indications du service. Les règles de reprise font partie de l’intégration cliente ; elles ne constituent pas une garantie de disponibilité.

Effets de bord et traitements longs

Une consultation des systèmes sources peut déclencher un travail persistant dans HOLCO. Les actions de mémoire peuvent enregistrer une règle ou transmettre un retour. Pour les revues asynchrones, conserver l’identifiant du travail et utiliser l’action de suivi correspondante ; ne pas lancer une nouvelle revue à chaque délai d’attente.

Recette d’un client

Vérifier initialisation, catalogue authentifié, dossier autorisé, refus sur un autre périmètre, résultat vide, erreur d’outil et reprise d’une lecture interrompue. Conserver identifiant de requête, nom d’outil, durée et catégorie d’erreur dans la télémétrie. Exclure clés, pièces et contenu client des journaux génériques. Tester avec des données de recette dédiées.