Serveur Admin Model Context Protocol (MCP)

Donnez à Claude, Cursor et autres outils d’IA un accès en écriture à votre contenu et tableau de bord Mintlify pour modifier pages, réglages et PRs.

​

À 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 ou Cursor au serveur Admin MCP pour collaborer sur votre contenu et vos paramètres Mintlify avec les mêmes outils que vous utilisez pour écrire du code. Lorsque vous utilisez le serveur Admin MCP, toutes les modifications se produisent sur une branche et nécessitent une pull request pour être fusionnées. Si votre organisation dispose de plusieurs déploiements, une seule connexion Admin MCP peut accéder à tous ces déploiements 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 collègue avec un accès en écriture. Connectez-le uniquement depuis des outils d’IA de confiance et examinez chaque pull request avant de la fusionner.

L’Admin MCP est un service Mintlify hébergé à l’adresse https://mcp.mintlify.com. Il n’existe pas de version auto-hébergée — chaque client se connecte au même endpoint et s’authentifie avec votre compte Mintlify.

​

En quoi l’Admin MCP diffère du Search MCP

	Admin MCP	Search MCP
Audience	Votre équipe	Vos utilisateurs finaux
Accès	Lire, modifier, restructurer, enregistrer, créer des workflows, gérer les paramètres	Lire et rechercher dans les pages publiées
Endpoints	Hébergé par Mintlify, à la portée de votre projet	/mcp sur le domaine de votre site
Résultat	Modifications de contenu, changements de navigation, pull requests, exécutions de workflows	Résultats de recherche et contenu des pages

​

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 : L’application GitHub Mintlify ou la connexion GitLab 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, 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 déploiements, selon la manière dont vous accordez l’accès. Une connexion limitée à des déploiements spécifiques ne peut faire de checkout que sur ceux-ci, tandis qu’une connexion à l’échelle de l’organisation peut faire de checkout n’importe quel déploiement de votre organisation.

Claude

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.

Claude Code

Ajoutez le serveur Admin MCP avec la CLI Claude Code :

claude mcp add --transport http mintlify https://mcp.mintlify.com

Lors de la première utilisation, Claude Code ouvre une fenêtre de navigateur pour terminer la connexion OAuth. Après authentification, la session est réutilisée pour les appels suivants.

Cursor

1. Ouvrez la palette de commandes avec Command + Shift + P (Ctrl + Shift + P sous Windows).
2. Recherchez Open MCP settings et cliquez sur Add custom MCP.
3. Dans mcp.json, ajoutez l’Admin MCP :

{
  "mcpServers": {
    "mintlify": {
      "url": "https://mcp.mintlify.com"
    }
  }
}

4. Rechargez Cursor et terminez la connexion OAuth lorsque vous y êtes invité.

Codex

Ajoutez le serveur Admin MCP à la configuration de votre CLI Codex dans ~/.codex/config.toml :

[mcp_servers.mintlify]
url = "https://mcp.mintlify.com"

Lors de la première utilisation, Codex ouvre une fenêtre de navigateur pour finaliser la connexion OAuth. Une fois authentifié, la session est réutilisée pour les appels suivants.

Consultez la documentation Codex MCP pour plus de détails.

​

Comment fonctionne une session

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

1. Découvrir les déploiements (facultatif)

   Si votre connexion a accès à plusieurs déploiements, 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 déploiement.

2. Extraire une branche

   Le premier appel requis est checkout {subdomain}. Il crée une nouvelle branche mintlify-mcp/<slug>-<sha> à partir de la branche de déploiement de ce déploiement (ou se rattache à une branche existante que vous nommez) et renvoie une editorUrl que vous pouvez ouvrir pour suivre l’évolution dans l’éditeur du tableau de bord.

   Appelez list_branches avant checkout si vous avez besoin de découvrir ou de filtrer les branches existantes du dépôt d’un déploiement.

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 main. Ouvrez l’editorUrl dans votre tableau de bord pour voir les mêmes changements rendus.

5. Enregistrer

   Appelez save pour pousser la branche vers Git. Utilisez mode: "pr" (par défaut) pour ouvrir une pull request, ou mode: "commit" pour pousser directement sur une branche de PR existante.

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 déploiements, chaque déploiement 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.

​

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.
• 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.
• write_page — Réécrit le contenu MDX complet d’une page.

​

Navigation

• 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 sont paginés via un cursor opaque.
• create_node — Ajoute une nouvelle page, un groupe, un onglet, une ancre, une version, une langue, un produit ou une liste déroulante.
• 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).
• move_node — Déplace un nœud, y compris renommer le chemin d’une page.
• delete_node — Supprime un nœud de la navigation.

​

Configuration

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

​

Session

• list_deployments — Liste les déploiements 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 déploiement donné, ou change quelle session de déploiement est active.
• list_branches — Liste les branches Git disponibles pour le projet d’un déploiement, 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.
• diff — Liste toutes les modifications entre la session et main.
• save — Ouvre une pull request ou pousse un commit sur la branche de session.
• discard_session — Abandonne la session et ses modifications en cours.

​

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

Ouvrir l'URL de l'éditeur

Chaque checkout renvoie une editorUrl. Ouvrez-la 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

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

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

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 mintlify-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 immédiatement tout jeton de session actif, donc les appels d’outils en cours é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.
  • 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.