Claude Academy
Chargement

StreamableHTTP en profondeur

Leçon 102 min

StreamableHTTP est la solution de MCP à un problème fondamental : certaines fonctionnalités de MCP nécessitent que le serveur envoie des requêtes au client, mais HTTP rend cela difficile. Explorons comment StreamableHTTP contourne cette limitation et dans quels cas vous pourriez avoir besoin de rompre ce contournement.

Le problème fondamental

Certaines fonctionnalités de MCP comme l'échantillonnage, les notifications et la journalisation reposent sur le fait que le serveur initie des requêtes vers le client. Cependant, HTTP est conçu pour que les clients envoient des requêtes aux serveurs, et non l'inverse. StreamableHTTP résout ce problème grâce à un contournement astucieux utilisant les Server-Sent Events (SSE).

Comment fonctionne StreamableHTTP

La magie opère grâce à un processus en plusieurs étapes qui établit des connexions persistantes entre le client et le serveur.

Les trois messages d'initialisation listés ci-dessous ; la notification Initialized porte l'ID de session et ne reçoit aucun résultat en retour.

Configuration initiale de la connexion

Le processus commence comme toute connexion MCP :

  • Le client envoie une Initialize Request au serveur
  • Le serveur répond avec un Initialize Result qui inclut un en-tête spécial mcp-session-id
  • Le client envoie une Initialized Notification avec l'ID de session

Cet ID de session est crucial : il identifie de manière unique le client et doit être inclus dans toutes les requêtes futures.

Le contournement SSE

Après l'initialisation, le client peut effectuer une requête GET pour établir une connexion Server-Sent Events. Cela crée une réponse HTTP de longue durée que le serveur peut utiliser pour diffuser des messages vers le client à tout moment.

GET mcp-server.com/mcp/ avec un en-tête mcp-session-id, auquel répond une réponse SSE qui peut rester ouverte arbitrairement longtemps.

Cette connexion SSE est la clé qui permet la communication du serveur vers le client. Le serveur peut désormais envoyer des requêtes, des notifications et d'autres messages via ce canal persistant.

Appels d'outils et double connexion SSE

Lorsque le client effectue un appel d'outil, les choses se complexifient. Le système crée deux connexions SSE distinctes :

Entre deux réponses SSE du serveur MCP, le client envoie une requête POST Call Tool Request avec un en-tête mcp-session-id.

  • Connexion SSE principale : utilisée pour les requêtes initiées par le serveur et reste ouverte indéfiniment
  • Connexion SSE spécifique à l'outil : créée pour chaque appel d'outil et se ferme automatiquement lorsque le résultat de l'outil est envoyé

Routage des messages

Différents types de messages sont acheminés via différentes connexions :

  • Notifications de progression : envoyées via la connexion SSE principale
  • Messages de journalisation et résultats d'outils : envoyés via la connexion SSE spécifique à l'outil

Des requêtes POST Call Tool Request vers mcp-server.com/mcp/ avec l'en-tête mcp-session-id ; les réponses SSE peuvent rester ouvertes arbitrairement longtemps.

Indicateurs de configuration qui rompent le contournement

StreamableHTTP inclut deux options de configuration importantes :

  • stateless_http
  • json_response

Définir ces options sur True peut rompre le mécanisme de contournement SSE. Vous pourriez vouloir activer ces indicateurs dans certains scénarios, mais cela limite les fonctionnalités complètes de MCP qui dépendent de la communication du serveur vers le client.

Points clés à retenir

StreamableHTTP est plus complexe que les autres transports MCP car il doit contourner les limitations de HTTP. Le contournement basé sur SSE permet d'obtenir les fonctionnalités complètes de MCP via HTTP, mais comprendre le modèle à double connexion est crucial pour le débogage et l'optimisation.

Lors de la création d'applications MCP avec StreamableHTTP, n'oubliez pas que les ID de session sont requis pour toutes les requêtes après l'initialisation, et que le système gère automatiquement plusieurs connexions SSE pour traiter les différents types de communication du serveur vers le client.