Article

Connecter un agent à une API : hypermédia ou MCP ?

Un agent peut suivre les liens et les actions d’une API hypermédia. Voici comment cela fonctionne, ce que MCP apporte et les critères utiles pour choisir.

Un agent IA, c’est-à-dire un programme qui confie à un modèle de langage le choix de ses actions, doit consulter une commande, vérifier son état puis demander son annulation. Vous pouvez lui proposer un outil nommé « annuler une commande », publié par un serveur MCP, ou lui laisser découvrir cette action dans les réponses de votre API, si elle est hypermédia. Les deux voies aboutissent, et aucune ne dispense le serveur de vérifier les droits et l’état au moment d’annuler. Si vous disposez déjà d’une API hypermédia que vous maîtrisez, essayez-la avant de construire une interface supplémentaire ; quand il faut réunir les outils de plusieurs fournisseurs, MCP est la piste à privilégier.

La même annulation passe ici par les deux chemins ; la suite compare ce que chacun simplifie, ce qu’aucun ne règle pour vous, et la façon de choisir.

Partir d’un parcours simple

L’agent ouvre la liste des commandes avec une requête GET. Il suit le lien vers la commande concernée. La réponse contient son état et, si l’annulation est proposée, la description de cette action : destination, méthode et informations à fournir.

C’est le principe de l’hypermédia : les réponses contiennent les liens et les actions qui mènent aux étapes possibles. Fielding décrit un tel client comme un moteur qui passe d’un état au suivant en choisissant parmi les transitions présentes dans les représentations reçues (thèse, §5.3.3). Le client n’a pas à connaître à l’avance toutes les adresses du parcours. Il doit néanmoins comprendre le format des réponses et le sens métier des actions.

Deux parcours d’annulation convergent vers le même service : un outil MCP nommé annuler_commande, ou un client qui suit l’action hypermédia reçue. Dans les deux cas le service vérifie les droits, la révision et l’état.
Deux chemins pour demander la même annulation : outil MCP ou action hypermédia. Le service contrôle dans les deux cas les droits et l’état courant.

Le schéma montre l’autre voie : une couche d’outils nommés, placée devant l’API. Dans les deux cas, le serveur contrôle les droits et l’état au moment de l’annulation, car une action affichée quelques secondes plus tôt peut être devenue impossible entre-temps. Le client doit donc savoir traiter un refus ou un conflit.

La même annulation, par les deux chemins

Les échanges suivants sont fictifs, et les noms métier appartiennent à l’exemple. Chaque parcours part de la même commande C42, préparée, en révision 7 : ce sont deux comparaisons, pas deux annulations successives. Dans le premier parcours, le client connaît le point d’entrée et le format Siren, un format JSON publié qui décrit les actions avec leur adresse, leur méthode et leurs champs. Il trouve C42 puis reçoit cette représentation abrégée ; les liens de la liste ne sont pas reproduits :

GET /commandes/C42 HTTP/1.1
Accept: application/vnd.siren+json

{"class":["commande"],
 "properties":{"id":"C42","statut":"preparee","revision":7},
 "actions":[{"name":"annuler","method":"POST",
  "href":"https://api.example/commandes/C42/annulations",
  "type":"application/json",
  "fields":[{"name":"revision_attendue","type":"hidden","value":7},
            {"name":"motif","type":"text"}]}]}

La commande est préparée, en révision 7 : ce numéro avance à chaque changement de la commande. Le client comprend « annuler », demande l’action autorisée par sa mission, puis soumet à l’adresse fournie {"revision_attendue": 7, "motif": "demande_client"}. La réponse décrit A42, une annulation confirmée, et fournit son lien. Si l’adresse de l’action devient /operations/annulation/C42, un client qui suit effectivement href continue sans mise à jour de sa table de routes. Un changement de sens ou de champs reste en revanche une évolution de contrat.

Le second parcours passe par MCP, pour Model Context Protocol. Ce protocole permet à une application d’IA de découvrir et d’utiliser, selon un format commun, les capacités de différents serveurs : des outils, des ressources et des modèles de prompts. Un outil présente une action nommée et un schéma d’entrée. Les messages suivent JSON-RPC 2.0 : appeler un outil revient à appeler à distance une procédure nommée, le modèle RPC que la figure oppose à l’hypermédia. Selon la spécification du 25 novembre 2025, le client et le serveur effectuent d’abord l’initialisation du protocole ; le client découvre ensuite les outils avec {"jsonrpc": "2.0", "id": 1, "method": "tools/list"}. L’extrait de réponse annonce notamment :

{"name":"annuler_commande",
 "description":"Annuler une commande encore préparée. Refuse une révision périmée.",
 "inputSchema":{"type":"object","properties":{
   "commande":{"type":"string"},
   "revision_attendue":{"type":"integer"},
   "motif":{"type":"string"}},
  "required":["commande","revision_attendue","motif"],
  "additionalProperties":false}}

Un outil de lecture documenté a préalablement fourni C42 en révision 7. Le client appelle alors :

{"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"annuler_commande","arguments":{
 "commande":"C42","revision_attendue":7,"motif":"demande_client"}}}

Le résultat peut contenir structuredContent avec {"annulation": "A42", "etat": "confirmee"}, et la même information sérialisée dans un bloc texte, que la spécification recommande pour la compatibilité. Les enveloppes de découverte, d’appel et de résultat viennent de la spécification ; l’outil d’annulation est le contrat fictif de l’exemple. Une erreur métier peut être exposée par un résultat isError: true, avec un motif de conflit exploitable.

Supposons maintenant une variante : C42 a été expédiée entre la lecture et l’exécution. Les deux parcours refusent, parce que le service vérifie la révision et le statut en même temps qu’il enregistre l’annulation. L’absence d’action dans une réponse ou la description rassurante d’un outil ne remplace pas ce contrôle.

Le tableau compare ce que chaque voie demande quand quelque chose change.

Évolution à testerHypermédia directOutil MCP spécialisé
Adresse HTTP de l’action modifiéeLe client suit le nouveau lien, à format comprisL’adaptateur masque la route si son contrat reste stable
Ajout d’une référence de justificatif obligatoireLe client doit comprendre et renseigner le nouveau champLe schéma d’entrée et le client doivent gérer ce champ
Commande devenue non annulableAction absente puis contrôle à l’écritureOutil éventuellement toujours listé, contrôle à l’écriture
Coût de contexteReprésentations et actions effectivement luesDescriptions découvertes et résultats effectivement présentés

Ni le nombre de jetons ni le taux d’erreur ne sont mesurés ici. La comparaison met au jour le travail de maintenance : rendre un client capable d’interpréter les contrôles d’un côté, maintenir une façade d’outils de l’autre. Les deux se combinent d’ailleurs : un outil MCP peut lui-même suivre une API hypermédia.

Ce que l’hypermédia peut simplifier

Une API déjà utilisée par une interface humaine peut exposer les mêmes ressources à un agent, dans une représentation adaptée. Cela évite parfois de maintenir un catalogue d’outils supplémentaire. Les liens et les formulaires décrivent alors les possibilités au fil du parcours.

Les modèles connaissent généralement HTTP, les liens et les formulaires. Cette familiarité peut faciliter leur utilisation, mais elle ne prouve pas qu’un agent réussira mieux par cette voie. Cet article défend un choix d’architecture ; il ne présente pas de comparaison expérimentale établissant la supériorité de l’hypermédia sur MCP.

Le contexte chargé par l’agent, c’est-à-dire le texte que le modèle doit lire, dépend de ce qu’il consulte réellement. Il peut être plus léger qu’un grand catalogue transmis dès le départ. Les réponses volumineuses et les allers-retours ont aussi un coût, qu’il faut mesurer sur un parcours complet.

Ce que MCP apporte

La forme d’un outil, une action nommée avec son schéma d’entrée, rend une opération métier facile à appeler, même si les systèmes sous-jacents sont très différents. Pour intégrer plusieurs services tiers qui publient chacun leur serveur MCP, cette homogénéité est utile : l’agent apprend un seul protocole.

MCP n’oblige pas à charger toutes les descriptions dans le contexte du modèle. La découverte progressive et l’appel par du code peuvent limiter ce volume. L’approche décrite par Anthropic en novembre 2025 présente justement les serveurs MCP comme du code que l’agent explore, et ne charge que les définitions d’outils dont il a besoin ; dans l’exemple détaillé, l’usage passe de 150 000 jetons à 2 000. Le code et MCP ne s’excluent donc pas. Le code ne s’oppose pas davantage à l’hypermédia : dans le premier parcours aussi, l’agent peut écrire du code qui lit les contrôles et enchaîne leurs appels ; le code est alors le moyen d’exécution, l’hypermédia le contrat suivi. L’article sur l’outillage d’un agent par le code développe cette option. Le nombre d’outils à montrer est lui-même mesuré : une étude de mai 2026 trouve, sur un banc de 370 outils, que le bon outil figure presque aussi souvent dans la liste montrée quand sa longueur est choisie pour chaque demande, sept outils en moyenne, que lorsqu’elle est fixée à cinquante (90,3 % contre 90,8 %).

La différence à examiner est donc concrète : que voit l’agent à chaque étape, quelles informations doit-il apprendre, et combien d’interfaces l’équipe doit-elle entretenir ?

Les droits dépendent du serveur, quel que soit le protocole

Un catalogue d’outils explicite aide à comprendre ce qui est proposé. Une réponse hypermédia aide à découvrir les actions liées à une ressource. Dans les deux cas, les autorisations doivent être vérifiées lors de l’exécution ; la spécification MCP impose d’ailleurs aux serveurs de valider les entrées des outils et d’appliquer des contrôles d’accès.

Deux limites, à distinguer, s’imposent au jeton qui accompagne les requêtes de l’agent : son audience, le service auquel il est destiné, et sa portée, l’ensemble des opérations qu’il autorise. La RFC 8707 permet au client d’indiquer le service visé pour que le jeton soit restreint à cette audience, et note que la portée concerne l’accès demandé plutôt que l’endroit où il sera utilisé. Restreindre l’audience limite donc où un jeton peut être accepté ; cela ne réduit pas ses pouvoirs dans ce service.

Privilégiez des droits délégués limités à la tâche, et jamais plus larges que ceux de l’utilisateur pour qui l’agent agit : annuler les commandes de ce client, pas toutes les commandes. La journalisation doit identifier l’utilisateur, l’agent et les opérations réalisées. Cette traçabilité se construit explicitement : elle n’est pas une garantie de REST.

Le budget nécessite lui aussi ses propres limites : nombre d’appels, durée, volume ou montant maximal. Un agent peut dépenser beaucoup en répétant une action parfaitement autorisée.

Choisir selon le système que vous avez déjà

SituationPiste à évaluer
Une API hypermédia existe et vous la maîtrisezTester son utilisation directe sur un parcours représentatif.
Plusieurs fournisseurs exposent des serveurs MCPUtiliser ce contrat commun pour simplifier leur intégration.
Le travail porte sur des fichiers ou du code localComparer les outils disponibles avec un environnement de commandes correctement isolé.
Quelques actions sensibles doivent être très encadréesProposer une interface étroite, avec des contrôles d’autorisation et, si nécessaire, une validation humaine.

Pour départager les solutions, faites exécuter la même tâche : trouver une commande, vérifier qu’elle est annulable, l’annuler et confirmer le résultat. Comparez les erreurs, le coût, la lisibilité des traces et le travail de maintenance.

L’annulation de C42 a suivi les deux chemins jusqu’au même résultat : A42 confirmée quand la commande était encore préparée, un refus quand elle venait d’être expédiée. La décision reste celle du service ; les deux chemins se distinguent par ce que votre équipe doit entretenir pour y conduire l’agent : un client qui sait lire les contrôles d’une API existante, ou une couche d’outils qui unifie plusieurs systèmes. Retenez celle que l’équipe sait surveiller et faire évoluer ; la recette ci-dessus permet de le vérifier mieux que l’étiquette de l’interface.

Sources

Explorer

Sur le même sujet

Choisis dans l’index d’après les étiquettes de cet article — les plus proches d’abord, hors de sa série. Rien n’est écrit à la main : un article publié demain avec les mêmes étiquettes y prendra place.

Laisser un commentaire

Elle n'est jamais affichée ni publiée. Elle sert à regrouper vos commentaires et, si vous vous inscrivez un jour avec elle, à vous les rendre.

Votre commentaire sera relu avant d'être publié.