Model Context Protocol

Permettez aux utilisateurs d’accéder à votre documentation et à vos API depuis leurs outils d’IA préférés

​

À propos des serveurs MCP

Le Model Context Protocol (MCP) est un protocole ouvert qui standardise les connexions entre les applications d’IA et des services externes, comme la documentation. Mintlify génère un serveur MCP à partir de votre documentation et de vos spécifications OpenAPI, afin de préparer votre contenu pour l’écosystème plus large de l’IA, où n’importe quel client MCP (comme Claude, Cursor, Goose, etc.) peut se connecter à votre documentation et à vos API.

Votre serveur MCP expose des outils permettant aux applications d’IA de rechercher dans votre documentation et d’interagir avec vos API.

​

Accéder à votre serveur MCP

Les serveurs MCP ne peuvent être générés que pour de la documentation publique. La documentation protégée par une authentification utilisateur final n’est pas accessible pour la génération de serveur.

Mintlify génère automatiquement un serveur MCP pour votre documentation et l’héberge à l’URL de votre documentation avec le chemin /mcp. Par exemple, le serveur MCP de Mintlify est disponible à l’adresse https://mintlify.com/docs/mcp.

Vous pouvez afficher et copier l’URL de votre serveur MCP dans votre Dashboard.

Le chemin /mcp est réservé aux serveurs MCP hébergés et ne peut pas être utilisé pour d’autres éléments de navigation.

​

Configurer votre serveur MCP

Tous les serveurs MCP incluent par défaut l’outil search, qui permet aux utilisateurs d’interroger les informations de votre documentation depuis d’autres outils.

Si vous avez un forfait Pro ou Enterprise, vous pouvez exposer des points de terminaison de votre spécification OpenAPI en tant qu’outils MCP.

Pour exposer des points de terminaison en tant qu’outils MCP, utilisez l’objet mcp dans l’extension x-mint, au niveau du fichier ou du point de terminaison. Par exemple, le serveur MCP de Mintlify inclut des outils pour créer des conversations avec l’Assistant, obtenir des mises à jour de statut et déclencher des mises à jour.

Les serveurs MCP adoptent une approche axée sur la sécurité où les points de terminaison d’API ne sont pas exposés par défaut. Vous devez activer explicitement les points de terminaison pour les rendre disponibles en tant qu’outils MCP. N’exposez que les points de terminaison sûrs pour un accès public via des outils d’IA.

mcp · object

La configuration MCP pour le point de terminaison.

Afficher MCP

enabled · boolean

Indique s’il faut exposer le point de terminaison en tant qu’outil MCP. Cette option prévaut sur la configuration au niveau du fichier.

name · string

Le nom de l’outil MCP.

description · string

La description de l’outil MCP.

​

Configuration au niveau du fichier

Activez MCP pour tous les points de terminaison par défaut dans un fichier de spécification OpenAPI, puis excluez-en certains de manière sélective :

{
  "openapi": "3.1.0",
  "x-mint": {
    "mcp": {
      "enabled": true
    }
  },
  // ...
  "paths": {
    "/api/v1/users": {
      "get": {
        "x-mint": {
          "mcp": {
            "enabled": false // Désactive MCP pour ce point d'accès
          }
        },
        // ...
      }
    }
  }
}

​

Configuration au niveau des endpoints

Activer le Model Context Protocol (MCP) pour des endpoints spécifiques :

{
  "paths": {
    "/api/v1/users": {
      "get": {
        "x-mint": {
          "mcp": {
            "enabled": true,
            "name": "get-users",
            "description": "Obtenir une liste d'utilisateurs"
          },
          // ...
        }
      }
    },
    "/api/v1/delete": {
      "delete": {
        // Pas de `x-mint: mcp` donc ce point de terminaison n'est pas exposé comme outil MCP
        // ...
      }
    }
  }
}

​

Utiliser votre serveur MCP

Vos utilisateurs doivent connecter votre serveur MCP à leurs outils d’IA préférés.

1. Rendez l’URL de votre serveur MCP publique.
2. Les utilisateurs copient l’URL de votre serveur MCP et l’ajoutent à leurs outils.
3. Les utilisateurs accèdent à votre documentation et à vos points de terminaison d’API depuis leurs outils.

Voici quelques façons d’aider vos utilisateurs à se connecter à votre serveur MCP :

Menu contextuel

Ajoutez des options dans le menu contextuel pour permettre à vos utilisateurs de se connecter à votre serveur MCP depuis n’importe quelle page de votre documentation.

Option	Identifiant	Description
Copier l’URL du serveur MCP	mcp	Copie l’URL de votre serveur MCP dans le presse‑papiers de l’utilisateur.
Se connecter à Cursor	cursor	Installe votre serveur MCP dans Cursor.
Se connecter à VS Code	vscode	Installe votre serveur MCP dans VS Code.

Claude

1. Obtenez l’URL de votre serveur MCP.

   Accédez à votre Dashboard et trouvez l’URL de votre serveur MCP.

2. Publiez l’URL de votre serveur MCP pour vos utilisateurs.

   Créez un guide pour vos utilisateurs qui inclut l’URL de votre serveur MCP et les étapes pour le connecter à Claude.

   1. Accédez à la page Connectors dans les paramètres de Claude.
   2. Sélectionnez Add custom connector.
   3. Ajoutez le nom et l’URL de votre serveur MCP.
   4. Sélectionnez Add.
   5. Lors de l’utilisation de Claude, sélectionnez le bouton des pièces jointes (l’icône « plus »).
   6. Sélectionnez votre serveur MCP.

Voir la documentation Model Context Protocol pour plus de détails.

Claude Code

1. Obtenez l’URL de votre serveur MCP.

   Accédez à votre Dashboard et trouvez l’URL de votre serveur MCP.

2. Publiez l’URL de votre serveur MCP pour vos utilisateurs.

   Créez un guide pour vos utilisateurs qui inclut l’URL de votre serveur MCP et la commande pour le connecter à Claude Code.

   claude mcp add --transport http <name> <url>
   

Voir la documentation Claude Code pour plus de détails.

Cursor

1. Obtenez l’URL de votre serveur MCP.

   Accédez à votre Dashboard et trouvez l’URL de votre serveur MCP.

2. Publiez l’URL de votre serveur MCP pour vos utilisateurs.

   Créez un guide pour vos utilisateurs qui inclut l’URL de votre serveur MCP et les étapes pour le connecter à Cursor.

   1. Utilisez Command + Shift + P (Ctrl + Shift + P sous Windows) pour ouvrir la palette de commandes.
   2. Recherchez « Open MCP settings ».
   3. Sélectionnez Add custom MCP. Cela ouvrira le fichier mcp.json.
   4. Dans mcp.json, configurez votre serveur :

   {
     "mcpServers": {
       "<your-mcp-server-name>": {
         "url": "<your-mcp-server-url>"
       }
     }
   }
   

Voir la documentation Cursor pour plus de détails.

VS Code

1. Obtenez l’URL de votre serveur MCP.

   Accédez à votre Dashboard et trouvez l’URL de votre serveur MCP.

2. Publiez l’URL de votre serveur MCP pour vos utilisateurs.

   Créez un guide pour vos utilisateurs qui inclut l’URL de votre serveur MCP et les étapes pour le connecter à VS Code.

   1. Créez un fichier .vscode/mcp.json.
   2. Dans mcp.json, configurez votre serveur :

   {
     "servers": {
       "<your-mcp-server-name>": {
         "type": "http",
         "url": "<your-mcp-server-url>"
       }
     }
   }
   

Voir la documentation VS Code pour plus de détails.

​

Exemple : connexion au serveur MCP de Mintlify

Connectez-vous au serveur MCP de Mintlify pour interagir avec l’API Mintlify et rechercher dans notre documentation. Vous obtiendrez ainsi des réponses plus précises sur l’utilisation de Mintlify dans votre environnement local, et vous verrez comment aider vos utilisateurs à se connecter à votre serveur MCP.

Menu contextuel

En haut de cette page, ouvrez le menu contextuel et choisissez Connect to Cursor ou Connect to VS Code pour connecter le serveur MCP de Mintlify à l’IDE de votre choix.

Claude

Pour utiliser le serveur MCP de Mintlify avec Claude :

1. Ajouter le serveur MCP de Mintlify à Claude

   1. Accédez à la page Connectors dans les paramètres de Claude.
   2. Sélectionnez Add custom connector.
   3. Ajoutez le serveur MCP de Mintlify :

   • Name: Mintlify
   • URL: https://mintlify.com/docs/mcp

   4. Sélectionnez Add.
2. Accéder au serveur MCP dans votre chat

   1. Dans Claude, cliquez sur le bouton des pièces jointes (l’icône “plus”).
   2. Sélectionnez le serveur MCP de Mintlify.
   3. Posez à Claude une question sur Mintlify.

Consultez la documentation Model Context Protocol pour plus de détails.

Claude Code

Pour utiliser le serveur MCP de Mintlify avec Claude Code, exécutez la commande suivante :

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

Testez la connexion en exécutant :

claude mcp list

Consultez la documentation Claude Code pour plus de détails.

CursorInstaller dans Cursor

Pour connecter le serveur MCP de Mintlify à Cursor, cliquez sur le bouton Installer dans Cursor. Ou, pour le connecter manuellement, suivez ces étapes :

1. Ouvrir les paramètres MCP

   1. Utilisez Command + Shift + P (Ctrl + Shift + P sous Windows) pour ouvrir la palette de commandes.
   2. Recherchez « Open MCP settings ».
   3. Sélectionnez Add custom MCP. Cela ouvrira le fichier mcp.json.
2. Configurer le serveur MCP de Mintlify

   Dans mcp.json, ajoutez :

   {
     "mcpServers": {
       "Mintlify": {
         "url": "https://mintlify.com/docs/mcp"
       }
     }
   }
   
3. Tester la connexion

   Dans le chat de Cursor, demandez « What tools do you have available? ». Cursor doit afficher le serveur MCP de Mintlify comme outil disponible.

Voir Installing MCP servers dans la documentation de Cursor pour plus de détails.

VS CodeInstaller dans VS Code

Pour connecter le serveur MCP de Mintlify à VS Code, cliquez sur le bouton Installer dans VS Code. Ou, pour le connecter manuellement, créez un fichier .vscode/mcp.json et ajoutez :

{
  "servers": {
    "Mintlify": {
      "type": "http",
      "url": "https://mintlify.com/docs/mcp"
    }
  }
}

Consultez la documentation VS Code pour plus de détails.

​

Authentification

Lorsque vous activez un point de terminaison d’API pour le MCP, le serveur inclut les exigences d’authentification définies dans vos securitySchemes et securityRequirement OpenAPI. Toute key est gérée directement par l’outil et n’est ni stockée ni traitée par Mintlify.

Si un utilisateur demande à son outil d’IA d’appeler un point de terminaison protégé, l’outil lui demandera alors les identifiants d’authentification nécessaires.

​

Surveiller votre serveur MCP

Vous pouvez consulter tous les outils MCP disponibles dans la section Outils disponibles de la page Serveur MCP de votre Dashboard.

​

Dépannage

Le serveur MCP n’affiche que l’outil de recherche

Si votre serveur MCP n’expose que l’outil de recherche malgré la présence d’une spécification OpenAPI :

1. Vérifiez que votre spécification OpenAPI est valide et accessible.
2. Assurez-vous d’avoir explicitement activé MCP pour des endpoints spécifiques avec x-mint.mcp.enabled: true.
3. Consultez vos journaux de déploiement pour détecter d’éventuelles erreurs de traitement OpenAPI.

Si le traitement OpenAPI échoue, le serveur continue avec l’outil de recherche uniquement afin de maintenir la fonctionnalité.

Problèmes d’authentification

Si des utilisateurs signalent des problèmes d’authentification :

1. Vérifiez que votre spécification OpenAPI inclut des définitions securitySchemes appropriées.
2. Confirmez que les endpoints activés fonctionnent avec les méthodes d’authentification spécifiées.

Descriptions d’outils manquantes ou peu claires

Si les outils d’IA n’exploitent pas efficacement vos endpoints d’API :

1. Ajoutez des champs summary et description détaillés à vos endpoints.
2. Assurez-vous que les noms et descriptions des paramètres sont explicites.
3. Utilisez le Dashboard MCP pour vérifier l’apparence de vos endpoints en tant qu’outils.