Passer au contenu principal

À propos du serveur Admin MCP

Le serveur Admin MCP donne aux outils d’IA un accès en écriture à votre contenu et à vos paramètres Mintlify. Utilisez-le pour mettre à jour le contenu et accéder à votre tableau de bord. Avec l’Admin MCP, vous pouvez utiliser vos outils d’IA préférés pour modifier des pages, restructurer la navigation, mettre à jour docs.json, ouvrir des pull requests, modifier des paramètres, créer des workflows, et plus encore. Connectez n’importe quel client MCP comme Claude, Claude Code, ChatGPT ou Cursor au serveur Admin MCP. Utilisez-le pour collaborer sur votre contenu et vos paramètres Mintlify avec les mêmes outils que vous utilisez pour écrire du code. Les modifications de contenu se produisent sur une branche et sont livrées via une pull request ou un commit lorsque vous appelez save. Les changements de gestion de projet, tels que les mises à jour de workflows et de paramètres, s’appliquent immédiatement au projet en ligne. Si votre organisation dispose de plusieurs projets, une seule connexion Admin MCP peut accéder à tous ces projets et basculer entre eux.
Le serveur Admin MCP permet aux outils d’IA d’accéder à votre tableau de bord Mintlify. Considérez-le comme un outil avec un accès en écriture. Connectez-le uniquement depuis des outils d’IA de confiance, examinez chaque pull request avant de la fusionner, et sachez que les changements de gestion de projet s’appliquent immédiatement, sans pull request.
L’Admin MCP est un service Mintlify hébergé à l’adresse https://mcp.mintlify.com. Chaque client se connecte au même endpoint et s’authentifie avec votre compte Mintlify.

En quoi l’Admin MCP diffère des autres serveurs MCP Mintlify

Consultez la référence MCP de Mintlify Index pour connaître les paramètres de ses outils et ses limites de débit.

Prérequis

Avant de connecter l’Admin MCP, confirmez ce qui suit :
  • Compte Mintlify : Vous avez besoin d’un compte Mintlify avec accès au projet que vous souhaitez modifier. La session OAuth hérite de vos autorisations du tableau de bord, donc les actions réservées aux administrateurs (telles que update_config sur les paramètres protégés) nécessitent un rôle d’administrateur sur le projet.
  • Accès au fournisseur Git : La connexion GitHub, GitLab ou Bitbucket du projet doit avoir un accès en écriture au dépôt de la branche de déploiement. save ouvre des PR via la même intégration que celle utilisée pour les déploiements normaux.
  • Client MCP : Un outil d’IA compatible MCP tel que Claude, Claude Code, ChatGPT, Cursor ou Codex.

Se connecter à l’Admin MCP

Vous devez disposer d’une connexion OAuth interactive à votre compte Mintlify pour vous connecter à l’Admin MCP. Les outils d’IA échangent cette connexion contre un jeton de session limité à un ou plusieurs projets, selon la manière dont vous accordez l’accès. Une connexion limitée à des projets spécifiques ne peut faire de checkout que sur ces projets. Une connexion à l’échelle de l’organisation peut faire le checkout de n’importe quel projet de votre organisation.
1

Ajouter l'Admin MCP comme connecteur personnalisé

  1. Accédez à la page Connectors dans les paramètres de Claude.
  2. Cliquez sur Add custom connector.
  3. Ajoutez le connecteur :
    • Nom : Admin MCP
    • URL : https://mcp.mintlify.com
  4. Cliquez sur Add et terminez la connexion OAuth.
2

Utiliser le MCP dans une conversation

Cliquez sur le bouton des pièces jointes (l’icône plus), puis sélectionnez votre serveur Admin MCP. Claude peut maintenant appeler les outils Mintlify Admin MCP tout en répondant à votre prompt.

Comment fonctionne une session

Chaque session Admin MCP est liée à une seule branche Git. Le flux est le suivant :
1

Découvrir les projets (facultatif)

Si votre connexion a accès à plusieurs projets, appelez list_deployments pour voir les valeurs de subdomain que vous pouvez utiliser dans checkout. Passez cette étape si votre connexion ne couvre qu’un seul projet.
2

Extraire une branche

Le premier appel requis est checkout {subdomain}. Il crée une nouvelle branche admin-mcp/<slug>-<sha> à partir de la branche de déploiement de ce projet (ou se rattache à une branche existante que vous nommez). Il renvoie également une editorUrl que vous pouvez ouvrir pour suivre l’évolution dans l’éditeur du tableau de bord.Pour ignorer la branche de session et modifier directement votre branche de déploiement, passez-la comme branch. Consultez Modifier directement la branche de déploiement.Appelez list_branches avant checkout si vous avez besoin de découvrir ou de filtrer les branches existantes du dépôt d’un projet.
3

Lire, rechercher et modifier

L’IA utilise des outils tels que search, read, list_nodes, edit_page, write_page, create_node et update_config pour effectuer des modifications. Toutes les modifications sont mises en mémoire tampon sur la branche de session en temps réel. Rien ne touche encore votre branche de déploiement.
4

Examiner le diff

Appelez diff à tout moment pour voir exactement ce qui a changé depuis votre branche de déploiement. Ouvrez une editorUrl dans votre tableau de bord pour voir les mêmes changements rendus. Lorsque create_node ajoute une page, il renvoie une editorUrl qui ouvre directement cette page.
5

Enregistrer

Appelez save pour pousser la branche vers Git. mode: "auto" (par défaut) ouvre une pull request. Si le paramètre de revue de l’agent du projet est push-to-main et que la branche de déploiement n’est pas protégée, Mintlify fusionne immédiatement la pull request (la réponse inclut merged: true). Utilisez mode: "pr" pour toujours ouvrir une pull request et la laisser ouverte pour révision. Utilisez mode: "commit" pour pousser directement sur une branche de PR existante sans ouvrir de nouvelle PR.Lorsque save ouvre ou met à jour une pull request, la réponse inclut une editorUrl qui ouvre la première page créée ou modifiée sur la branche. Si les changements ne concernent que la configuration, le lien ouvre la branche. Les sauvegardes fusionnées immédiatement ne renvoient pas d’editorUrl.
6

Abandonner si nécessaire

Appelez discard_session pour abandonner toutes les modifications en session et libérer la branche.
Si votre connexion a accès à plusieurs projets, chaque projet dont vous faites le checkout conserve sa propre session et sa propre branche en mémoire simultanément.Appeler checkout à nouveau avec un subdomain ou une branche différente change la session active. Cela ne supprime pas les autres. Pour abandonner un brouillon en cours plutôt que de simplement en changer, appelez discard_session.

Modifier directement la branche de déploiement

Passez votre branche de déploiement à checkout pour la modifier comme dans l’éditeur du tableau de bord. Par exemple, checkout { subdomain: "acme", branch: "main" }. Mintlify lie la session à la branche de déploiement au lieu de créer une branche admin-mcp/*. Le checkout est plus rapide et aucune pull request n’est créée. L’outil d’IA agit en votre nom sur la branche de déploiement :
  • Les modifications sont visibles en direct par les collaborateurs. Toute autre personne qui modifie la branche de déploiement dans le tableau de bord voit les modifications de l’IA au fur et à mesure.
  • save publie uniquement vos modifications. Il ignore mode et commite vos modifications en attente directement sur la branche de déploiement, comme un clic sur Publish dans l’éditeur. Les modifications non publiées des autres restent en attente. Vos propres modifications non publiées dans l’éditeur du tableau de bord sont également publiées.
  • discard_session annule uniquement vos modifications. Il renvoie discardedChanges avec le nombre de modifications annulées. Les modifications des autres et la branche elle-même restent intactes.
  • get_session_state liste uniquement vos modifications.
Mintlify suit les modifications par page. Si vous et une autre personne avez modifié la même page, save publie la page entière et discard_session annule la page entière, y compris les modifications de l’autre personne. Dans l’un des cas suivants, Mintlify crée plutôt une branche de session à partir de la branche de déploiement. checkout renvoie une note qui en explique la raison :
  • La protection de votre branche de déploiement exige des pull requests, ou Mintlify ne peut pas vérifier vos règles de protection de branche.
  • La modification de la branche de déploiement est verrouillée dans l’éditeur du tableau de bord.
  • Pousser directement sur votre branche de déploiement est désactivé dans vos paramètres de publication.
  • Vous vous êtes connecté avec un jeton client ou machine à machine au lieu d’une connexion OAuth. Ces jetons ne sont pas liés à un utilisateur et n’ont donc pas de modifications « propres ».

Publication

La section Publication de la page des paramètres de l’Admin MCP dans votre tableau de bord contrôle ce qui se passe lorsque save s’exécute avec mode: "auto". Activez Pousser directement sur votre branche de déploiement pour que Mintlify pousse les modifications directement sur votre branche de déploiement. Désactivez-la pour que save ouvre une pull request à la place. Ce bouton partage le même paramètre agentReviewProcess que l’agent Slack et l’agent du tableau de bord, donc toute modification ici s’applique également à ces flux. Le bouton est désactivé dans trois cas :
  • Votre branche de déploiement requiert une pull request. Si des règles de protection de branche ou des approbations requises empêchent les push directs, les modifications MCP ouvrent toujours une pull request, quel que soit ce paramètre.
  • Mintlify héberge votre projet. Pour les sites hébergés par Mintlify, les modifications MCP sont toujours poussées directement, sauf si la protection de branche exige tout de même une pull request.
  • Vous n’êtes pas administrateur. La modification de ce paramètre requiert le rôle d’administrateur sur votre projet. Les éditeurs et les lecteurs voient le bouton désactivé avec une bannière de permission.
Vous pouvez également remplacer ce paramètre appel par appel en passant un mode explicite à save. Définissez "pr" pour toujours ouvrir une pull request, ou "commit" pour pousser sur une branche de PR existante sans ouvrir de nouvelle PR.

Ce que l’Admin MCP peut faire

Contenu

  • read: Récupère le MDX complet de n’importe quelle page sur la branche de session. Transmettez un chemin de page comme /quickstart, ou l’ID de page d’une URL de l’éditeur (le segment après ~/), pour qu’un outil d’IA puisse ouvrir une page directement depuis un lien de l’éditeur. Pour lire une page privée, transmettez son ID de nœud private-page-<uuid> obtenu depuis list_nodes avec visibility: "private". Les lectures privées fonctionnent sans checkout et nécessitent une session OAuth. L’Admin MCP refuse les jetons client et machine à machine pour l’accès aux pages privées.
  • search: Trouve les lignes correspondant à une sous-chaîne ou à une expression régulière dans toutes les pages.
  • edit_page: Applique une modification ciblée à une page. Pour modifier une page privée, transmettez son ID de nœud private-page-<uuid> comme path. Les modifications privées nécessitent une session OAuth avec un rôle d’editor ou supérieur sur la page et fonctionnent sans checkout.
  • write_page: Réécrit le contenu MDX complet d’une page. Accepte un ID de nœud private-page-<uuid> pour réécrire une page privée avec les mêmes exigences OAuth et de rôle que edit_page. Utilisez create_node pour créer une nouvelle page privée.

Images

  • upload_image : Démarre le téléversement d’un fichier image local vers la branche de session. Transmettez le path de destination (par exemple, images/dashboard.png), le contentType du fichier et sa size exacte en octets. Renvoie un uploadId, une uploadUrl présignée et les headers à envoyer avec le téléversement.
  • finalize_image_upload : Enregistre l’image téléversée sur la branche de session. Transmettez l’uploadId et le même path. Renvoie le src à référencer dans le MDX avec edit_page ou write_page, ou dans les champs logo ou favicon de docs.json avec update_config.
Après upload_image, l’outil d’IA téléverse les octets du fichier vers uploadUrl avec une requête PUT et les en-têtes renvoyés. Par exemple :
Mintlify vérifie que le contenu du fichier téléversé correspond à son extension avant de l’enregistrer. Un téléversement vers un path existant remplace cette image. Mintlify n’accepte les fichiers SVG que pour les logos et les favicons : transmettez purpose: "logo" aux deux outils lorsque vous en téléversez un. Les images enregistrées apparaissent dans get_session_state et sont publiées avec le reste de la session lorsque vous appelez save.
  • list_nodes: Parcourt l’arbre de navigation avec des filtres optionnels. Filtrez par parentId (utilisez recursive: true pour inclure tous les descendants), un ou plusieurs types de nœuds, ou n’importe quel scope de division : language, version, tab, dropdown, anchor, product ou item. Les résultats se paginent via un cursor opaque. Transmettez visibility: "private" pour lister les pages privées et dossiers auxquels l’utilisateur OAuth a accès, au lieu de l’arbre de navigation de la branche. Le listing privé fonctionne sans checkout, ignore les autres filtres et renvoie le role de chaque nœud.
  • create_node: Ajoute une nouvelle page, un groupe, un onglet, une ancre, une version, une langue, un produit ou une liste déroulante. Transmettez visibility: "private" avec data.type: "page" ou data.type: "group" pour créer une page privée ou un dossier privé dans l’arbre privé de l’appelant. L’appelant devient le manager du nœud. La création privée nécessite une session OAuth, fonctionne sans checkout et place le nœud à la racine privée ou sous un parent private-folder-<uuid> existant. Pour les nouvelles pages, la réponse inclut une editorUrl qui ouvre la page dans votre tableau de bord.
  • update_node: Met à jour les propriétés d’un nœud sur place (renommer un groupe, modifier une icône, définir une version par défaut). Accepte un ID de nœud private-page-<uuid> ou private-folder-<uuid> pour renommer une page privée ou un dossier, ou changer son icône ou son tag. Les mises à jour privées nécessitent une session OAuth avec un rôle d’editor ou supérieur et fonctionnent sans checkout.
  • move_node: Déplace un nœud, y compris renommer le chemin d’une page.
  • delete_node: Supprime un nœud de la navigation. Accepte un ID de nœud private-page-<uuid> ou private-folder-<uuid> pour supprimer une page privée ou un dossier de l’arbre privé de l’appelant. Les suppressions privées nécessitent une session OAuth avec un rôle de manager sur le nœud et fonctionnent sans checkout.
Si un appel à create_node, update_node, move_node ou delete_node laisse la navigation dans un état invalide, la réponse inclut un champ navigationErrors qui décrit le problème. Par exemple, une page placée à la racine à côté d’onglets renvoie navigationErrors. Mintlify peut retirer les nœuds invalides de la navigation publiée. Corrigez donc ces erreurs avant d’appeler save.

Configuration

  • update_config: Modifie docs.json (thème, racines de navigation, intégrations, paramètres SEO).

Gestion de projet

Les outils de gestion de projet gèrent les opérations au niveau du projet, comme la gestion des workflows, des paramètres de projet, des domaines personnalisés, des sources Git, de l’authentification, des membres, des analyses et du partage des pages privées. Ils ne nécessitent pas de checkout. Chaque outil prend un subdomain correspondant au projet ciblé. Les connexions à l’échelle de l’organisation doivent transmettre subdomain. Appelez list_deployments pour le trouver. Les outils de lecture acceptent aussi subdomains, une liste de 25 projets maximum, et renvoient un résultat ou une erreur pour chacun. La plupart des outils prennent un objet request dont le champ action sélectionne l’opération. Par exemple :
Outils de lecture :
  • get_deployment_settings: Lit en un seul appel les paramètres du dashboard d’un projet, ses sources Git, l’état de ses noms d’hôte personnalisés et ses vérifications de sources. La configuration Slack et les snippets sont facultatifs.
  • get_analytics_report: Lit un rapport d’analyse prédéfini, comme les pages vues, les pages populaires, les référents, les retours, les conversations de l’assistant ou la qualité de la recherche. Sélectionnez le rapport avec request.report. Les résultats volumineux sont paginés avec maxRows et rowOffset. Pour des requêtes personnalisées, utilisez query_analytics.
  • get_workflows: Liste les workflows, récupère un workflow ou parcourt ses exécutions.
  • list_repos_and_prs: Liste les dépôts connectés, les pull requests d’un dépôt ou les intégrations disponibles pour un workflow.
Outils d’écriture :
  • update_deployment_settings: Modifie un paramètre du dashboard, comme noindex, base_path, name, disable_ai_chat, search_settings, privacy, custom_scripts ou un module complémentaire. Utilisez update_config pour les paramètres de docs.json.
  • manage_custom_domain: Ajoute ou supprime un domaine personnalisé, provisionne son nom d’hôte ou relance la validation du nom d’hôte.
  • manage_git_source: Ajoute, met à jour, supprime ou réordonne les dépôts Git à partir desquels un projet est compilé, ou définit la source de base.
  • manage_access_auth: Configure ou supprime l’authentification du site, ajoute ou supprime des mots de passe, configure l’authentification des utilisateurs finaux ou change celle qui est active.
  • manage_workflow: Crée, met à jour, active ou désactive, supprime ou déclenche un workflow.
  • manage_members_sharing: Liste ou retire des membres de l’organisation, met à jour leurs rôles ou gère les autorisations et déplacements des pages privées.
Les outils d’écriture renvoient l’état mis à jour du projet dans state, afin que l’outil d’IA puisse confirmer la modification sans second appel. Chaque action vérifie les scopes accordés à la connexion et votre rôle dans le dashboard. Une action pour laquelle vous n’êtes pas autorisé renvoie une erreur comme insufficient_scope.
Les écritures de gestion de projet s’appliquent immédiatement au projet en ligne. Elles ne créent pas de branche et n’ouvrent pas de pull request. Confirmez la modification prévue avant de demander à un outil d’IA de mettre à jour des workflows, des paramètres, des domaines, l’authentification ou des membres.

Session

  • list_deployments: Liste les projets auxquels votre connexion peut accéder, en renvoyant chaque {subdomain, name}. Appelez ceci pour découvrir quel subdomain transmettre à checkout.
  • checkout: Lie une session à une branche pour un subdomain de projet donné, ou change quelle session de projet est active. Passez la branche de déploiement comme branch pour la modifier directement.
  • list_branches: Liste les branches Git disponibles pour le dépôt d’un projet, avec un filtrage query optionnel. Renvoie les noms de branches, le nombre total et la branche de déploiement. Appelez ceci avant checkout pour vous rattacher à une branche existante par son nom.
  • get_session_state: Inspecte la branche en cours, les fichiers modifiés et le diff de navigation en attente. Sur la branche de déploiement, liste uniquement vos modifications.
  • diff: Liste toutes les modifications entre la session et votre branche de déploiement. Chaque fichier modifié et chaque entrée docs.json incluent authors et byYou. authors liste les membres dont l’entrée contient les modifications non publiées. byYou vaut true lorsque l’entrée inclut vos propres modifications. Utilisez byYou pour distinguer vos modifications de celles d’un collègue sur une branche partagée.
  • save: Ouvre une pull request ou pousse un commit sur la branche de session. Mintlify fusionne automatiquement la PR lorsque le projet est configuré pour pousser les modifications de l’agent vers main et que la branche de déploiement n’est pas protégée. Sur la branche de déploiement, commite directement uniquement vos modifications en attente.
  • discard_session: Abandonne la session et ses modifications en cours. Sur la branche de déploiement, annule uniquement vos modifications en attente.

Exemples de prompts

Une fois l’Admin MCP connecté, vous pouvez le piloter avec des prompts en langage naturel. Par exemple :
  • “Extrais une branche appelée add-billing-faq et crée une nouvelle page sous le groupe FAQ intitulée ‘Billing’. Rédige des réponses aux cinq questions de ce ticket Linear.”
  • “Trouve toutes les pages qui mentionnent le champ déprécié legacy_token et mets à jour l’exemple pour utiliser api_key à la place. Enregistre comme une PR intitulée ‘docs: replace legacy_token references’.”
  • “Réorganise la référence d’API : déplace les pages webhooks dans un nouveau groupe appelé ‘Webhooks’ et mets à jour les icônes pour qu’elles correspondent au reste de la section.”

Bonnes pratiques

checkout renvoie une editorUrl pour la branche. create_node et save renvoient une editorUrl pour la page modifiée. Ouvrez ces liens dans un onglet séparé pour pouvoir voir les modifications de l’IA s’afficher en direct dans l’éditeur du tableau de bord pendant que vous rédigez vos prompts.
L’Admin MCP est suffisamment puissant pour réécrire des centaines de pages en une seule session. Avant de fusionner, lisez le diff de la PR et parcourez l’aperçu rendu. Ne validez pas des changements importants sans les examiner.
Passez un slug à checkout (par exemple, add-quickstart) pour que la branche générée automatiquement soit lisible. Sans cela, le nom de la branche dérive du jeton de session et est difficile à reconnaître dans votre dépôt.
Limitez chaque session à un seul changement. Des sessions plus petites produisent des pull requests plus faciles à examiner et préservent les fenêtres de contexte des agents. Utilisez discard_session puis checkout à nouveau pour passer à un travail sans lien.
Les sessions conservent une branche en mémoire côté Mintlify. Si vous abandonnez une session sans l’enregistrer ou la supprimer, la branche persiste jusqu’à ce que votre prochain checkout l’écrase. Évitez de laisser des branches admin-mcp/* obsolètes dans votre dépôt. Nettoyez-les périodiquement.

Se déconnecter ou révoquer l’accès

Déconnectez l’Admin MCP lorsque vous ne souhaitez plus qu’un outil d’IA modifie votre projet, ou lorsque vous souhaitez forcer une nouvelle connexion OAuth.
  • Révoquer l’autorisation OAuth : Dans votre tableau de bord Mintlify, accédez à Settings → Security & access → Connected apps et révoquez l’entrée pour l’outil d’IA que vous avez connecté. La révocation invalide le jeton d’accès de l’outil dans un délai de 30 secondes. Ensuite, les appels d’outils échouent et l’outil doit compléter une nouvelle connexion OAuth lors du prochain appel.
  • Supprimer le connecteur dans le client :
    • Claude : Settings → Connectors, puis supprimez l’entrée Admin MCP.
    • Claude Code : claude mcp remove mintlify.
    • ChatGPT : Settings → Connectors, puis supprimez l’entrée Mintlify.
    • Cursor : supprimez l’entrée mintlify de mcp.json et rechargez.
    • Codex : supprimez le bloc [mcp_servers.mintlify] de ~/.codex/config.toml.
La révocation de l’autorisation OAuth n’affecte pas les pull requests que le MCP a déjà ouvertes. Fermez ou annulez ces PR dans votre fournisseur Git si vous souhaitez annuler les modifications en attente.