Utiliser Mintlify comme graphe de connaissances pour votre base de code

Un graphe de connaissances de base de code est un projet Mintlify qui décrit votre code : ce que fait chaque dépôt, ce qu’il expose et comment les dépôts dépendent les uns des autres. Les agents l’interrogent via MCP avant de modifier le code. Vous n’avez besoin ni de documentation existante ni de migration. La configuration se fait en trois étapes :

Générer le graphe de connaissances initial avec l’agent Mintlify ou votre propre agent de code.
Configurer des automatisations pour le maintenir à jour.
Utiliser le graphe de connaissances via MCP.

Les dépôts, pull requests et réponses présentés dans les exemples de cette page sont des données fictives.

Prérequis

Un projet Mintlify connecté à un dépôt Git. Ce dépôt central (hub) contient le graphe de connaissances et peut être vide au départ. Consultez le Quickstart.
La GitHub App Mintlify installée sur le dépôt central et sur chaque dépôt source que vous souhaitez documenter.
Un forfait Enterprise pour les automatisations personnalisées.
L’agent Mintlify, ou un agent de code tel que Claude Code, Codex ou Cursor.

Pour garder le graphe de connaissances privé, configurez l’authentification. Le serveur MCP de recherche exige alors que chaque utilisateur se connecte.

Planifier la structure

Placez tous les dépôts dans un seul projet central, afin que les agents interrogent un seul serveur MCP et que les pages puissent comporter des liens entre dépôts. Attribuez à chaque dépôt son propre groupe, ainsi qu’une section de vue d’ensemble.

docs.json

{
  "navigation": {
    "groups": [
      {
        "group": "Overview",
        "pages": ["index", "architecture", "glossary"]
      },
      {
        "group": "Web app",
        "pages": ["repos/web-app/index", "repos/web-app/local-development", "repos/web-app/routing"]
      },
      {
        "group": "API service",
        "pages": ["repos/api-service/index", "repos/api-service/endpoints", "repos/api-service/data-model"]
      },
      {
        "group": "API gateway",
        "pages": ["repos/api-gateway/index", "repos/api-gateway/auth"]
      }
    ]
  }
}

Chaque section de dépôt doit couvrir ce dont un agent a besoin avant de modifier le code : ce que fait le dépôt et qui en est responsable, les endpoints ou événements qu’il expose, ce qu’il appelle et ce qui l’appelle, ses principaux modèles de données, et comment l’exécuter et le tester. Commencez par quelques dépôts représentatifs, par exemple un frontend, un backend et un service partagé, avant d’ajouter les autres.

Étape 1 : Générer le graphe de connaissances initial

Demandez à un agent de lire votre code source et d’écrire les premières pages dans le dépôt central. Utilisez l’agent Mintlify, ou clonez les dépôts et exécutez votre propre agent de code.

Agent Mintlify
Cloner et pousser

L’agent Mintlify lit n’importe quel dépôt sur lequel la GitHub App Mintlify est installée : vous n’avez donc rien à cloner.

Connecter vos dépôts sources

Installez la GitHub App Mintlify sur chaque dépôt source que vous souhaitez documenter. Consultez Connecter des dépôts comme contexte.

Générer la documentation d'un dépôt

Ouvrez l’agent dans votre dashboard ou dans Slack et indiquez le dépôt source, le dossier cible et les pages à écrire.

Example prompt

Read the source code in the your-org/api-service repository and write
documentation for it in repos/api-service/.

Create these pages:
- index.mdx: what the service does, who owns it, and how it fits into the
  rest of the system
- endpoints.mdx: every HTTP endpoint with method, path, parameters, and
  response shape, based on the route definitions
- data-model.mdx: the main models and database tables
- local-development.mdx: how to install, run, and test the service

For each page, list the other repositories this service calls or is called
by, and link to their pages under repos/.

Only document what you can confirm from the code. If something is unclear,
leave a TODO comment instead of guessing.

Add the new pages to docs.json in a group named "API service".

L’agent ouvre une pull request dans le dépôt central. Relisez-la et corrigez ce que l’agent a mal compris.

Répéter pour chaque dépôt

Répétez l’opération pour vos autres dépôts, puis demandez à l’agent de rédiger les pages de vue d’ensemble.

Example prompt

Read every page under repos/ and write architecture.mdx. Describe how the
repositories depend on each other, which services call which, and how a
request moves through the system. Link to the repository pages for details.

Fusionner les pull requests

Une fois les pull requests fusionnées, Mintlify déploie le graphe de connaissances et l’indexe pour la recherche et MCP.

Exécutez Claude Code, Codex ou Cursor sur des clones locaux, puis poussez les pages vers le dépôt central.

Configurer votre agent de code

Clonez le dépôt central et les dépôts sources dans un même répertoire parent.

mkdir knowledge-graph && cd knowledge-graph
git clone https://github.com/your-org/docs-hub.git
git clone https://github.com/your-org/web-app.git
git clone https://github.com/your-org/api-service.git
git clone https://github.com/your-org/api-gateway.git

Depuis le dépôt central, exécutez mint agent setup pour installer la skill Mintlify et connecter le serveur MCP d’administration.

cd docs-hub
mint agent setup

Générer la documentation d'un dépôt

Lancez votre agent dans le répertoire parent et indiquez le dépôt source, le dossier cible et les pages à écrire.

Example prompt

Read the source code in ../api-service and write documentation for it in
docs-hub/repos/api-service/.

Create these pages:
- index.mdx: what the service does, who owns it, and how it fits into the
  rest of the system
- endpoints.mdx: every HTTP endpoint with method, path, parameters, and
  response shape, based on the route definitions
- data-model.mdx: the main models and database tables
- local-development.mdx: how to install, run, and test the service

For each page, list the other repositories this service calls or is called
by, and link to their pages under docs-hub/repos/.

Only document what you can confirm from the code. If something is unclear,
leave a TODO comment instead of guessing.

Add the new pages to docs-hub/docs.json in a group named "API service".

Relisez le résultat, corrigez ce que l’agent a mal compris et exécutez mint dev depuis le dépôt central pour prévisualiser les pages.

Répéter pour chaque dépôt

Répétez l’opération pour vos autres dépôts, puis demandez à l’agent de rédiger les pages de vue d’ensemble.

Example prompt

Read every page under docs-hub/repos/ and write docs-hub/architecture.mdx.
Describe how the repositories depend on each other, which services call
which, and how a request moves through the system. Link to the repository
pages for details.

Pousser vers le dépôt central

Commitez les pages, poussez-les vers le dépôt central et ouvrez une pull request. Une fois celle-ci fusionnée, Mintlify déploie le graphe de connaissances et l’indexe pour la recherche et MCP.

git checkout -b initial-knowledge-graph
git add repos architecture.mdx docs.json
git commit -m "Add initial knowledge graph"
git push -u origin initial-knowledge-graph

Enregistrez les prompts qui ont fonctionné sous forme de skill personnalisée ou de fichier AGENTS.md dans le dépôt central. Toute personne qui ajoutera un nouveau dépôt par la suite obtiendra la même structure de pages.

Étape 2 : Maintenir le graphe de connaissances à jour

Créez une automatisation personnalisée avec un déclencheur de modification de code afin que l’agent mette à jour le dépôt central chaque fois qu’une pull request est fusionnée dans un dépôt source.

Créer l'automatisation

Ouvrez vos paramètres Automations.
Cliquez sur New automation.
Sélectionnez le déclencheur Code change.
Cliquez sur Add repo pour chaque dépôt source documenté à l’étape 1. Une automatisation peut écouter jusqu’à 50 dépôts.

Filtrer le déclencheur

Dans Show advanced options sur chaque carte de dépôt, définissez Listening to changes in sur des chemins sources tels que src/**, et utilisez Excluding PRs from pour ignorer les bots. Consultez Filtrer les déclencheurs de modification de code.

Rédiger les instructions

Indiquez à l’agent comment les dépôts correspondent aux pages du dépôt central et ce qu’il doit modifier.

Example instructions

1. Read the merged pull request diff from the trigger repository.
2. Find the matching folder under /repos/ in this project. The folder name
   matches the repository name.
3. Identify changes to endpoints, events, data models, dependencies on
   other repositories, or setup steps.
4. Update the affected pages in that folder. If the change affects how
   repositories depend on each other, also update /architecture.mdx.
5. If the pull request doesn't change anything the documentation covers,
   make no changes.
6. Open a pull request that lists the pages you changed and links to the
   source pull request.

Choisir un mode de mise à jour

Commencez avec Modify and wait for review, qui ouvre une pull request et désigne les auteurs de la modification source comme relecteurs. Passez à Update and merge changes une fois les résultats fiables. Si vous utilisez la protection de branche, consultez Configurer la fusion automatique.

Tester l'automatisation

Enregistrez-la et exécutez-la manuellement, puis consultez l’historique des exécutions et affinez les instructions.

Ce simulateur utilise une automatisation qui écoute src/** dans les trois dépôts d’exemple et exclut dependabot[bot]. Pour ajouter un dépôt plus tard, générez ses pages comme à l’étape 1, puis ajoutez-le au déclencheur. Chaque exécution qui met à jour le dépôt central consomme des crédits, et les exécutions qui ne modifient rien sont gratuites. Pour les dépôts très actifs, un déclencheur planifié regroupe de nombreuses fusions en une seule exécution. Consultez Contrôler l’utilisation des crédits.

L’estimation suppose que chaque fusion modifie du code documenté : l’utilisation réelle sera donc probablement inférieure.

Étape 3 : Utiliser le graphe de connaissances via MCP

Chaque projet dispose d’un serveur MCP de recherche hébergé au chemin /mcp de l’URL de votre site. Avec l’authentification, utilisez /authed/mcp et activez d’abord le MCP authentifié.

Claude Code
Codex
Cursor

claude mcp add --transport http knowledge-graph https://docs.your-company.com/mcp

codex mcp add knowledge-graph --url https://docs.your-company.com/mcp

Ajoutez le serveur à .cursor/mcp.json dans votre projet, ou à ~/.cursor/mcp.json pour tous les projets.

.cursor/mcp.json

{
  "mcpServers": {
    "knowledge-graph": {
      "url": "https://docs.your-company.com/mcp"
    }
  }
}

Consultez Utiliser votre serveur MCP pour les autres clients. Pour que les agents le consultent sans qu’on le leur demande, ajoutez une ligne au fichier CLAUDE.md, AGENTS.md ou aux règles Cursor de chaque dépôt source.

AGENTS.md

Before changing code that calls another service or repository, search the
knowledge-graph MCP server for that service. Use its documented endpoints,
data models, and conventions instead of guessing.

Voici comment un agent utilise les outils MCP pour répondre à des questions sur votre code : Lorsqu’un agent trouve une page erronée, il peut la signaler avec l’outil de feedback. Les signalements apparaissent dans votre dashboard de feedback.

Étapes suivantes

Automatisations

Découvrez les types de déclencheurs, les modes de mise à jour et les limites d’utilisation.

Serveur MCP de recherche

Configurez l’indexation, l’authentification et les identifiants client de votre serveur MCP.

Skills

Apprenez aux agents à utiliser votre graphe de connaissances grâce aux fichiers de skills.

Authentification

Restreignez l’accès au graphe de connaissances à votre équipe.

Aperçu

IA

Documentation d'API

Bonnes pratiques

Git

Cas d'usage

Utiliser Mintlify comme graphe de connaissances pour votre base de code

Prérequis

Planifier la structure

Étape 1 : Générer le graphe de connaissances initial

Étape 2 : Maintenir le graphe de connaissances à jour

Étape 3 : Utiliser le graphe de connaissances via MCP

Étapes suivantes

Automatisations

Serveur MCP de recherche

Skills

Authentification

​Prérequis

​Planifier la structure

​Étape 1 : Générer le graphe de connaissances initial

​Étape 2 : Maintenir le graphe de connaissances à jour

​Étape 3 : Utiliser le graphe de connaissances via MCP

​Étapes suivantes

Automatisations

Serveur MCP de recherche

Skills

Authentification

Prérequis

Planifier la structure

Étape 1 : Générer le graphe de connaissances initial

Étape 2 : Maintenir le graphe de connaissances à jour

Étape 3 : Utiliser le graphe de connaissances via MCP

Étapes suivantes