Migrer un serveur MCP HTTP vers 2026-07-28 tout en prenant en charge les anciens clients

Objectif

État au 25 octobre 2026. Migrer un serveur MCP HTTP vers la révision 2026-07-28 tout en maintenant un mode de fonctionnement explicitement pris en charge pour les clients 2025-11-25. Vérifier de nouveau les spécifications versionnées du transport, les schémas de messages et la prise en charge documentée du SDK choisi avant le déploiement. Il s'agit d'une proposition de procédure de recette, et non du compte rendu d'une migration testée.

Prérequis

Recenser les révisions du protocole utilisées par les clients, les gestionnaires d'initialisation, le stockage des sessions, les fonctions de rappel, les abonnements et les politiques d'autorisation. Préparer un point de terminaison de préproduction derrière une passerelle de même type qu'en production, une configuration de retour arrière et des clients pour les deux révisions. Utiliser des outils de test sans effet dommageable et des identités de test distinctes. Consigner la version réelle du paquet SDK ; une révision du protocole n'est pas une version de paquet.

Étapes

1. Séparer les modes de traitement du protocole. Les règles de compatibilité autorisent les deux comportements sur un même point de terminaison. Un appel initialize selon l'ancienne révision sélectionne la sémantique correspondante ; les métadonnées modernes propres à chaque requête sélectionnent le traitement sans état. Conserver le comportement négocié de l'ancienne révision tant que ses clients restent pris en charge. Ne pas appliquer indistinctement les exigences modernes relatives aux en-têtes à l'initialisation des anciens clients.

2. Rendre les requêtes autonomes. Exiger io.modelcontextprotocol/protocolVersion et io.modelcontextprotocol/clientCapabilities dans params._meta. Inclure l'identité du client comme recommandé, sans jamais utiliser cette identité autodéclarée comme autorisation. Cesser de déduire les capacités ou le contexte applicatif de la connexion précédente. Exposer des identifiants explicites pour l'état conservé entre plusieurs appels.

3. Mettre en œuvre la découverte et la validation du transport. Implémenter server/discover, recopier la version dans MCP-Protocol-Version et vérifier la concordance des en-têtes obligatoires avec le corps. Un test élémentaire de découverte pour un point de terminaison de préproduction sans authentification est :

   curl --request POST 'https://mcp.example.com/mcp' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json, text/event-stream' \
     --header 'MCP-Protocol-Version: 2026-07-28' \
     --header 'Mcp-Method: server/discover' \
     --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"migration-check","version":"local"}}}}'
   

   Remplacer l'URL d'exemple. Pour les points de terminaison protégés, utiliser le client de test authentifié approuvé pour le déploiement ; ne pas désactiver l'authentification pour effectuer cette vérification.

4. Mettre à jour les résultats et les interactions. Émettre resultType: "complete" pour les résultats ordinaires. Implémenter MRTR pour les opérations interactives autorisées : renvoyer input_required, puis accepter les inputResponses correspondantes et le requestState opaque inchangé avec un nouvel identifiant de requête. Vérifier l'intégrité de l'état lorsqu'il influe sur les permissions ou la logique métier ; le lier à l'entité authentifiée, à une échéance et à l'opération d'origine comme recommandé. Imposer une utilisation unique côté serveur lorsque cela est nécessaire.

5. Migrer les notifications et la mise en cache. Remplacer le flux de notifications GET indépendant par subscriptions/listen. Conserver les flux SSE propres à une requête là où ils sont utilisés, mais supprimer la reprise avec Last-Event-ID : la fermeture d'un flux de réponse signale une annulation. Ajouter un ttlMs positif ou nul et le cacheScope approprié aux résultats complets couverts par la spécification de mise en cache. Exclure du cache les résultats intermédiaires et ceux des nouvelles tentatives MRTR.

6. Tester explicitement la récupération en cas de version incompatible. Une version moderne non prise en charge renvoie UnsupportedProtocolVersionError avec les versions prises en charge. Les clients devraient réessayer avec une version compatible. Sur HTTP 400, examiner le corps JSON-RPC : les erreurs modernes reconnues nécessitent une correction ou le choix d'une version ; un corps vide ou non reconnu autorise le repli vers l'initialisation de l'ancienne révision. Ne pas rétrograder uniquement parce qu'une requête moderne valide a été rejetée.

7. Tester le passage par l'infrastructure de déploiement. En préproduction, exécuter la découverte, la récupération d'une liste, un appel sans effet dommageable, une nouvelle tentative interactive et un abonnement via la passerelle. Répéter avec un ancien client et répartir les requêtes modernes entre les instances. Interrompre une réponse SSE sans effet dommageable et vérifier l'annulation et le rétablissement sûr du fonctionnement sans reprise du flux. Vérifier les autorisations de chaque identité et confirmer que les métadonnées des requêtes parviennent inchangées au serveur.

Résultat attendu

Les deux révisions prises en charge permettent de mener à bien leurs parcours respectifs. Les opérations modernes ne nécessitent aucune session de transport ; les anciens clients conservent le cycle de vie négocié. Garder l'ancienne configuration disponible jusqu'à la réussite des contrôles de recette.

Limites et base de vérification

La spécification citée définit le comportement du protocole ; les étapes ci-dessus constituent un plan de vérification proposé par l'exploitant. Elles ne démontrent ni la compatibilité du SDK, ni la sûreté des nouvelles tentatives pour les actions métier, ni le bon fonctionnement sur un répartiteur de charge particulier. Ces points nécessitent des tests propres au déploiement.