Waafir
Cette page est une traduction automatique en attente de relecture humaine. Elle peut contenir des erreurs.

Configuration

Connecter un assistant IA à Waafir ne demande qu'une URL : collez-la dans votre assistant, puis connectez-vous à Waafir lorsqu'il vous le demande. Aucun jeton n'est à créer ni à copier. Cette page couvre la connexion, l'étape d'ajout de serveur de chaque assistant, et la façon de se connecter plutôt avec un jeton d'accès personnel lorsqu'un assistant ne peut pas se connecter.

Les bases

L'URL. Une seule URL sert tous les outils Waafir :

https://app.waafir.io/api/mcp/waafir

Modules complémentaires → Configuration → Assistants IA affiche l'URL de votre déploiement, avec un bouton de copie. Remplacez https://app.waafir.io si vous êtes sur un autre déploiement.

La connexion. La première fois que votre assistant utilise l'URL, il ouvre Waafir dans votre navigateur. Connectez-vous comme d'habitude, puis examinez l'écran de consentement :

  • Quelle organisation l'assistant utilise, si vous appartenez à plusieurs organisations ;
  • Quelles salles de données il peut atteindre : toutes, ou uniquement celles que vous choisissez ;
  • Ce qu'il peut faire : lecture, écriture ou administration, jamais au-delà de ce que votre propre rôle autorise, et s'il peut signer des documents ou envoyer en dehors de votre organisation ;
  • Confirmez qu'il s'agit bien de vous. Si vous avez configuré l'authentification à deux facteurs, chaque approbation demande d'abord votre code, comme le fait la création d'un jeton.

Approuvez, et le navigateur vous renvoie vers l'assistant. La connexion apparaît sous Modules complémentaires → Configuration → Assistants IA, où vous pouvez voir ce à quoi elle peut accéder et la révoquer. Voir Connexions.

Unverified app "…". Un assistant qui s'identifie par une adresse web qu'il contrôle est affiché sous cette adresse, comme claude.ai. Un assistant qui s'est enregistré lui-même sous un nom de son choix est affiché comme Unverified app "<its name>" : Waafir ne peut pas confirmer qui l'a créé, donc ne l'approuvez que si vous avez vous-même lancé la connexion.

Ce qu'affiche la liste des outils. Les noms d'outils commencent par leur domaine : dataroom_, esign_, redact_ et translate_. La liste n'affiche que les outils que votre connexion et votre organisation peuvent utiliser : une connexion en lecture seule ne voit pas les outils d'écriture, et les outils de signature électronique n'apparaissent que si votre organisation dispose du module complémentaire E-Signatures ou d'un abonnement actif. Une connexion liste aussi les outils qui exigent une permission que vous n'avez pas accordée, comme signer ou envoyer en dehors de votre organisation. Si l'assistant en appelle un, Waafir refuse l'appel et l'assistant vous demande d'approuver à nouveau, cette fois avec cette permission proposée. Un jeton ne peut pas redemander, donc sa liste omet ces outils. Un outil qui n'est pas listé reste refusé, avec son motif, si un assistant l'appelle malgré tout.

Connecter votre assistant

Chaque section ci-dessous indique l'étape d'ajout de serveur propre à l'assistant et renvoie à sa documentation (chaque lien vérifié pour la dernière fois le 23 octobre 2026). Aucun de ces assistants n'a encore été testé avec la connexion Waafir, c'est pourquoi chaque section conserve à côté la solution de repli par jeton.

Claude (claude.ai et Claude Desktop)

Pas encore testé par Waafir. Ouvrez Customize → Connectors, choisissez Add → Add custom connector, donnez-lui un nom, collez l'URL et continuez. Laissez la connexion activée, et connectez-vous à Waafir lorsque Claude le demande. Pour l'utiliser dans une conversation, activez-le sous + → Connectors. Avec une offre Team ou Enterprise, c'est un propriétaire qui ajoute les connecteurs sous Organization settings → Connectors. (Guide de Claude)

Si la connexion ne fonctionne pas, ajoutez plutôt un en-tête de requête Authorization: Bearer <token> avec un jeton (voir Se connecter avec un jeton à la place).

ChatGPT

Pas encore testé par Waafir. ChatGPT accède aux serveurs MCP distants à des endroits différents selon l'application ; dans l'application de bureau, ouvrez Settings → MCP servers → Add server et collez l'URL, puis connectez-vous à Waafir lorsqu'on vous le demande. (Guide d'OpenAI)

Si ChatGPT ne peut pas se connecter, utilisez plutôt un jeton.

Claude Code

Pas encore testé par Waafir.

claude mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir

Exécutez ensuite /mcp dans Claude Code (ou claude mcp login waafir depuis votre shell) et connectez-vous à Waafir dans le navigateur. Ajoutez --scope user pour l'utiliser dans tous vos projets. Modules complémentaires → Configuration → Assistants IA propose cette commande prête à copier. (Guide de Claude Code)

Cursor

Pas encore testé par Waafir. Ajoutez l'URL à .cursor/mcp.json (ou à ~/.cursor/mcp.json pour tous les projets), puis connectez-vous à Waafir lorsque Cursor le demande :

{
  "mcpServers": {
    "waafir": {
      "url": "https://app.waafir.io/api/mcp/waafir"
    }
  }
}

(Guide de Cursor)

Si Cursor ne peut pas se connecter, ajoutez l'en-tête de jeton indiqué dans Se connecter avec un jeton à la place.

VS Code

Pas encore testé par Waafir. Exécutez MCP: Add Server depuis la palette de commandes, choisissez HTTP, collez l'URL et donnez-lui l'identifiant waafir. Connectez-vous à Waafir lorsque VS Code le demande. (Guide de VS Code)

Gemini CLI

Pas encore testé par Waafir.

gemini mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir

Exécutez ensuite /mcp auth waafir et connectez-vous dans le navigateur. La connexion nécessite un navigateur local ; elle ne fonctionne donc pas dans la plupart des sessions SSH distantes : utilisez-y un jeton. (Guide de Gemini CLI)

Codex

Pas encore testé par Waafir.

codex mcp add waafir --url https://app.waafir.io/api/mcp/waafir
codex mcp login waafir

(Guide de Codex)

Se connecter avec un jeton à la place

Utilisez un jeton d'accès personnel lorsqu'un assistant ne peut pas se connecter, ou pour un script. Chaque requête porte le jeton en tant que jeton bearer dans l'en-tête Authorization :

Authorization: Bearer waafir_pat_...

Ne commitez jamais un vrai jeton dans un fichier ou un dépôt partagé ; traitez-le comme un mot de passe. Modules complémentaires → Configuration → Jetons API propose un extrait prêt à copier.

Serveurs par domaine. En plus de waafir, quatre serveurs par domaine sont toujours servis, afin qu'une configuration existante continue de fonctionner. Chacun ne liste que les outils de son propre domaine, filtrés de la même manière, et conserve les noms d'outils qu'il a toujours eus (list_files plutôt que dataroom_list_files). Vous n'en avez pas besoin si vous vous connectez à waafir :

ServeurURL
waafir-redacthttps://app.waafir.io/api/mcp/waafir-redact
waafir-translatehttps://app.waafir.io/api/mcp/waafir-translate
waafir-dataroomhttps://app.waafir.io/api/mcp/waafir-dataroom
waafir-esignhttps://app.waafir.io/api/mcp/waafir-esign

Il n'existe aucun point de terminaison /api/mcp nu : le segment du nom de serveur est obligatoire, et une requête qui ne le contient pas renvoie une 404. waafir-esign est une offre payante : sans le module complémentaire E-Signatures ou un abonnement actif, son URL répond par une erreur ADDON_NOT_PURCHASED. Sur waafir, la même organisation ne voit simplement pas les outils esign_.

Claude Code. Placez d'abord le jeton dans une variable d'environnement, afin qu'il reste hors de l'historique de votre shell :

export WAAFIR_PAT=...   # the token you copied at issuance
claude mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir \
  --header "Authorization: Bearer $WAAFIR_PAT"

Pour partager la configuration avec un projet, placez la même entrée dans son .mcp.json. Claude Code développe ${WAAFIR_PAT} à partir de l'environnement de chaque personne, de sorte que le fichier peut être commité sans le jeton :

{
  "mcpServers": {
    "waafir": {
      "type": "http",
      "url": "https://app.waafir.io/api/mcp/waafir",
      "headers": {
        "Authorization": "Bearer ${WAAFIR_PAT}"
      }
    }
  }
}

Le fichier de configuration de Claude Desktop. claude_desktop_config.json démarre des serveurs locaux : chaque entrée est une command à exécuter, et non une url distante. Pour atteindre Waafir depuis ce fichier, exécutez la passerelle mcp-remote (elle nécessite Node.js), qui relaie vers le serveur distant et ajoute votre jeton en en-tête :

{
  "mcpServers": {
    "waafir": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.waafir.io/api/mcp/waafir",
        "--header",
        "Authorization:${WAAFIR_AUTH}"
      ],
      "env": {
        "WAAFIR_AUTH": "Bearer YOUR_WAAFIR_PAT"
      }
    }
  }
}

Veillez à ce que l'argument Authorization:${WAAFIR_AUTH} ne contienne aucun espace, puis redémarrez Claude Desktop.

Cursor, et les autres clients qui acceptent une URL et des en-têtes.

{
  "mcpServers": {
    "waafir": {
      "url": "https://app.waafir.io/api/mcp/waafir",
      "headers": {
        "Authorization": "Bearer YOUR_WAAFIR_PAT"
      }
    }
  }
}

Un serveur par domaine s'ajoute de la même manière, en changeant la clé de l'entrée et l'URL.

Appeler un outil

Après la connexion, votre client liste les outils du serveur (un tools/list MCP) et les appelle en votre nom. Vous n'appelez pas les outils à la main — vous demandez au client IA de faire quelque chose (« liste les fichiers de cette salle de données », « traduis ce paragraphe en français ») et il sélectionne et appelle le bon outil, en transmettant les arguments documentés dans la référence de chaque serveur. Consultez les références waafir-redact, waafir-translate, waafir-dataroom et waafir-esign pour les contrats des outils.

En cas de problème

Les échecs arrivent sur deux couches différentes, et ils ne se ressemblent pas. Se tromper sur ce point est de loin l'erreur d'intégration la plus courante ici : un client qui ne se fonde que sur le statut HTTP manquera silencieusement tous les échecs du second type.

Couche 1 — la requête a été refusée avant l'exécution de tout outil

Il s'agit de véritables statuts d'erreur HTTP, avec un corps d'erreur au format JSON-RPC. Ils signifient que la requête n'a jamais atteint d'outil :

  • 404 — Serveur MCP inconnu. Le segment du nom de serveur de l'URL n'est pas l'un de waafir, waafir-redact, waafir-translate, waafir-dataroom ou waafir-esign — le plus souvent une faute de frappe ou un /api/mcp nu sans nom de serveur. Corrigez l'URL.

  • 402 — Module complémentaire non acheté. Le serveur est une offre payante (aujourd'hui : waafir-esign) et votre organisation ne dispose ni du module complémentaire ni d'un abonnement actif. Un administrateur de l'organisation peut acheter le module complémentaire ou une offre depuis les paramètres de facturation. Une organisation sans ce droit ne peut même pas lister les outils du serveur. waafir ne répond jamais 402 : il masque plutôt les outils payants, et un appel à l'un d'eux est refusé sur la couche 2 avec QUOTA_EXCEEDED et un message nommant cet outil, qui porte aussi ADDON_NOT_PURCHASED.

  • 401 — Non authentifié. L'identifiant est absent, mal formé, révoqué ou expiré. Pour une connexion, reconnectez-vous depuis votre assistant : la plupart des assistants le font pour vous lorsqu'ils reçoivent la 401, et une connexion révoquée, ou restée inutilisée pendant 30 jours, nécessite une nouvelle connexion. Pour un jeton, vérifiez que l'en-tête Authorization est présent et que le jeton est toujours actif dans Modules complémentaires → Configuration → Jetons API ; émettez-en un nouveau s'il a été révoqué ou s'il a expiré. Un déploiement antérieur à ce comportement répond à un jeton absent ou mal formé par 403 CSRF validation failed: missing Origin à la place ; sur cette surface, cela signifie également que le jeton est absent ou mal formé.

  • 403 — Interdit. L'identifiant a été rejeté d'entrée : une session de navigateur authentifiée a été utilisée au lieu d'une connexion ou d'un PAT (les sessions ne sont pas acceptées sur cette surface), ou votre organisation applique une liste d'adresses IP autorisées et la requête provenait d'une adresse hors de cette liste.

  • 429 — Trop de requêtes. Vous avez atteint une limite de débit MCP. Rien ici n'est indexé sur votre adresse IP ni sur votre organisation — votre budget est celui de votre jeton, de sorte qu'un collègue de la même organisation et un second client sur le même réseau ne le consomment pas. La limite est de 60 requêtes par minute et par jeton. Elle est décomptée avant la recherche du jeton, si bien qu'un jeton mal formé, révoqué ou expiré la consomme aussi, et les appels du même jeton à l'API Waafir en dehors de MCP sont imputés sur les mêmes 60. Les 60 d'une connexion authentifiée sont aussi décomptés par connexion, de sorte que le nouveau jeton que votre assistant obtient lorsqu'il actualise sa connexion ne repart pas de 60.

    La réponse ne contient aucun en-tête Retry-After ni code distinctif — toutes les 429 de cette surface se ressemblent — alors espacez vos tentatives selon votre propre calendrier plutôt que de boucler. Si un jeton ne vous laisse pas assez de marge, émettez-en un second : la limite s'applique par jeton.

Couche 2 — un outil s'est exécuté et a refusé

C'est là que se trouvent la plupart des refus, et ce n'est pas une erreur HTTP. La réponse HTTP est 200 et l'enveloppe JSON-RPC est une enveloppe de succès. L'échec est porté à l'intérieur du résultat de l'outil, qui définit isError: true et dont le contenu textuel est :

{ "error": { "code": "CONFLICT", "message": "…" } }

Aiguillez votre traitement sur error.code. Les codes sont :

CodeSignification
INVALID_ARGUMENTUn argument est absent, mal formé ou n'est pas un identifiant valide — corrigez-le et réessayez
FORBIDDENLe jeton est valide mais n'est pas autorisé pour cet appel
NOT_FOUNDAucun enregistrement de ce type, ou il ne vous appartient pas
CONFLICTCompris et autorisé, mais la salle de données n'est pas dans un état qui permet de l'exécuter
TOO_LARGEL'entrée dépasse une limite de taille — fractionnez-la
QUOTA_EXCEEDEDUne allocation mesurée est épuisée ; quelqu'un doit acheter ou mettre à niveau quelque chose
UPSTREAM_ERROR / UNAVAILABLEUne défaillance transitoire en aval — réessayez plus tard
INTERNALUne défaillance inattendue — ne réessayez pas, escaladez

Deux d'entre eux prennent les gens au dépourvu :

  • FORBIDDEN pour une portée insuffisante. Une connexion ou un jeton read ne voit pas les outils d'écriture, mais un client qui en appelle un malgré tout est refusé par l'outil ; le refus arrive donc ici sous la forme de FORBIDDEN dans la charge utile — et non d'une 403 HTTP. Il en va de même pour un jeton restreint à des salles de données précises qui indique comme dataroom_id une salle hors de sa liste autorisée. La plupart des outils qui prennent plutôt un identifiant de fichier ou de dossier répondent NOT_FOUND pour un élément d'une telle salle, exactement comme pour un identifiant inexistant. Reconnectez-vous depuis votre assistant et accordez la bonne portée ou les bonnes salles de données, ou émettez un jeton avec la bonne portée.
  • CONFLICT. L'appel a été compris et autorisé, mais la salle de données n'est pas dans un état qui permet de l'exécuter — un nom de dossier déjà pris, un fichier dont le nom a entre-temps été pris par un fichier actif, ou une restauration dont le conteneur est toujours supprimé ou dont le téléversement ne s'est jamais terminé. Un CONFLICT n'est pas un problème d'autorisation, et se reconnecter ou réémettre le jeton n'y changera rien ; le message nomme l'enregistrement bloquant lorsqu'il y en a un, afin que vous puissiez agir dessus et réessayer. La référence waafir-dataroom liste les conflits que chaque outil peut renvoyer.

Un fichier encore en cours de vérification. Waafir vérifie chaque fichier nouvellement téléversé et chaque nouvelle version avant d'en servir le contenu. D'ici là, un outil qui lit le contenu du fichier répond UNAVAILABLE avec error.reason: "ACTIVATION_PENDING" et le message This file is still being checked. Try again shortly. C'est transitoire : rappelez l'outil après un court délai.

Un refus clair sur l'une ou l'autre couche est l'issue attendue et sûre d'un appel que Waafir ne servira pas — la requête échoue plutôt que de faire silencieusement moins que ce que vous avez demandé.