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/waafirModules 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/waafirExé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"
}
}
}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/waafirExé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 waafirSe 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 :
| Serveur | URL |
|---|---|
waafir-redact | https://app.waafir.io/api/mcp/waafir-redact |
waafir-translate | https://app.waafir.io/api/mcp/waafir-translate |
waafir-dataroom | https://app.waafir.io/api/mcp/waafir-dataroom |
waafir-esign | https://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-dataroomouwaafir-esign— le plus souvent une faute de frappe ou un/api/mcpnu 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.waafirne répond jamais 402 : il masque plutôt les outils payants, et un appel à l'un d'eux est refusé sur la couche 2 avecQUOTA_EXCEEDEDet un message nommant cet outil, qui porte aussiADDON_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
Authorizationest 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 403CSRF 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-Afterni 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 :
| Code | Signification |
|---|---|
INVALID_ARGUMENT | Un argument est absent, mal formé ou n'est pas un identifiant valide — corrigez-le et réessayez |
FORBIDDEN | Le jeton est valide mais n'est pas autorisé pour cet appel |
NOT_FOUND | Aucun enregistrement de ce type, ou il ne vous appartient pas |
CONFLICT | Compris et autorisé, mais la salle de données n'est pas dans un état qui permet de l'exécuter |
TOO_LARGE | L'entrée dépasse une limite de taille — fractionnez-la |
QUOTA_EXCEEDED | Une allocation mesurée est épuisée ; quelqu'un doit acheter ou mettre à niveau quelque chose |
UPSTREAM_ERROR / UNAVAILABLE | Une défaillance transitoire en aval — réessayez plus tard |
INTERNAL | Une défaillance inattendue — ne réessayez pas, escaladez |
Deux d'entre eux prennent les gens au dépourvu :
FORBIDDENpour une portée insuffisante. Une connexion ou un jetonreadne 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 deFORBIDDENdans 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 commedataroom_idune salle hors de sa liste autorisée. La plupart des outils qui prennent plutôt un identifiant de fichier ou de dossier répondentNOT_FOUNDpour 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é. UnCONFLICTn'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érencewaafir-dataroomliste 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é.