Passer au contenu principal

​
À propos des serveurs MCP

Le Model Context Protocol (MCP) est un protocole ouvert qui établit des connexions standardisées 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 d’IA plus large, où tout client MCP (comme Claude, Cursor, Goose et autres) 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 une documentation publique. La documentation protégée par l’authentification des utilisateurs finaux 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 au 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 depuis votre tableau de bord. 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.

​
Configuration de votre serveur MCP

Tous les serveurs MCP incluent l’outil search par défaut, qui permet aux utilisateurs d’interroger des informations issues de votre documentation depuis d’autres outils. Si vous disposez d’un forfait Pro ou Enterprise, vous pouvez exposer des endpoints de votre spécification OpenAPI en tant qu’outils MCP. Pour exposer des endpoints en tant qu’outils MCP, utilisez l’objet mcp dans l’extension x-mint, au niveau du fichier ou de l’endpoint. Par exemple, le serveur MCP de Mintlify inclut des outils pour créer des conversations avec l’Assistant, obtenir des mises à jour d’état et déclencher des mises à jour. Les serveurs MCP adoptent une approche « security-first » où les endpoints d’API ne sont pas exposés par défaut. Vous devez activer explicitement les endpoints pour les rendre disponibles en tant qu’outils MCP. N’exposez que les endpoints sûrs pour un accès public via des outils d’IA.
​
mcp
object
La configuration MCP de l’endpoint.

​
Configuration au niveau du fichier

Activez MCP par défaut pour tous les endpoints dans un fichier de spécification OpenAPI, puis excluez certains endpoints 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 de terminaison
          }
        },
        // ...
      }
    }
  }
}

​
Configuration au niveau des endpoints

Activer MCP pour des endpoints spécifiques : 
{
  "paths": {
    "/api/v1/users": {
      "get": {
        "x-mint": {
          "mcp": {
            "enabled": true,
            "name": "get-users",
            "description": "Récupérer la liste des utilisateurs"
          },
          // ...
        }
      }
    },
    "/api/v1/delete": {
      "delete": {
        // Pas de `x-mint: mcp`, donc cet endpoint 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. Rendre publique l’URL de votre serveur MCP.
  2. Les utilisateurs copient l’URL de votre serveur MCP et l’ajoutent à leurs outils.
  3. Les utilisateurs accèdent à votre documentation et à vos endpoints API via leurs outils.
Voici quelques façons d’aider vos utilisateurs à se connecter à votre serveur MCP :

​
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 verrez comment aider vos utilisateurs à se connecter à votre serveur MCP.

​
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. Toutes les clés sont gérées directement par l’outil et ne sont ni stockées ni traitées par Mintlify. Si un utilisateur demande à son outil d’IA d’appeler un point de terminaison protégé, l’outil lui demandera alors les informations d’identification nécessaires à l’authentification.

​
Surveiller votre serveur MCP

Vous pouvez consulter tous les outils MCP disponibles dans la section Available tools de la page MCP Server de votre tableau de bord.
Tableau de bord MCP avec la section Available tools mise en évidence

​
Dépannage

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 points de terminaison spécifiques à l’aide de 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 uniquement l’outil de recherche afin de préserver la fonctionnalité.
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 points de terminaison activés fonctionnent avec les méthodes d’authentification spécifiées.
Si les outils d’IA n’utilisent pas efficacement vos points de terminaison d’API :
  1. Ajoutez des champs summary et description détaillés à vos points de terminaison.
  2. Assurez-vous que les noms et descriptions des paramètres sont explicites.
  3. Utilisez le tableau de bord MCP pour vérifier comment vos points de terminaison apparaissent en tant qu’outils.