Qu’est-ce que MCP ? Comment le Model Context Protocol relie les AI Agent, Tools, API et JSON Schema ?

Symptôme : votre AI Agent affiche plusieurs outils, mais vous ne savez pas qui les découvre, qui valide les paramètres ni qui exécute réellement l’action.

Solution la plus rapide : utilisez le MCP Model Context Protocol comme couche de liaison entre votre application d’IA et des outils contrôlés ; commencez en STDIO pour un usage local, puis passez à Streamable HTTP lorsque plusieurs utilisateurs ou services doivent partager le même MCP Server.

À qui s’adresse ce guide ?

Ce guide s’adresse aux développeurs qui construisent un MCP Server et doivent exposer correctement des outils, des ressources et des schémas.

Il concerne également les équipes plateforme qui connectent plusieurs Clients et modèles, ainsi que les équipes d’exploitation et de sécurité responsables de l’authentification, de l’audit et de la limitation des permissions.

MCP ne remplace ni le modèle ni votre API

Le MCP Model Context Protocol est un protocole ouvert qui relie une application d’IA à des outils, des ressources et des modèles de prompts. Il ne s’agit pas d’un modèle de langage, et il ne remplace pas votre API métier ni les mécanismes de Function Calling utilisés par certains modèles.

La séparation des rôles doit rester claire :

• le Host est l’application principale qui gère l’interface, le modèle, le consentement et le cycle de vie ;
• le Client MCP est une connexion isolée créée par le Host pour dialoguer avec un Server précis ;
• le MCP Server publie des outils, des ressources ou des prompts ;
• l’API sous-jacente exécute l’opération métier réelle ;
• le modèle interprète la demande, choisit éventuellement un outil et propose des arguments, mais ne doit pas être considéré comme le propriétaire du réseau ou des secrets.

Un même Host peut gérer plusieurs Clients, tandis qu’un Client dialogue normalement avec un Server donné. Cette isolation évite de mélanger les capacités, les permissions et les journaux de plusieurs intégrations. La description officielle de l’architecture MCP détaille cette relation entre Host, Client et Server.

Cette organisation évite trois erreurs fréquentes :

1. exposer directement une API sensible au modèle ;
2. placer des identifiants dans le prompt ou dans le JSON Schema ;
3. croire que la présence d’un outil dans la liste signifie qu’il sera automatiquement autorisé.

Un MCP Server correctement conçu ne donne donc pas « accès à tout le système ». Il publie une interface limitée, documentée et contrôlable.

Le cycle de connexion commence avec le Host

Pensez à MCP comme à une connexion qui traverse plusieurs étapes. Le modèle participe à cette chaîne, mais il ne doit pas être confondu avec le protocole ni avec le service chargé de réaliser l’opération.

Utilisateur
   │
   ▼
Host : interface, modèle, sécurité, cycle de vie
   │
   ▼
Client MCP : connexion isolée vers un Server
   │  initialize / capacités / tools/list
   ▼
MCP Server : validation, permissions, logique métier
   │
   ▼
API, base de données, outil système ou automatisation
   │
   └── résultat structuré ──► Server ──► Client ──► Host ──► modèle

1. Le Host crée le Client

L’utilisateur formule une demande dans l’application d’IA. Le Host décide quels MCP Server peuvent être utilisés, crée un Client pour chacun d’eux et conserve la maîtrise du cycle de vie.

Le Host peut aussi agréger les outils disponibles, filtrer certaines descriptions et demander une confirmation avant une opération d’écriture. Cette responsabilité est importante lorsque la même application connecte un outil de lecture de données, un outil de déploiement et un outil capable de supprimer une ressource.

2. Le Client et le Server négocient leurs capacités

La connexion commence par une requête initialize. Le Client annonce notamment une version de protocole et ses capacités. Le Server répond avec sa propre version et ses capacités, puis le Client envoie une notification initialized.

MCP encode ses messages avec JSON-RPC 2.0. Vous devez donc distinguer :

• les requêtes qui attendent une réponse ;
• les résultats qui signalent une exécution réussie ;
• les erreurs qui portent un code et un message ;
• les notifications qui ne demandent pas de réponse.

Cette distinction facilite le diagnostic. Une erreur de validation d’arguments ne doit pas être traitée comme une coupure de transport ou comme une indisponibilité de l’API métier.

3. Le Client découvre les capacités

Après l’initialisation, le Client peut demander la liste des outils avec tools/list. Le Server renvoie pour chaque outil un nom, une description, un inputSchema et, lorsque cela est prévu, un outputSchema.

La découverte ne signifie pas que le modèle comprend automatiquement votre métier. Une description comme « traiter une commande » laisse trop de place aux mauvaises sélections. Préférez une formulation qui précise :

• l’action exacte ;
• les conditions d’utilisation ;
• les effets de bord ;
• les unités attendues ;
• les erreurs fréquentes ;
• les situations dans lesquelles l’outil ne doit pas être appelé.

Les annotations telles que readOnlyHint, destructiveHint ou idempotentHint peuvent aider le Client, mais elles ne remplacent pas votre propre politique de confiance. Le contrat officiel des outils MCP décrit la structure attendue et les mécanismes associés.

Pourquoi JSON Schema est-il le contrat des outils ?

Le rôle de JSON Schema n’est pas de décider quel outil choisir. Il décrit la forme des données nécessaires pour l’appeler et, éventuellement, la forme des données retournées.

Un outil qui consulte les métriques d’un service pourrait publier un schéma d’entrée comme celui-ci :

{
  "type": "object",
  "properties": {
    "service": {
      "type": "string",
      "description": "Nom exact du service à consulter"
    },
    "period": {
      "type": "string",
      "enum": ["hour", "day", "week"]
    }
  },
  "required": ["service", "period"],
  "additionalProperties": false
}

Le Client peut utiliser ce contrat pour détecter un champ manquant avant l’appel. Le Server doit toutefois refaire la validation côté exécution : un Client ancien, défaillant ou malveillant ne doit jamais être considéré comme une barrière suffisante.

L’inputSchema décrit les arguments. L’outputSchema, lorsqu’il est fourni, décrit le résultat structuré transmis dans structuredContent. Cela facilite l’affichage, l’automatisation et le chaînage avec un autre outil.

Ce que le schéma ne garantit pas

Même un schéma précis ne garantit pas :

• que la valeur demandée existe réellement dans l’API ;
• que l’utilisateur possède le droit d’effectuer l’action ;
• que l’opération est sans danger ;
• que la réponse sera disponible avant le délai limite ;
• que le modèle choisira le bon outil parmi plusieurs descriptions proches.

Vous devez donc traiter séparément la validation de forme, la validation métier et l’autorisation.

Le schéma doit également rester raisonnablement lisible. Des propriétés trop génériques, des descriptions contradictoires ou des dizaines de paramètres optionnels peuvent dégrader la sélection par l’AI Agent. Lorsque deux outils se ressemblent, donnez-leur des noms distincts et expliquez clairement leurs limites.

L’API reste derrière le Server

Le MCP Server doit encapsuler la complexité de l’API. Il peut convertir une demande simple en plusieurs appels internes, normaliser les erreurs et masquer les champs qui ne doivent pas être transmis au modèle.

Par exemple, un outil verifier_rendu_video peut recevoir un identifiant de projet et une période, puis interroger plusieurs services internes. Le modèle n’a pas besoin de connaître les URL, les en-têtes d’authentification ni la structure complète de la base de données. Il reçoit uniquement le résultat utile : état du rendu, date de dernière vérification et lien de prévisualisation autorisé.

Cette abstraction est particulièrement pertinente pour l’audio, la vidéo et le design. Un outil peut vérifier les métadonnées d’un fichier, un autre lancer un rendu, et un troisième publier une version validée. Le fait de séparer ces actions réduit le risque qu’une demande de lecture déclenche involontairement une opération d’écriture.

Qui exécute réellement l’outil ?

Le chemin d’exécution doit rester explicite :

1. le modèle analyse la demande et sélectionne un outil ;
2. le Host ou le Client prépare l’appel ;
3. le Client envoie tools/call au Server ;
4. le Server vérifie l’identité, les permissions et les arguments ;
5. le Server appelle l’API ou le programme local ;
6. le Server transforme la réponse en résultat MCP ;
7. le Client remet le résultat au Host ;
8. le modèle décide s’il doit répondre, demander une précision ou effectuer une autre étape.

Le modèle propose donc une intention d’appel ; le Server exécute l’action réelle. Cette séparation permet d’appliquer une politique avant l’appel et de conserver les secrets dans l’environnement d’exécution.

Erreurs, délais et annulation

Vous devez prévoir au minimum les situations suivantes :

• paramètre invalide ou champ obligatoire absent ;
• ressource métier inexistante ;
• authentification expirée ;
• API indisponible ;
• délai dépassé ;
• opération annulée par l’utilisateur ;
• résultat partiel ou non conforme à l’outputSchema.

Une erreur doit être retournée de manière exploitable, et non sous la forme d’un long texte ambigu. Le Client doit pouvoir distinguer une erreur JSON-RPC, une erreur métier et une erreur de transport.

Ajoutez aussi des limites opérationnelles :

• délai maximum par outil ;
• nombre maximal de tentatives ;
• budget d’appels par session ;
• protection contre les appels récursifs ;
• identifiant de corrélation pour les journaux ;
• comportement défini en cas de réponse partielle.

L’idempotence est essentielle. Une lecture peut souvent être répétée sans conséquence. En revanche, « créer une facture », « publier un fichier audio » ou « lancer une commande de production » doit posséder une clé d’idempotence ou un mécanisme de vérification avant une nouvelle tentative. Sinon, une reprise après timeout peut déclencher deux opérations.

Cas concret : une équipe audio-vidéo

Imaginez un outil qui reçoit un identifiant de projet, vérifie l’état d’un rendu vidéo et renvoie une URL de prévisualisation. Le modèle peut choisir cet outil lorsque l’utilisateur demande de vérifier si le montage est prêt. Il ne devrait pas recevoir la clé d’accès au stockage ni appeler directement le service de rendu.

Le Server valide l’identifiant, interroge l’API de production, normalise l’état en quelques valeurs documentées et retourne un objet structuré. Si l’état est processing, le Host peut informer l’utilisateur sans relancer indéfiniment la même requête.

Si l’utilisateur demande ensuite une publication, cette action doit être exposée comme un outil distinct, avec confirmation et permission d’écriture. La distinction entre consulter, modifier et publier est plus importante que le simple nombre d’outils disponibles.

Le passage du local au distant impose une nouvelle architecture

En local, le transport STDIO permet au Client de lancer le Server comme sous-processus. Les messages passent par stdin et stdout, tandis que les journaux peuvent être envoyés sur stderr. Le Server ne doit rien écrire d’autre qu’un message MCP valide sur stdout.

Ce mode convient à un développeur seul, à un prototype ou à une intégration liée à une machine. Il limite toutefois le partage entre utilisateurs, complique la supervision centralisée et lie l’exécution aux dépendances installées localement.

En distant, Streamable HTTP expose un endpoint MCP indépendant. Le Server peut gérer plusieurs connexions, utiliser des requêtes HTTP POST et éventuellement fournir un flux SSE selon les capacités de l’implémentation. Les détails de transport et de cycle de vie sont documentés dans la spécification officielle des transports MCP.

Pour convertir votre Server local en service distant, suivez cette séquence :

1. Séparez la logique métier du transport. Le code qui appelle l’API ne doit pas dépendre directement de STDIO.
2. Ajoutez un transport Streamable HTTP. Utilisez un endpoint clairement défini, puis vérifiez l’initialisation et la fermeture.
3. Définissez le mode d’état. Choisissez un Server sans état pour simplifier la montée en charge, ou des sessions si votre flux exige une continuité.
4. Activez TLS et l’authentification. Appliquez le mécanisme compatible avec votre environnement.
5. Validez chaque appel côté Server. Contrôlez le jeton, son audience, les paramètres, la portée de l’action et le locataire concerné.
6. Ajoutez les contrôles opérationnels. Préparez les limites de débit, les délais, les journaux, les traces et les alertes avant l’ouverture réseau.
7. Testez avec un Client compatible. Vérifiez l’initialisation, la découverte, un appel valide, un appel invalide, une erreur d’API et une annulation.

Pour HTTP, la documentation officielle de l’autorisation MCP précise notamment la validation des jetons, l’usage de TLS et les protections nécessaires dans un environnement distant.

Ne transposez pas mécaniquement l’authentification HTTP au mode STDIO. Un Server local récupère généralement ses identifiants dans son environnement d’exécution, alors qu’un Server HTTP doit contrôler les requêtes entrantes sur une surface réseau exposée.

Les permissions doivent être conçues avant les outils

Commencez par classer chaque outil :

• lecture seule : consulter un fichier, rechercher un ticket, lire l’état d’un rendu ;
• écriture réversible : ajouter un commentaire, créer une branche, modifier un brouillon ;
• écriture sensible : publier, déployer, envoyer un message externe ;
• action destructive : supprimer, révoquer, écraser ou arrêter une ressource.

Appliquez ensuite cette logique :

• si l’outil est en lecture seule, si ses arguments sont bornés et si les données retournées ne sont pas sensibles, autorisez éventuellement l’exécution automatique ;
• si l’outil modifie un état réversible, exigez une permission liée au projet ou au compte ;
• si l’outil publie, dépense, déploie ou communique vers l’extérieur, demandez une confirmation explicite ;
• si l’outil est destructif, utilisez une liste blanche stricte, une confirmation séparée et un mécanisme de récupération ;
• si le propriétaire de la ressource n’est pas identifiable, bloquez l’appel jusqu’à validation humaine.

Les identifiants doivent rester dans le Host, le Server ou un coffre de secrets contrôlé. Ils ne doivent pas être inscrits dans la description de l’outil, le prompt, l’inputSchema, un exemple public ou un fichier de configuration partagé sans protection.

Évitez le « passthrough » aveugle. Si le Server reçoit un jeton du Client puis le transmet sans contrôle à une API tierce, vous risquez de mélanger les rôles et les audiences. Le Server doit valider le jeton reçu et utiliser, lorsque nécessaire, un identifiant distinct pour l’API en aval.

Le choix du transport dépend de votre équipe

Un Server local est généralement le meilleur point de départ pour vérifier les schémas, la sélection d’outils et les erreurs. Il ne demande pas de service réseau permanent et réduit la surface exposée.

Un Server distant devient plus pertinent lorsque :

• plusieurs développeurs doivent utiliser les mêmes outils ;
• les secrets doivent rester dans un environnement contrôlé ;
• les journaux et la supervision doivent être centralisés ;
• les API ne sont pas accessibles depuis les postes locaux ;
• l’équipe veut faire évoluer le Server sans réinstaller chaque Client.

Une architecture hybride peut être préférable. Vous pouvez garder les outils liés aux fichiers locaux en STDIO et placer les outils métier partagés derrière Streamable HTTP.

Ne forcez pas tous les MCP Server à être hébergés sur Mac. Le choix doit suivre les dépendances réelles : une API web, un service de données ou un traitement conteneurisé peut fonctionner sur une infrastructure classique. En revanche, si votre outil doit accéder en permanence à Xcode, à une signature Apple, à des simulateurs ou à une automatisation macOS, l’environnement d’exécution devient une contrainte fonctionnelle.

Dans ce cas, vérifiez la disponibilité de macOS, la conservation de la session, les droits utilisateur, les accès aux périphériques et les besoins de redémarrage. Vous pouvez consulter le guide de l’infrastructure Kvmjet pour comprendre les possibilités d’environnement distant, puis utiliser le centre d’aide Kvmjet lorsque votre équipe doit clarifier les conditions d’exploitation.

Grille de décision avant la mise en production

Situation	Transport conseillé	Contrôles indispensables	Limite principale
Prototype individuel et outil local	STDIO	environnement isolé, validation des arguments, journaux sur stderr	partage et supervision limités
Équipe partageant une API interne	Streamable HTTP	TLS, authentification, quotas, audit et tests de compatibilité	exploitation réseau nécessaire
Outil de création ou de publication	HTTP ou hybride	confirmation, idempotence, liste blanche et retour structuré	risque d’effets de bord
Automatisation dépendante de macOS	Server sur Mac dédié ou hybride	session stable, certificats, droits macOS et surveillance	dépendance à une ressource physique
Service très sollicité et sans état	Streamable HTTP sans session persistante, si le Client le permet	montée en charge, limites, corrélation et reprise côté application	compatibilité variable selon les Clients

Avant d’accepter un nouveau Client, vérifiez sa version de protocole, ses capacités réellement prises en charge et son comportement face aux schémas. Une capacité documentée dans la spécification peut rester indisponible dans une implémentation particulière.

Pour la validation interactive d’un Server, vous pouvez utiliser l’inspecteur MCP officiel afin d’exercer un Server STDIO ou Streamable HTTP. Testez ensuite les réponses et les erreurs avant d’intégrer le Server à votre plateforme.

La recette doit couvrir toute la durée de vie

Une recette sérieuse ne consiste pas seulement à vérifier que l’outil apparaît dans une interface. Elle doit couvrir :

• l’initialisation avec une version acceptée ;
• la déclaration des capacités ;
• la découverte d’un outil ;
• la validation d’un argument obligatoire ;
• le rejet d’un champ inattendu ;
• la réponse structurée conforme à l’outputSchema ;
• l’expiration d’un jeton ;
• la tentative d’accès à une ressource d’un autre utilisateur ;
• le timeout de l’API ;
• l’annulation par le Client ;
• la répétition d’un appel après interruption ;
• l’absence de secret dans les messages et les journaux.

Conservez la version de protocole, la version du Client, la version du Server et le résultat de chaque test. Lorsqu’une nouvelle version de la spécification ou un nouveau transport est adopté, rejouez cette matrice. Vous éviterez ainsi d’attribuer à MCP un comportement qui provient en réalité d’une implémentation particulière.

Si votre solution actuelle repose sur un script local lancé depuis chaque poste, elle peut convenir à une expérimentation, mais ses défauts apparaissent rapidement : versions divergentes, secrets dispersés, absence d’audit centralisé et accès difficile aux ressources macOS nécessaires à une automatisation Apple. Pour un besoin ponctuel de Server distant, de validation d’intégration ou de service qui doit rester disponible sur une machine Mac, la location Kvmjet peut offrir un environnement plus cohérent que l’achat d’un poste dédié ou l’empilement de solutions locales.

Vous pouvez examiner une option de Mac distant pour un service prolongé uniquement si votre MCP Server exige réellement Xcode, la signature ou l’automatisation macOS. Pour un service générique sans dépendance Apple, une infrastructure non-Mac reste souvent plus simple à exploiter.