Sécurité du serveur MCP

Cette page s’adresse à la personne qui doit approuver la connexion d’un agent d’IA à Docsbook. Elle indique ce que fait réellement le serveur MCP aujourd’hui — comment un client s’authentifie, ce que chaque portée peut atteindre, ce qui est consigné, ce qui quitte le réseau — puis précise, dans deux sections distinctes, les points sur lesquels Docsbook ne respecte pas la spécification du Model Context Protocol et les artefacts de conformité qui n’existent pas encore.

Rien de ce qui est présenté ici n’est prospectif. Lorsqu’un contrôle est absent, il est indiqué comme tel.

Ce que vous obtenez#

Un client connecté détient un unique jeton Bearer opaque, lié à un compte Docsbook, et porteur de l’une de deux portées. La portée est choisie par un humain sur un écran de consentement — elle n’est pas demandée par le client. Chaque outil qui agit sur un projet identifie ce projet par son propriétaire, de sorte qu’un jeton qui indique l’identifiant d’un espace de travail appartenant à quelqu’un d’autre ne renvoie rien, et non cet espace : c’est la frontière entre les locataires, et elle s’applique à tous les outils.

La frontière entre la lecture et l’écriture est plus étroite que ne le laissent entendre les deux noms de portée, et la section ci-dessous indique exactement quels outils l’appliquent et lesquels ne le font pas. Lisez-la avant de considérer un jeton en lecture seule comme une mesure de cloisonnement.

Chaque appel facturé écrit une ligne dans le journal des appels de votre projet : quel outil a été utilisé, ce qui a été envoyé, ce qui a été renvoyé, le temps qu’il a fallu et ce qu’il a consommé. Les arguments et les résultats sont expurgés par clé avant d’être stockés, de sorte qu’une clé d’API transmise à un outil n’est jamais enregistrée.

Ce que vous n’obtenez pas : l’expiration des jetons, les jetons d’actualisation, la limitation du débit, les rôles au sein d’un compte ou un rapport d’audit.

Fonctionnement de l’authentification#

Le flux d’autorisation#

Docsbook est son propre serveur d’autorisation et son propre serveur de ressources. Il émet des jetons opaques pour lui-même ; il n’accepte, ne transmet et ne réutilise jamais un jeton émis par quelqu’un d’autre.

Les métadonnées publiées déclarent un modèle de client public — code_challenge_methods_supported: ["S256"], token_endpoint_auth_methods_supported: ["none"], grant_types_supported: ["authorization_code"]. Il n’y a ni secret client ni flux d’identifiants client.

Ce qu'est le jeton#

Le jeton est composé de 48 octets issus du CSPRNG de la plateforme, représentés par 96 caractères hexadécimaux. Il ne contient aucune revendication : il s'agit d'une clé de recherche vers une ligne contenant le compte, la portée et un horodatage de révocation.

• Il n'expire pas. Aucun expires_in n'est renvoyé et aucun jeton d'actualisation n'est émis. Un jeton est valide jusqu'à sa révocation.
• La révocation est immédiate. La révocation depuis le panneau horodate la ligne, et chaque appel ultérieur échoue lors de la recherche — il n'y a aucun cache en amont.
• Il est stocké tel qu'il a été émis, et non haché. Traitez un jeton MCP Docsbook comme vous traiteriez un mot de passe : si la machine qui le détient est compromise, révoquez-le plutôt que de supposer qu'il a expiré avec le temps. (Ce qui est effectivement chiffré au repos est indiqué sous ce qui quitte votre espace de travail.)
• La dernière utilisation est enregistrée à chaque appel, de sorte qu'un jeton inutilisé reste visible dans la liste des jetons du panneau.

Ce que chaque portée peut faire#

La portée est une chaîne unique comparée exactement. Tout ce qui n’est pas la portée d’écriture est traité comme étant en lecture seule — une valeur non reconnue est refusée par défaut.

La vérification de la portée ne couvre pas encore tous les outils d’écriture, et vous devez en tenir compte dans votre planification. Elle est appliquée exactement à huit outils : write_docs, create_issue, connect_source, configure_source, enable_agent et les trois exécutions de run_docs_* qui écrivent. Ceux-ci refusent un jeton en lecture seule avant toute action.

Tous les autres outils qui modifient l’état — les outils d’écriture des paramètres update_* et set_*, update_access, l’enregistrement et la suppression de webhooks, la création d’objectifs et d’entonnoirs, l’importation, l’approbation et la suppression de traductions, create_workspace — sont contrôlés uniquement par la propriété du projet, et non par la portée. Un jeton en lecture seule peut donc modifier les paramètres d’un projet, activer un webhook ou supprimer une traduction sur un projet détenu par son compte. Il ne peut toutefois pas valider une page, créer un ticket, connecter une source ou activer un agent.

Considérez la portée en lecture seule comme « ne peut pas publier ni connecter de nouvelles fonctionnalités », et non comme « ne peut rien modifier ». Si le cloisonnement est plus important pour vous, utilisez un compte Docsbook distinct qui ne possède que le projet que vous êtes disposé à exposer. Il s’agit d’un défaut, répertorié à nouveau sous limites, et non d’un choix de conception.

Un outil qui applique cette vérification répond à un jeton en lecture seule par une erreur READ_ONLY_TOKEN structurée indiquant le nom de l’outil et la manière de réautoriser l’accès — et non par un simple 403, ni par une absence d’opération silencieuse. Le même format s’applique lorsque le solde d’un projet est épuisé (INSUFFICIENT_BALANCE, avec le nom du projet, le prix et le solde restant) et lorsqu’un forfait n’inclut pas la fonctionnalité (PLAN_RESTRICTION, avec le niveau indiqué).

Le search anonyme est le seul outil sans jeton qui lit un projet, et il est refusé de trois façons : sur un endpoint associé à aucun projet, pour un projet dont la visibilité est privée (ce qui couvre également un forfait arrivé à expiration), et lorsque le projet n’a plus de solde pour payer l’intégration de la requête. Il n’accepte aucun argument de projet et ne peut donc lire que le site auquel il est associé.

Ce qu’un seul jeton ne peut pas atteindre#

Chaque outil détermine son espace de travail cible à partir du workspace_id explicite, de l’argument repo, ou de l’ancrage propre au point de terminaison — et, dans les trois cas, la recherche est filtrée par le compte du jeton. Un espace de travail que le compte ne possède pas ne renvoie aucun résultat, et l’outil répond « espace de travail introuvable ». Le résolveur de facturation applique le même filtre : indiquer l’identifiant du projet d’un tiers ne peut donc pas non plus débiter le solde d’un tiers.

Deux autres limites méritent d’être précisées, car elles surprennent les utilisateurs :

• write_docs enregistre les modifications dans le dépôt hébergé par Docsbook en utilisant les propres identifiants GitHub de Docsbook. Un site hébergé depuis un dépôt de votre propre compte GitHub est refusé avec NO_GITHUB_ACCESS au lieu d’y être enregistré. Un jeton MCP ne permet donc pas de pousser des modifications vers votre organisation GitHub.
• Une compétence exécutée en mode audit ne peut pas modifier l’état. Lorsqu’une compétence en mode audit est active, une liste explicite d’outils d’écriture ainsi que tout outil dont le nom commence par update_, set_, register_webhook_, enable_ ou disable_ sont refusés avant leur exécution. run_docs_analyze active ce mode pour toute son exécution, ce qui explique pourquoi son utilisation avec un jeton en lecture seule est sûre.

Qu'est-ce qui est enregistré#

Chaque appel MCP — facturé ou non, abouti ou non — ajoute une ligne au registre des appels du projet, que le propriétaire du projet peut consulter dans le panneau Feeds.

Deux détails de l'expurgation sont importants pour la vérification. La correspondance se fait sur la clé, sans tenir compte de la casse et comme sous-chaîne, et non sur la forme de la valeur — deviner à quoi ressemble un secret est une forme qu'elle ne détecte pas. Elle s'effectue aussi lors de la transmission sortante que lors de la transmission entrante, de sorte qu'un outil qui renvoie ses propres entrées ne puisse pas divulguer une clé dans son résultat. Chaque côté est limité à 8 000 caractères, avec un marqueur indiquant le nombre de caractères supprimés.

Les analyses au niveau du lecteur ne transmettent jamais d'identité à un client MCP. Un visiteur est un pseudonyme : sha256(salt | repository | ip), tronqué à 16 caractères hexadécimaux, le sel étant conservé côté serveur. get_top_visitors, get_page_journeys et get_visitor_activity renvoient ce pseudonyme, un pays et des événements au niveau de la page ; aucun outil ne renvoie d'adresse IP, de nom ou d'e-mail. Le pseudonyme est limité à un seul dépôt, de sorte que le même lecteur sur deux de vos sites corresponde à deux identifiants sans lien.

Ce qui quitte votre espace de travail#

Deux affirmations généralement formulées sur la page de sécurité d'un fournisseur de documentation, rectifiées :

• « Votre contenu ne quitte jamais votre dépôt » n'est pas vrai ici. Docsbook stocke une copie consultable du texte de vos pages et de leurs intégrations vectorielles, et envoie le texte des pages à un fournisseur de modèles pour créer ces intégrations et répondre aux appels de chat et d'agents. Ce qui est vrai, c'est que GitHub reste la source de vérité : l'arrêt du paiement interrompt le travail mesuré sans supprimer votre Markdown.
• Les récupérations sortantes sont protégées, et pas simplement considérées comme fiables. Avant toute récupération, le schéma est vérifié, le nom d'hôte est résolu et toute adresse résolue appartenant à une plage privée ou réservée est refusée — et la vérification est répétée à chaque étape de redirection, de sorte qu'une URL publique ne puisse pas aboutir à une URL interne. robots.txt est respecté et la réponse est limitée. Le récupérateur de skills est encore plus restrictif : il ne récupère des données que depuis l'hôte et le préfixe de chemin propres au catalogue, et ne peut donc pas être transformé en proxy d'URL arbitraires.

Les webhooks et les chat hooks ne sont pas la même chose#

Les livraisons de webhooks sortants sont signées. La signature est un HMAC-SHA256 calculé sur les octets exacts envoyés, dans X-Docsbook-Signature-256: sha256=<hex>, avec X-Docsbook-Event. Une URL de webhook entrant Discord ou Slack est adaptée à cette plateforme avant la signature, de sorte que la signature couvre toujours ce que votre endpoint reçoit effectivement. Le secret est défini lors de l'enregistrement, comporte au moins 16 caractères et n'est jamais renvoyé en clair par la suite. Les tentatives de livraison expirent au bout de 15 secondes et la réponse est stockée sous forme tronquée.

Les chat hooks ne comportent aucune signature. Les hooks pré-, post- et de streaming de l'assistant de documentation sont de simples objets JSON POSTs, avec un délai d'expiration de 5 secondes et sans en-tête HMAC. Ne réutilisez pas votre code de vérification des webhooks à cet endroit en supposant qu'il a vérifié quoi que ce soit. Le pré-hook peut également renvoyer inject_context, dont le texte est intégré au prompt de l'assistant — un endpoint vers lequel vous dirigez un chat hook peut donc influencer ce que dit l'assistant ; traitez-le comme une infrastructure de confiance, authentifiez-le par un autre moyen et ne le dirigez pas vers une URL que vous ne contrôlez pas.

Pourquoi c’est la bonne méthode (preuves)#

Un dernier point relève de votre client plutôt que de nous : la spécification MCP indique aux clients de « considérer les annotations des outils comme non fiables, sauf si elles proviennent de serveurs de confiance », et de maintenir « un humain dans la boucle ayant la possibilité de refuser les invocations d’outils » (Outils MCP). Un jeton Docsbook en lecture-écriture est précisément le cas qui mérite cette intervention humaine.

Là où Docsbook ne respecte pas aujourd’hui la spécification MCP#

Ces éléments sont évalués par rapport à la révision 2026-07-28. Chacun constitue une lacune de Docsbook, et non un désaccord avec la spécification.

Ce que Docsbook n’a pas encore#

Répertorié afin qu’un examen puisse écarter Docsbook en une heure plutôt qu’à la troisième semaine.

Une fonctionnalité est régulièrement confondue avec les deuxième et quatrième lignes : un espace de travail privé peut être protégé par un mot de passe ou par votre propre fournisseur OIDC via update_access, avec tous les forfaits. Il s’agit de l’authentification unique pour les lecteurs de votre site de documentation. Il ne s’agit pas de l’authentification unique pour les membres de votre compte Docsbook, et cela n’accorde aucun accès MCP.

Si votre organisation a besoin d’un artefact précis — un DPA conforme au RGPD, un BAA, un questionnaire rempli — écrivez à support@docsbook.io et demandez ce qui existe. La réponse aujourd’hui pourrait bien être que cela n’existe pas.

Limites et questions en suspens#

• Question en suspens : régions d’hébergement. Cette page ne nomme délibérément aucune région pour la base de données ou le magasin analytique. Il s’agit dans les deux cas de services gérés dont la région est un paramètre de déploiement plutôt qu’un élément qu’un lecteur peut vérifier à partir du comportement de Docsbook, et une version précédente de cette page nommait des régions sans source. Demandez au support la réponse actuelle par écrit si la résidence des données fait partie de votre évaluation.
• L’identifiant pseudonyme du visiteur est un pseudonyme, pas une anonymisation. Il s’agit du hachage salé d’une adresse IP tronquée à 64 bits. Toute personne détenant le sel et le stockage brut des événements pourrait le recalculer ; la garantie est que le sel ne figure pas dans les données et qu’aucune API ne renvoie d’adresse IP. La question de savoir si cela satisfait votre organisme de réglementation relève de celui-ci.
• Un jeton de lecture-écriture est un identifiant d’administration complet. Il n’est pas possible d’accorder le droit « peut modifier les pages, mais ne peut pas modifier les paramètres » ou « peut consulter les statistiques, mais pas les transcriptions des discussions ». L’échelle des autorisations comporte deux niveaux.
• La portée en lecture seule n’est pas appliquée de manière complète. Huit outils la vérifient ; les outils d’écriture des paramètres, des webhooks, des objectifs et des traductions ne le font pas, et les descriptions de certains de ces outils indiquent elles-mêmes qu’ils nécessitent un jeton de lecture-écriture alors qu’aucune vérification n’est effectuée. Tant que ce problème n’est pas résolu, la limite fiable est la propriété du compte, et non la portée : isolez donc les projets par compte et consultez la liste appliquée ci-dessus plutôt que la description d’un outil.
• Rien de tout cela n’a fait l’objet d’une attestation indépendante. Chaque affirmation ci-dessus peut être vérifiée dans le comportement de Docsbook — émettez un jeton en lecture seule et observez un outil d’écriture le refuser ; connectez un projet dont vous n’êtes pas propriétaire et observez qu’il n’est pas résolu — mais aucun tiers ne l’a audité. Considérez cette page comme une spécification que vous pouvez tester, et non comme une certification.
• La disponibilité et le prix figurent sur la page des tarifs. Aucun montant n’est indiqué ici, car un prix copié dans la documentation devient obsolète en silence.

Connexes#

• Serveur MCP — les outils eux-mêmes et ce sur quoi s’appuie un appel
• Contenu prêt pour les agents — les quatre interfaces machine et la manière dont elles s’articulent
• Compétences Docs — ce qu’une compétence peut et ne peut pas faire pendant son exécution
• Webhooks — le schéma complet des événements et la vérification des signatures
• Hooks de chat IA — les hooks non signés avant, après et pendant le streaming
• Sources — ce qu’un agent est autorisé à lire en votre nom