État et transport StreamableHTTP

Mise à jour du 2 novembre 2026 — état et sessions. Depuis la spécification MCP 2026-07-28, le transport Streamable HTTP n’a plus de sessions ni d’en-tête Mcp-Session-Id, et la reprise des flux SSE est supprimée : un serveur qui a besoin d’un état entre deux appels doit créer lui-même des identifiants et les faire passer comme arguments d’outils. Les options décrites ici concernent les serveurs qui implémentent encore la version précédente du protocole.

Les paramètres stateless_http et json_response dans les serveurs MCP contrôlent des aspects fondamentaux du comportement de votre serveur. Comprendre quand et pourquoi les utiliser est crucial, surtout si vous planifiez de mettre à l’échelle votre serveur ou de le déployer en production. À la fin de cette leçon, vous saurez pourquoi la montée en charge horizontale impose le mode sans état, ce que chaque drapeau sacrifie, et comment tester comme en production.

Quand vous avez besoin de HTTP stateless

Imaginez que vous construisez un serveur MCP qui devient populaire. Initialement, vous pourriez avoir quelques clients se connectant à une seule instance de serveur.

À mesure que votre serveur grandit, vous pourriez avoir des milliers de clients. La solution typique est la mise à l’échelle horizontale — faire tourner plusieurs instances de serveur derrière un load balancer.

Mais voilà où ça se complique. Les clients MCP ont besoin de deux connexions séparées :

• Une connexion GET SSE pour recevoir les requêtes serveur-vers-client
• Des requêtes POST pour appeler des outils et recevoir des réponses

Avec un load balancer, ces requêtes pourraient être routées vers différentes instances de serveur. Si votre outil doit utiliser Claude (via sampling), le serveur gérant la requête POST devrait se coordonner avec le serveur gérant la connexion GET SSE.

Client
  ├── GET /mcp ──────► Serveur A (instance 1)
  └── POST /mcp ─────► Serveur B (instance 2)  ← problème de coordination !

Comment stateless_http résout ça

stateless_http=True élimine ce problème de coordination — mais avec des compromis significatifs :

Ce qui est désactivé :

• Les clients ne reçoivent pas d’IDs de session (le serveur ne peut pas tracker les clients individuels)
• Pas de requêtes serveur-vers-client (la voie SSE primaire devient indisponible)
• Pas de sampling (impossible d’utiliser Claude ou d’autres LLM)
• Pas de rapports de progression
• Pas de subscriptions (impossible de notifier les clients des mises à jour de ressources)

Ce qui est activé :

• L’initialisation client n’est plus requise — les clients peuvent faire des requêtes directement sans handshake initial

Comprendre json_response

Le paramètre json_response=True est plus simple : il désactive simplement le streaming pour les réponses aux requêtes POST. Au lieu de recevoir plusieurs messages SSE pendant l’exécution d’un outil, vous n’obtenez que le résultat final en JSON simple.

Avec streaming désactivé :

• Pas de messages de progression intermédiaires
• Pas d’instructions de log pendant l’exécution
• Juste le résultat final de l’outil

Guide de décision

Utiliser stateless_http=True quand :

• Vous avez besoin de mise à l’échelle horizontale avec load balancers
• Vous n’avez pas besoin de communication serveur-vers-client
• Vos outils n’utilisent pas le sampling
• Vous voulez minimiser l’overhead de connexion

Utiliser json_response=True quand :

• Vous n’avez pas besoin de réponses en streaming
• Vous préférez des réponses HTTP simples
• Vous intégrez avec des systèmes qui attendent du JSON classique

Tableau de comparaison

Conseil pour la production

Si vous développez localement avec le transport STDIO mais planifiez de déployer avec le transport HTTP, testez avec le même transport que vous utiliserez en production. Les différences de comportement entre les modes stateful et stateless peuvent être significatives, et il vaut mieux détecter les problèmes pendant le développement.

Ces paramètres changent fondamentalement le fonctionnement de votre serveur MCP : choisissez-les en fonction de vos besoins spécifiques en matière de mise à l’échelle et de fonctionnalités. En SDK Python v2, ils ne se passent plus au constructeur mais à run() ou aux méthodes qui construisent l’application web ; et sur une connexion 2026-07-28, le serveur est de toute façon sans état, ce qui revient à généraliser le choix que cette leçon réserve aux déploiements répliqués.

À vous de jouer

1. Lancez deux instances de votre serveur HTTP derrière un répartiteur de charge local (ou simulez-le en alternant les ports) et observez ce qui casse en mode stateful.
2. Passez stateless_http=True : quels outils de votre serveur continuent de fonctionner ? Lesquels perdent leur progression ?
3. Rédigez, pour votre serveur, le tableau « fonctionnalité → mode requis » et décidez du mode de production.

Sources officielles : State and the StreamableHTTP transport (Claude Academy) · Streamable HTTP (spécification 2026-07-28) · Guide de migration du SDK Python (transports)

Points clés à retenir

• Plusieurs instances derrière un répartiteur de charge : le GET SSE et les POST d’un même client peuvent atterrir sur des serveurs différents ; le mode sans état supprime ce problème de coordination.
• stateless_http=True : plus de session, de requêtes serveur → client, de sampling, de progression, d’abonnements ; plus de poignée de main non plus.
• json_response=True : plus de streaming des réponses POST, seulement le résultat final.
• Testez avec le transport et le mode de la production ; en v2, ces réglages se passent à run().