Sécurité du serveur MCP

Cette page s’adresse à la personne qui doit approuver la connexion d’un agent IA à Docsbook. Elle décrit 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 indique, 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 jeton Bearer opaque, lié à un compte Docsbook, et portant l’une de deux portées. La portée est choisie par une personne sur un écran de consentement — elle n’est pas demandée par le client. Chaque outil qui agit sur un projet détermine ce projet par son propriétaire ; ainsi, un jeton qui désigne l’identifiant d’un espace de travail appartenant à quelqu’un d’autre ne renvoie rien, et non cet espace : c’est la limite entre les locataires, et elle s’applique à tous les outils.

La limite entre la lecture et l’écriture est plus étroite que ne le suggèrent les deux noms de portée, et la section ci-dessous indique précisément quels outils l’appliquent et lesquels ne l’appliquent pas. Lisez-la avant de considérer un jeton en lecture seule comme une mesure de confinement.

Chaque appel comptabilisé ajoute une ligne au journal d’appels de votre propre projet : quel outil a été utilisé, ce qui a été envoyé, ce qui a été renvoyé, le temps pris et ce qu’il a consommé. Les arguments et les résultats sont expurgés par clé avant leur stockage, de sorte qu’une clé API transmise à un outil n’est jamais enregistrée.

Ce que vous n’obtenez pas : l’expiration des jetons, des jetons d’actualisation, la limitation du débit, des 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 un tiers.

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’existe ni secret client ni octroi d’identifiants client.

Ce qu’est le jeton#

Le jeton est constitué de 48 octets générés par le CSPRNG de la plateforme, représentés par 96 caractères hexadécimaux. Il ne contient aucune revendication : c’est 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 — aucun cache ne se trouve devant celle-ci.
• 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 chiffré au repos est indiqué dans la section 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 permet de faire#

La portée est une chaîne unique comparée à l’identique. Toute valeur qui n’est pas la portée d’écriture est traitée 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 à quatre outils : write_docs, create_issue, connect_source et configure_source. Ceux-ci refusent un jeton en lecture seule avant toute action.

Tout autre outil qui modifie 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 — est limité 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 dont le compte est propriétaire. 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 signifiant « ne peut pas publier ni mettre en place de nouvelles fonctionnalités », et non comme « ne peut rien modifier ». Si le cloisonnement est plus important, utilisez un compte Docsbook distinct qui n’est propriétaire que du projet que vous acceptez d’exposer. Il s’agit d’un défaut, répertorié à nouveau sous limites, et non d’un choix de conception.

Un outil qui applique effectivement cette vérification répond à un jeton en lecture seule par une erreur structurée READ_ONLY_TOKEN indiquant le nom de l’outil et la manière de s’authentifier à nouveau — et non par un simple 403, ni par une absence de réponse silencieuse. La même structure 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 nom du niveau).

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 jamais lire que le site auquel il est associé.

Ce qu’un jeton ne peut pas atteindre#

Chaque outil détermine son espace de travail cible à partir de 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 de projet d’un tiers ne permet donc pas non plus de débiter le solde d’un tiers.

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

• write_docs valide les modifications dans le dépôt hébergé par Docsbook avec les propres identifiants GitHub de Docsbook. Un site fourni depuis un dépôt de votre propre compte GitHub est refusé avec NO_GITHUB_ACCESS, au lieu d’y être validé. Un jeton MCP ne permet donc pas d’envoyer des modifications vers votre organisation GitHub.
• Une compétence exécutée en mode audit ne peut pas effectuer de modification. 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. Le lanceur qui activait autrefois ce mode pour toute une exécution côté serveur a été supprimé le 12.09.2026 ; la protection s’applique donc désormais à un tour ayant préchargé une compétence audit et rien d’autre.

Qu’est-ce qui est enregistré#

Chaque appel MCP — facturé ou non, réussi ou non — écrit une ligne dans le 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. Elle recherche la clé, sans tenir compte de la casse et comme une sous-chaîne, et non la forme de la valeur — deviner à quoi ressemble un secret est une approche qui lui échappe. Elle s’exécute également à la sortie comme à l’entrée, afin qu’un outil qui renvoie ses propres données d’entrée 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’adresse e-mail. Le pseudonyme est propre à un seul dépôt : le même lecteur sur deux de vos sites correspond donc à deux identifiants sans rapport.

Ce qui quitte votre espace de travail#

Deux affirmations que l’on trouve généralement sur la page de sécurité d’un fournisseur de documentation, corrigé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 ainsi que ses représentations vectorielles, et envoie le texte des pages à un fournisseur de modèles pour créer ces représentations 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 met fin au travail facturé à l’usage sans supprimer vos fichiers 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 — la vérification est également réexécutée à chaque étape de redirection, de sorte qu’une URL publique ne puisse pas rediriger vers une URL interne. robots.txt est respecté et la réponse est plafonnée. Le récupérateur de compétences est encore plus limité : 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 arbitraire.

Les webhooks et les hooks de chat 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 enregistrée sous forme tronquée.

Les hooks de chat ne comportent aucune signature. Les hooks pré-, post- et de streaming de l'assistant de documentation sont de simples JSON POST 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 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 hook de chat 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 concerne votre client plutôt que nous : la spécification MCP demande 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#

Liste établie 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 document spécifique — un DPA conforme au RGPD, un BAA, un questionnaire rempli — écrivez à support@docsbook.io pour demander ce qui existe. La réponse aujourd’hui pourrait très 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 antérieure de cette page mentionnait 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 d’un hachage salé d’une adresse IP tronquée à 64 bits. Toute personne détenant le sel et le magasin d’événements bruts pourrait le recalculer ; la garantie est que le sel ne se trouve 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 ce dernier.
• Un jeton en lecture-écriture est un identifiant d’administration complet. Il n’est pas possible d’autoriser « peut modifier les pages, mais ne peut pas changer les paramètres » ou « peut lire les analyses, mais pas les transcriptions de chat ». L’échelle des niveaux d’accès comporte deux échelons.
• La portée en lecture seule est appliquée de manière incomplè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 affirment eux-mêmes qu’ils nécessitent un jeton en lecture-écriture alors qu’aucun contrôle ne l’effectue. 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 usages par compte et consultez la liste effectivement contrôlée ci-dessus plutôt que la description d’un outil.
• Rien de ce qui est présenté ici 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 ne se résout pas — 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 sont indiqués sur la page des tarifs. Aucun chiffre n’est indiqué ici, car un prix copié dans la documentation devient obsolète sans que personne ne s’en aperçoive.

Rubriques 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 façon dont elles s’articulent
• Compétences de documentation — 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 du chat IA — les hooks pre/post/streaming non signés
• Sources — ce qu’un agent est autorisé à lire en votre nom