À propos du serveur Admin MCP
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.
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
- 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_configsur 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.
saveouvre 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
- Claude
- Claude Code
- ChatGPT
- Cursor
- Codex
1
Ajouter l'Admin MCP comme connecteur personnalisé
- Accédez à la page Connectors dans les paramètres de Claude.
- Cliquez sur Add custom connector.
- Ajoutez le connecteur :
- Nom : Admin MCP
- URL :
https://mcp.mintlify.com
- 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
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.Modifier directement la 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.
savepublie uniquement vos modifications. Il ignoremodeet 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_sessionannule uniquement vos modifications. Il renvoiediscardedChangesavec le nombre de modifications annulées. Les modifications des autres et la branche elle-même restent intactes.get_session_stateliste uniquement vos modifications.
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
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.
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œudprivate-page-<uuid>obtenu depuislist_nodesavecvisibility: "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œudprivate-page-<uuid>commepath. 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œudprivate-page-<uuid>pour réécrire une page privée avec les mêmes exigences OAuth et de rôle queedit_page. Utilisezcreate_nodepour 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 lepathde destination (par exemple,images/dashboard.png), lecontentTypedu fichier et sasizeexacte en octets. Renvoie unuploadId, uneuploadUrlprésignée et lesheadersà envoyer avec le téléversement.finalize_image_upload: Enregistre l’image téléversée sur la branche de session. Transmettez l’uploadIdet le mêmepath. Renvoie lesrcà référencer dans le MDX avecedit_pageouwrite_page, ou dans les champslogooufavicondedocs.jsonavecupdate_config.
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 :
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 parparentId(utilisezrecursive: truepour inclure tous les descendants), un ou plusieurs types de nœuds, ou n’importe quel scope de division :language,version,tab,dropdown,anchor,productouitem. Les résultats se paginent via uncursoropaque. Transmettezvisibility: "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 lerolede 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. Transmettezvisibility: "private"avecdata.type: "page"oudata.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 parentprivate-folder-<uuid>existant. Pour les nouvelles pages, la réponse inclut uneeditorUrlqui 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œudprivate-page-<uuid>ouprivate-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œudprivate-page-<uuid>ouprivate-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.
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: Modifiedocs.json(thème, racines de navigation, intégrations, paramètres SEO).
Gestion de projet
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 :
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 avecrequest.report. Les résultats volumineux sont paginés avecmaxRowsetrowOffset. Pour des requêtes personnalisées, utilisezquery_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.
update_deployment_settings: Modifie un paramètre du dashboard, commenoindex,base_path,name,disable_ai_chat,search_settings,privacy,custom_scriptsou un module complémentaire. Utilisezupdate_configpour les paramètres dedocs.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.
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.
Session
list_deployments: Liste les projets auxquels votre connexion peut accéder, en renvoyant chaque{subdomain, name}. Appelez ceci pour découvrir quelsubdomaintransmettre àcheckout.checkout: Lie une session à une branche pour unsubdomainde projet donné, ou change quelle session de projet est active. Passez la branche de déploiement commebranchpour la modifier directement.list_branches: Liste les branches Git disponibles pour le dépôt d’un projet, avec un filtragequeryoptionnel. Renvoie les noms de branches, le nombre total et la branche de déploiement. Appelez ceci avantcheckoutpour 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éedocs.jsonincluentauthorsetbyYou.authorsliste les membres dont l’entrée contient les modifications non publiées.byYouvauttruelorsque l’entrée inclut vos propres modifications. UtilisezbyYoupour 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 versmainet 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
- “Extrais une branche appelée
add-billing-faqet 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_tokenet mets à jour l’exemple pour utiliserapi_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
Ouvrir l'URL de l'éditeur
Ouvrir l'URL de l'éditeur
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.Examiner chaque PR
Examiner chaque PR
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.
Utiliser des slugs pour les noms de branches
Utiliser des slugs pour les noms de branches
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.Garder les sessions ciblées
Garder les sessions ciblées
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
- 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
mintlifydemcp.jsonet rechargez. - Codex : supprimez le bloc
[mcp_servers.mintlify]de~/.codex/config.toml.