# Démarrer avec HOLCO MCP

Guide développeur · référence du 9 septembre 2026.

Documentation : https://apps.holco.co/mcp/docs/

## Références développeur

- [API et connecteurs](https://apps.holco.co/mcp/docs/connecteurs/)
- [Pennylane](https://apps.holco.co/mcp/docs/connecteurs/pennylane/)
- [Sage Active](https://apps.holco.co/mcp/docs/connecteurs/sage/)
- [Cegid Loop](https://apps.holco.co/mcp/docs/connecteurs/cegid/)
- [Qonto](https://apps.holco.co/mcp/docs/connecteurs/qonto/)
- [Outils et paramètres](https://apps.holco.co/mcp/docs/outils/)
- [Contrat de données](https://apps.holco.co/mcp/docs/gouvernance/)

## 1. Préparer votre accès

Vous avez besoin d’un accès HOLCO actif, des sources autorisées pour votre cabinet et d’un client MCP distant ou de curl pour le diagnostic développeur.

- **Client conversationnel** : suivez le [guide Claude](https://apps.holco.co/install/claude/) ou le [guide ChatGPT](https://apps.holco.co/install/chatgpt/).
- **Client développé par votre équipe** : demandez une clé HOLCO à votre administrateur, puis transmettez-la dans `Authorization: Bearer …`. Utilisez le flux OAuth si votre client est configuré pour ce mode.
- **Sources métier** : gérez les connexions dans votre [espace cabinet](https://apps.holco.co/cabinet/). La clé HOLCO ne remplace pas l’autorisation Pennylane, Microsoft ou Boond.

Pour une démonstration, demandez un accès dédié à [alan@holco.co](mailto:alan@holco.co). La démonstration peut utiliser le même endpoint avec une identité limitée et des données fictives ; ne supposez pas l’existence d’un endpoint sandbox public distinct.

```mermaid
flowchart LR
  N0["Identité HOLCO : Compte actif et clé ou OAuth"]
  N1["Sources connectées : Autorisations de chaque fournisseur"]
  N2["Périmètre effectif : Capacité, source et dossier accessibles"]
  N0 --> N1 --> N2
```

## 2. Utiliser le point d’entrée MCP

Endpoint public recommandé :

```text
https://mcp.holco.co/
```

Endpoint de compatibilité : `https://apps.holco.co/mcp/pennylane/mcp/v1`.

Les appels de diagnostic ci-dessous sont des requêtes **POST JSON-RPC 2.0**. L’endpoint MCP est destiné à un client, pas à l’ouverture d’une page dans un navigateur.

Le serveur négocie actuellement `2025-06-18`, `2025-03-26` ou `2024-11-05`. Réutilisez la version renvoyée par `initialize`. Le parcours actif est sans état de session : il ne renvoie pas de `Mcp-Session-Id` à conserver. Authentifiez chaque requête.

La version MCP désigne le protocole. La version de l’implémentation HOLCO apparaît séparément dans `result.serverInfo.version`.

```mermaid
flowchart LR
  N0["initialize : Négocier version et capacités"]
  N1["tools/list : Découvrir les outils de cette identité"]
  N2["tools/call : Appeler un outil avec son schéma"]
  N0 --> N1 --> N2
```

## 3. Initialiser et découvrir les outils

Exemples pour Bash et curl. Placez votre clé dans la variable d’environnement `HOLCO_API_KEY` via votre gestionnaire de secrets ; ne l’insérez ni dans le README ni dans Git.

```bash
: "${HOLCO_API_KEY:?Définissez votre clé HOLCO dans l’environnement}"
export HOLCO_MCP_URL='https://mcp.holco.co/'

curl --silent --show-error --fail-with-body \
  --request POST "$HOLCO_MCP_URL" \
  --header "Authorization: Bearer $HOLCO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"holco-developer-quickstart","version":"1.0.0"}}}'
```

Vérifiez la présence de `result.protocolVersion`, `result.capabilities.tools` et `result.serverInfo`. Un HTTP 200 seul ne suffit pas : contrôlez aussi l’absence de champ `error`.

Si `initialize` a confirmé `2025-06-18`, découvrez les outils :

```bash
curl --silent --show-error --fail-with-body \
  --request POST "$HOLCO_MCP_URL" \
  --header "Authorization: Bearer $HOLCO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'MCP-Protocol-Version: 2025-06-18' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

La réponse expose `result.tools` avec les noms, descriptions et `inputSchema` disponibles pour votre identité. Ces deux requêtes découvrent le serveur et son catalogue ; elles ne lancent pas de révision de dossier. Elles peuvent alimenter les métadonnées techniques de connexion.

Ces exemples sont des sondes HTTP du serveur HOLCO actuel. Pour une intégration applicative complète, utilisez un client MCP qui gère son cycle de connexion et la négociation du protocole.

## 4. Construire un appel métier

Prenez le nom et les arguments dans le catalogue renvoyé à votre compte. La surface peut être historique ou regroupée par capacités : ne figez pas un nom d’outil découvert avec une autre identité.

1. Choisissez une opération correspondant au besoin et lisez sa description.
2. Construisez `params.arguments` selon son `inputSchema`, notamment ses champs `required`.
3. Envoyez la méthode `tools/call` avec `params.name` et `params.arguments`.
4. Contrôlez `error`, puis `result.isError`. Lisez `structuredContent` lorsqu’il existe et les blocs `content` selon leur type.

Exemple **de construction**, à intégrer dans votre client avec un outil et des arguments réellement découverts :

```javascript
function makeToolCall(id, discoveredTool, validatedArguments) {
  return {
    jsonrpc: "2.0",
    id,
    method: "tools/call",
    params: {
      name: discoveredTool.name,
      arguments: validatedArguments
    }
  };
}
```

Validez les arguments avec le schéma avant l’envoi. Cette fonction construit uniquement le message ; elle n’effectue ni validation ni appel réseau.

Les identifiants de dossier proviennent de votre périmètre autorisé. Les contrôles comptables sont en lecture seule dans Pennylane ; les opérations de mémoire et de décision peuvent conserver un état dans HOLCO. Consultez la description de chaque opération avant de l’exécuter.

```mermaid
flowchart LR
  N0["Votre client : Outil découvert et arguments validés"]
  N1["Serveur HOLCO : Droits, source, contrôle et contexte"]
  N2["Résultat : Contenu, provenance ou erreur explicite"]
  N0 --> N1 --> N2
```

## 5. Diagnostiquer une réponse

- **HTTP 401** : vérifier l’en-tête Bearer, la validité de la clé ou du jeton et l’état du compte.
- **HTTP 403 ou refus de politique dans le résultat** : vérifier le périmètre, les capacités et les autorisations de la source. Ne pas réessayer avec un dossier arbitraire.
- **HTTP 405** : vérifier que vous utilisez POST sur l’endpoint MCP.
- **JSON-RPC `error`** : vérifier la méthode et la structure JSON. Le serveur distingue notamment le JSON illisible et la méthode inconnue.
- **`result.isError: true`** : l’outil signale un échec même si le transport HTTP répond 200. Lisez le message avant de poursuivre.
- **Limitation de débit, quota ou délai** : lire les indications de reprise disponibles. Ne pas relancer en boucle serrée ; une opération avec effet de bord ne se rejoue pas aveuglément.
- **Outil ou source absent** : rafraîchir le catalogue après un changement d’accès et vérifier la connexion dans l’espace cabinet.

Pour le support, conservez l’heure UTC, la méthode, le statut et le `x-request-id` renvoyé lorsqu’il est présent. Retirez les clés et les données de dossier de votre message à [alan@holco.co](mailto:alan@holco.co). Aucun quota universel ni contrat d’idempotence général n’est annoncé par ce guide.

## 6. Comprendre les frontières d’exécution

Le modèle de votre assistant consomme le contexte retourné par MCP. Les contrôles déterministes et les lectures d’API n’impliquent pas à eux seuls un appel de modèle côté HOLCO. Les agents serveur, lorsqu’ils appellent un LLM, ont une consommation distincte.

Les règles et objets de mémoire sont rattachés au cabinet et au dossier avec leur provenance. Les constats et arbitrages peuvent être conservés. La pseudonymisation est une option configurable, pas un anonymat garanti de toute pièce jointe.

Consultez les schémas du [Lab : architecture, RAG, évaluations et coûts LLM](https://apps.holco.co/). La feuille de route y distingue les mécanismes actuels et la chaîne documentaire à généraliser.

## 7. Ressources disponibles

- [Installation Claude](https://apps.holco.co/install/claude/)
- [Installation ChatGPT](https://apps.holco.co/install/chatgpt/)
- [Commandes métier de départ](https://apps.holco.co/mcp/docs/aide/)
- [Connexion Boond](https://apps.holco.co/mcp/docs/boond/)
- [Source Pappers](https://apps.holco.co/mcp/docs/pappers/)
- [Lexique et sources](https://apps.holco.co/mcp/docs/lexique/)
- [Sécurité et gouvernance](https://apps.holco.co/mcp/docs/security/)
- [FAQ](https://apps.holco.co/mcp/docs/faq/)
- [Référence MCP : découverte et appel des outils](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)

Les guides métier complètent ce démarrage développeur. Le catalogue authentifié `tools/list` reste la référence pour les outils réellement disponibles sur votre compte.