Le transport StreamableHTTP — MCP — Sujets avancés

Le transport StreamableHTTP permet aux clients MCP de se connecter à des serveurs hébergés à distance via des connexions HTTP. Contrairement au transport STDIO qui nécessite client et serveur sur la même machine, ce transport ouvre la possibilité de serveurs MCP publics auxquels n’importe qui peut accéder. À la fin de cette leçon, vous saurez pourquoi HTTP contrarie la bidirectionnalité de MCP, quels messages en souffrent, et ce que contrôlent les deux drapeaux de configuration.

Cependant, il y a une mise en garde importante : certains paramètres de configuration peuvent significativement limiter les fonctionnalités de votre serveur MCP. Si votre application fonctionne parfaitement avec le transport STDIO en local mais se casse lors du déploiement avec le transport HTTP, c’est probablement la cause.

Paramètres de configuration importants

Deux paramètres clés contrôlent le comportement du transport StreamableHTTP :

Paramètre	Par défaut	Impact
`stateless_http`	`False`	Contrôle la gestion de l’état de connexion
`json_response`	`False`	Contrôle la gestion du format de réponse

Par défaut, les deux sont False. Certains scénarios de déploiement peuvent vous forcer à les mettre à True. Quand ils sont activés, ces paramètres peuvent casser les fonctionnalités essentielles comme les notifications de progression, les logs, et les requêtes initiées par le serveur.

Le défi de la communication HTTP

Pour comprendre pourquoi ces limitations existent, rappelons comment fonctionne la communication HTTP standard :

✅ Client → Serveur : facile (le serveur a une URL connue)
✅ Serveur → Client : facile (réponse à une requête existante)
❌ Serveur → Client (initié) : difficile (le client n'a pas d'URL connue)
❌ Client → Serveur (réponse) : problématique

Types de messages MCP affectés

Cette limitation HTTP impacte des patterns de communication MCP spécifiques. Les types de messages suivants deviennent difficiles à implémenter avec du HTTP simple :

Requêtes initiées par le serveur :

CreateMessageRequest (sampling)
ListRootsRequest

Notifications :

ProgressNotification
LoggingMessageNotification
InitializedNotification
CancelledNotification

Ce sont exactement les fonctionnalités qui se cassent quand vous activez les paramètres HTTP restrictifs. Les barres de progression disparaissent, les logs s’arrêtent, et les requêtes de sampling initiées par le serveur échouent.

La solution StreamableHTTP

Le transport StreamableHTTP fournit une solution intelligente pour contourner les limitations d’HTTP, mais avec des compromis. Quand vous êtes forcé d’utiliser stateless_http=True ou json_response=True, vous dites essentiellement au transport d’opérer dans les contraintes d’HTTP plutôt que de les contourner.

Décisions à prendre

Comprendre ces limitations vous aide à :

Choisir le bon transport pour différents scénarios de déploiement
Concevoir votre serveur MCP pour gérer gracieusement les contraintes HTTP
Accepter les compromis de fonctionnalités réduites vs les avantages de l’hébergement distant

La leçon suivante explique en détail comment StreamableHTTP utilise les Server-Sent Events (SSE) pour contourner les limitations d’HTTP et permettre une communication bidirectionnelle. Depuis la version 2026-07-28, la question se pose différemment : le serveur n’initie plus de requêtes (le pattern en plusieurs allers-retours les remplace), les requêtes POST portent des en-têtes Mcp-Method et Mcp-Name, et les notifications de changement passent par un flux subscriptions/listen auquel le client s’abonne explicitement.

À vous de jouer

Dessinez les quatre directions de communication (client → serveur requête et réponse, serveur → client requête et réponse) et marquez celles qu’HTTP seul sait faire.
Pour votre propre serveur, listez les fonctionnalités de ce cours qu’il utilise (sampling, progression, logs) : lesquelles survivraient à stateless_http=True ?
Lisez les en-têtes obligatoires des requêtes POST dans la spécification 2026-07-28 et repérez Mcp-Method.

Sources officielles : The StreamableHTTP transport (Claude Academy) · Streamable HTTP (spécification 2026-07-28) · Changelog 2026-07-28

Points clés à retenir

Streamable HTTP permet des serveurs distants et publics ; HTTP, lui, ne sait pas laisser le serveur initier une requête.
Les messages touchés : requêtes du serveur (sampling, roots) et notifications (progression, logs, etc.).
stateless_http et json_response, à False par défaut, échangent des fonctionnalités contre de la simplicité et de la montée en charge.
En 2026-07-28, plus de requêtes initiées par le serveur : MRTR, en-têtes Mcp-Method/Mcp-Name, et subscriptions/listen pour les notifications.