Model Context Protocol (MCP)

MCP vs OpenAPI : Relier les agents IA et les API REST

Nov 2, 2026 · 1 views
api designinteroperabilityAI AgentsMCPopenapi

Le paysage de l'intégration de l'IA évolue rapidement. Bien qu'OpenAPI soit depuis longtemps la référence pour documenter les API REST, le Model Context Protocol (MCP) émerge comme le standard de facto permettant aux agents IA d'interagir avec des outils et des sources de données. Cependant, de nombreuses organisations font face à un défi : elles disposent de spécifications OpenAPI étendues mais doivent exposer ces capacités aux LLM via MCP. Cet article explore comment ces deux spécifications se comparent et comment les relier efficacement pour une interopérabilité entre protocoles.

Comprendre les différences fondamentales

En leur cœur, MCP et OpenAPI sont tous deux des définitions basées sur JSON Schema, mais leurs philosophies de conception diffèrent considérablement. OpenAPI est conçu pour une documentation d'API lisible par l'homme et des contrats de requête/réponse stricts. Il se concentre sur les méthodes HTTP, les chemins et les schémas de sécurité. MCP, en revanche, est conçu pour la communication machine à machine, spécifiquement pour que les LLM découvrent et invoquent des outils. Il abstrait les détails HTTP et se concentre sur des descriptions sémantiques qui aident les modèles à comprendre l'intention et l'utilisation.

Les principales différences incluent :

  • Couche de transport : OpenAPI implique HTTP/HTTPS. MCP est agnostique quant au transport, utilisant souvent stdio ou Streamable HTTP.
  • Granularité du schéma : OpenAPI exige un typage strict pour tous les corps de requête. MCP accepte souvent des entrées flexibles, s'appuyant sur le modèle pour analyser les arguments en langage naturel en données structurées.
  • But de la description : Les descriptions OpenAPI aident les développeurs à implémenter des clients. Les descriptions MCP aident les LLM à décider quand et comment utiliser un outil.

Comparaison des définitions d'outils

Une « opération » OpenAPI est mappée à un « outil » MCP. Examinons un exemple pratique. Supposons que nous ayons une fonction simple pour rechercher dans une base de données.

Définition OpenAPI 3.0 :


openapi: 3.0.0
info:
  title: Search API
  version: 1.0.0
paths:
  /search:
    post:
      operationId: searchItems
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: The search term
              required:
                - query
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object

Définition d'outil MCP :


{
  "name": "search_items",
  "description": "Searches the product database for items matching the provided query. Returns a list of products with name and price.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The keyword or phrase to search for in product names or descriptions."
      }
    },
    "required": ["query"]
  }
}

Remarquez comment la définition MCP inclut un champ « description » plus descriptif. C'est crucial car les LLM s'appuient sur ce texte pour comprendre l'utilité de l'outil. La spécification OpenAPI s'appuie sur l'`operationId` et la structure du chemin, qui sont moins intuitifs pour un modèle cherchant à raisonner sur les actions.

Stratégies pour l'interopérabilité

Lors de la conversion d'OpenAPI vers MCP, ou vice versa, vous ne devriez pas vous fier à une simple transformation JSON 1:1. Au lieu de cela, envisagez les stratégies suivantes :

  1. Enrichissement sémantique : Utilisez un LLM pour générer des descriptions améliorées pour les outils MCP basées sur la spécification OpenAPI. Le document original pourrait dire « Obtenir l'ID utilisateur », mais la description de l'outil MCP devrait dire « Récupère l'identifiant unique de l'utilisateur actuellement authentifié ». Ce contexte aide le modèle à utiliser correctement l'outil.
  2. Aplatir les paramètres : OpenAPI utilise souvent des objets imbriqués dans les corps de requête. MCP fonctionne mieux avec des schémas d'entrée plats et simples. Aplatissez les structures JSON imbriquées en paramètres individuels lorsque c'est possible pour réduire l'ambiguïté pour le LLM.
  3. Abstraction de la gestion des erreurs : OpenAPI définit des codes de statut HTTP. Les outils MCP retournent généralement un seul objet de résultat. Votre implémentation de serveur MCP doit capturer les erreurs HTTP de l'API OpenAPI sous-jacente et les convertir en messages d'erreur significatifs dans la réponse MCP, plutôt que d'exposer des 404 bruts au modèle.

Meilleures pratiques d'implémentation

Pour construire un pont robuste, enveloppez votre client OpenAPI à l'intérieur de votre serveur MCP. Le serveur MCP agit comme un adaptateur. Il reçoit l'appel d'outil du LLM, construit la requête HTTP définie dans la spécification OpenAPI, l'exécute et formate la réponse en un résultat compatible MCP.


// Pseudo-code pour un gestionnaire de serveur MCP
async function handleSearchTool(args) {
  // 1. Valider les arguments contre le inputSchema MCP
  if (!args.query) throw new McpError("Missing query");

  // 2. Construire la requête HTTP basée sur la logique OpenAPI
  const response = await fetch("https://api.example.com/search", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: args.query })
  });

  // 3. Gérer les erreurs
  if (!response.ok) {
    return { content: [{ type: "text", text: `Search failed: ${response.statusText}` }] };
  }

  // 4. Formater la réponse de succès pour MCP
  const data = await response.json();
  return {
    content: [{
      type: "text",
      text: `Found ${data.length} items: ${data.map(i => i.name).join(", ")}`
    }]
  };
}

Conclusion

OpenAPI et MCP ne sont pas des concurrents mais des standards complémentaires. OpenAPI définit le contrat pour le comportement de votre API, tandis que MCP définit l'interface pour la façon dont les agents IA perçoivent et interagissent avec ce comportement. En comprenant les différences de granularité du schéma et d'intention descriptive, vous pouvez construire des adaptateurs efficaces qui exposent vos API REST existantes au monde des agents IA. À mesure que l'adoption de MCP augmente, maintenir un mappage clair entre vos spécifications OpenAPI et vos définitions d'outils MCP sera essentiel pour quiconque construit des applications alimentées par l'IA à grande échelle.

Share:
Related Posts