État et transport StreamableHTTP

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.

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.