Documentation du serveur MCP Foliade

Connecter votre compte dans Codex

Installer le plugin ne connecte pas encore votre compte. Après l'installation, lancez cette commande dans le terminal de votre ordinateur, en dehors de la conversation Codex :

codex mcp login foliade

Dans la page Foliade qui s'ouvre, connectez-vous, vérifiez l'adresse du compte et autorisez la connexion. Revenez ensuite dans votre assistant.

Si le navigateur ne s'ouvre pas, ouvrez le lien affiché dans le terminal. Ne partagez pas ce lien de connexion.

Attendez la confirmation de connexion dans le terminal avant de continuer. Aucune clé API n'est à copier.

Vérifier la connexion et envoyer un premier PDF · Installation Claude Code

Transport et authentification

Le MCP est inclus gratuitement, avec ou sans compte. Codex et Claude Code appliquent les droits de votre offre ; leurs propres conditions d’accès restent distinctes.

Compte gratuit : 5 catalogues publiés, 50 Mo et 100 pages par PDF. Site et MCP partagent 10 tentatives de dépôt sur 24 heures, remplacements et échecs compris, avec un seul dépôt en cours. Les vues restent illimitées.

Sans compte, sur le site ou par MCP : 3 PDF par IP sur 24 heures, 50 Mo et 100 pages par PDF, un seul dépôt en cours. Publication pendant 30 jours, gestion privée pendant 30 minutes. Conservez le lien privé pour rattacher le catalogue à un compte avant son expiration.

Protection du gratuit : traitement limité à 120 secondes, 512 Mo par résultat et 2 Go de stockage par compte. La capacité globale est limitée ; les offres payantes sont prioritaires. En cas de refus, attendez le délai indiqué sans relance automatique.

Avant chaque transfert, l’assistant vérifie le compte ou le mode invité et vous explique les limites renvoyées par Foliade. Le brouillon reste privé jusqu’à votre demande de publication.

https://foliade.gekkode.com/mcp

La connexion OAuth est facultative pour un dépôt invité et nécessaire pour accéder à votre compte, y compris gratuit. Le serveur vérifie vos droits à chaque action ; une connexion expirée ne devient jamais un accès invité.

Le jeton d'accès dure une heure. Les jetons de renouvellement tournent à chaque usage, sans prolonger la connexion au-delà de 30 jours. Un jeton de renouvellement réutilisé révoque toute la connexion.

Les clients peuvent utiliser l'enregistrement dynamique ou les documents d'identité des clients OpenAI et Anthropic. Les métadonnées sont publiques :

/.well-known/oauth-authorization-server
/.well-known/oauth-protected-resource/mcp

Les permissions sont séparées :

• foliade:read — lire le compte, les réglages, les liens de suivi et les statistiques ;
• foliade:write — transférer un PDF et configurer les catalogues, thèmes, enrichissements et étagères ;
• foliade:publish — gérer les publications, les protections et les adresses publiques.

Les outils de dépôt et de publication

Personnaliser Foliade depuis un assistant

Le serveur propose 35 outils. Les 26 outils de configuration nécessitent un compte connecté et respectent les droits de votre offre.

Commencez par découvrir les capacités, puis lisez les réglages de la cible. Envoyez seulement les champs à modifier avec la révision reçue. Un conflit impose une nouvelle lecture ; les champs inconnus, valeurs nulles et valeurs invalides sont refusés.

Un aperçu avec dry_run ne sauvegarde rien. Pour enregistrer, utilisez la révision initiale, pas celle de l’aperçu. Les réglages d’un catalogue publié sont visibles immédiatement ; les enrichissements disposent d’un brouillon et d’une publication distincte.

Le lecteur expose ses couleurs, fonds, barre, contrôles, effets, sens de lecture, son, page de départ, disposition, lien et position du logo, langue et téléchargement PDF. Les éléments interactifs utilisent les 13 types de l’éditeur, avec coordonnées en pourcentage de page.

Les listes sont paginées. Les liens de suivi ne déclenchent aucun envoi de message. Modifier la marque du compte peut affecter plusieurs catalogues ; pour un seul PDF, préférez ses réglages propres.

Exemple : harmoniser les couleurs du lecteur

foliade_get_catalogue_settings({"catalogue_id": "IDENTIFIANT"})
foliade_update_catalogue({
  "catalogue_id": "IDENTIFIANT",
  "expected_revision": "REVISION_RENVOYEE_PAR_LA_LECTURE",
  "patch": {
    "fond": "#f7f5f0",
    "barre_fond": "#111111",
    "barre_icones": "#f7f5f0",
    "progression": "#ad935a"
  },
  "dry_run": true
})

Les imports de médias binaires, le remplacement du PDF, la synchronisation des produits, la gestion des clés API, des webhooks, de l’équipe et de la facturation restent accessibles par l’espace web ou l’API REST selon la fonction. Le MCP ne configure pas le DNS ou les certificats TLS.

Si votre assistant ne voit encore que neuf outils, actualisez la liste des outils dans son interface MCP ou relancez la session. Une réinstallation ne doit pas être la première réponse à un cache ancien. Vérifiez ensuite la présence de foliade_capabilities.

Transfert d'un PDF local

Le serveur distant ne peut pas lire un chemin sur votre ordinateur. Le plugin calcule la taille et l'empreinte SHA-256 du fichier choisi, prépare un dépôt, envoie ses octets en HTTPS puis finalise le brouillon.

Le ticket expire après 10 minutes et ne permet de transférer que le PDF annoncé, en 120 secondes maximum. Le gratuit autorise un seul dépôt en cours ; les comptes payants peuvent ouvrir cinq transferts.

La conversion est asynchrone. L'assistant vérifie son résultat avant d'annoncer la réussite. La publication publique exige une action distincte ; le brouillon reste privé par défaut.

Le PDF doit être lisible, sans mot de passe, et respecter la limite affichée par l'outil de vérification du compte.

Erreurs et révocation

• 401 : connexion absente, expirée ou révoquée. Reconnectez le compte.
• 403 renvoyé par Foliade : permission insuffisante. Vérifiez les droits autorisés. Un refus Cloudflare 403/1010 relève du dépannage ci-dessous.
• 413 : fichier trop volumineux. Réduisez le PDF.
• 422 : fichier reçu différent du fichier annoncé. Recommencez le transfert.
• 429 : trop de demandes. Respectez le délai de nouvelle tentative.

Les erreurs des outils sont signalées dans leur résultat MCP. Un catalogue d'un autre compte reste inaccessible. Un PDF corrompu ou une conversion échouée ne doit jamais être présenté comme réussi.

Foliade → API → Assistants connectés permet de révoquer chaque connexion. L'accès est coupé immédiatement, sans supprimer vos catalogues.

Plugin activé, mais outils MCP indisponibles

Un plugin activé peut échouer à se connecter au serveur. Consultez l’état MCP et le message d’erreur avant de réinstaller le plugin ou de reconnecter votre compte.

1. Si le serveur est introuvable, vérifiez l’installation et l’activation du plugin.
2. Si la connexion dépasse le délai de démarrage, consultez les journaux MCP. Un délai dépassé après 30 secondes ne prouve pas que votre connexion OAuth a expiré.
3. Si la réponse Cloudflare 403 indique l’erreur 1010 ou browser_signature_banned, le contrôle Browser Integrity Check bloque le client HTTP avant son accès à Foliade. Augmenter le délai de démarrage ne corrige pas ce refus.
4. Si Foliade renvoie 401 ou invalid_token, reconnectez votre compte par OAuth. Ne remplacez pas cette connexion par un accès invité.

Que faire en cas de blocage Cloudflare ?

Sur le service hébergé Foliade, contactez notre support avec l’heure et le fuseau horaire, l’URL concernée, le code d’erreur et le Ray ID Cloudflare s’il est affiché. Ne transmettez aucun jeton, cookie, lien de connexion ou document privé. Vous n’avez pas de réglage Cloudflare à modifier sur votre ordinateur.

État du service · Contacter le support Foliade

Après la correction du serveur, relancez votre assistant pour recharger les outils MCP, puis demandez-lui de vérifier le compte Foliade connecté. Envoyez le PDF seulement lorsque les outils sont disponibles et que l’adresse du compte a été confirmée.

(http.host eq "foliade.gekkode.com" and (
  http.request.uri.path in {
    "/mcp" "/authorize" "/token" "/register" "/revoke"
    "/.well-known/oauth-authorization-server"
    "/.well-known/oauth-protected-resource"
    "/.well-known/oauth-protected-resource/mcp"
  }
  or starts_with(http.request.uri.path, "/mcp/uploads/")
))