Audit de migration MCP : la checklist en 12 points avant de toucher au code

La majorité des migrations MCP ratées ne ratent pas sur le code. Elles ratent parce que l'équipe a commencé à écrire avant de savoir ce que son serveur faisait vraiment.

Voici la liste que je passe avant de chiffrer une migration. Elle est faite pour être exécutée en une journée sur un serveur de taille moyenne, sans rien modifier. Un audit statique ne prouve pas la compatibilité, il te dit où regarder et combien ça va coûter.

Partie 1 : l'état caché

1. Toutes les lectures de session

Cherche Mcp-Session-Id, sessionId, session_id et leurs variantes dans le serveur, les clients maison, les passerelles et la configuration de déploiement. Note chaque occurrence avec le fichier et la ligne.

Signal d'alerte : zéro résultat sur un serveur qui a des workflows multi-étapes. Ça veut dire que l'état est là mais qu'il ne porte pas ce nom.

2. L'état en mémoire de process

Variables de module, singletons, caches déclarés au niveau du fichier, maps globales. Pour chacun, réponds à une seule question : est-ce que la correction du serveur dépend de cette valeur, ou est-ce seulement une optimisation ?

Si c'est la correction, c'est de l'état à externaliser. Si c'est une optimisation, vérifie que le chemin sans cache est testé.

3. Les workflows multi-appels

Liste les paires ou triplets d'outils qui doivent être appelés dans l'ordre. Pour chacun, note ce qui transite entre les appels et où ça vit.

C'est le point qui prend le plus de temps et qui donne le plus d'information. Si personne dans l'équipe ne sait répondre pour un workflow, c'est là que la migration va coincer.

4. Les abonnements et tâches de fond

Ils portaient de l'état, ils ne sont pas dans le chemin de requête principal, ils sont oubliés systématiquement. Vérifie s'ils survivent à un redémarrage d'instance et à un changement d'instance.

5. Le contexte utilisateur

Où est résolu le tenant, le plan, les permissions, les quotas ? Si la réponse est « au handshake », il faut le reconstruire par requête, et il faut estimer la charge supplémentaire sur la base de données.

Partie 2 : la conformité protocole

6. Le handshake

Repère tout ce qui est initialisé une fois par connexion et réutilisé ensuite. Voir le point 5, mais aussi la négociation de version et les capabilities.

7. Les listes qui varient par client

Est-ce que tools/list renvoie la même chose à tout le monde ? Si la liste dépend du plan ou d'un feature flag, c'est un changement de comportement produit à décider, pas seulement une correction technique.

8. Le code d'erreur -32002

Recherche de chaîne sur 32002, y compris dans les tests, les mocks, les fixtures, la documentation publique et les règles d'alerting.

9. Les en-têtes Mcp-Method et Mcp-Name

Deux questions : ton serveur les exige-t-il, et rejette-t-il une requête dont l'en-tête ne correspond pas au corps ? La deuxième est une question de sécurité, pas de conformité.

10. Les capacités dépréciées

Inventorie les usages de sampling, roots et logging. Le sampling est le seul qui a un impact de coût et de conformité, donc il se traite à part.

Partie 3 : l'infrastructure et l'autorisation

11. L'affinité de session

Regarde la configuration réelle du load balancer et de la passerelle, pas la documentation interne. Sticky sessions, store de sessions partagé, inspection du corps de requête pour router. Chacun de ces trois est un symptôme, et chacun peut disparaître une fois l'état externalisé.

12. La chaîne OAuth

Trois vérifications issues de la nouvelle révision : le paramètre iss est-il présent dans les réponses d'autorisation et validé côté client, l'application_type est-il précisé à l'enregistrement, les credentials sont-ils stockés indexés par issuer. Et si tu utilises le Dynamic Client Registration, sache qu'il est formellement déprécié au profit des Client ID Metadata Documents.

Le test qui conclut l'audit

Une fois la liste remplie, il reste une seule vérification, et c'est la seule qui prouve quelque chose.

Lance un scénario multi-étapes réel, en round-robin sur au moins deux instances, sans affinité, et tue une instance au milieu du scénario.

S'il finit correctement, l'externalisation est faite. S'il échoue, il reste de l'état caché, et l'appel qui échoue te dit exactement où.

Ce test entre dans ta CI. Les deux modes d'échec de cette migration, l'affinité collante et le code déprécié mort, sont silencieux jusqu'en production. Une instance unique en développement masque le premier, un hôte avec un modèle configuré masque le second.

Ce que l'audit te donne concrètement

À la fin des douze points, tu as trois choses que tu n'avais pas :

• une liste finie de fichiers à modifier, donc un chiffrage au lieu d'une estimation au doigt mouillé
• l'ordre de traitement, parce que certaines corrections en débloquent d'autres
• la séparation entre ce qui est urgent (transport, en-têtes, code d'erreur) et ce qui a douze mois devant lui (dépréciations)

C'est cette séparation qui fait la différence entre une migration de deux semaines et un chantier qui traîne un trimestre.

Fais-le toi-même, ou envoie-le-moi

Cette checklist est publique et elle est complète. Si tu as le temps, prends-la et déroule-la, elle marche.

Si tu préfères que quelqu'un qui ne fait que ça la déroule à ta place : envoie-moi ton dépôt ou un accès à ton serveur. Tu reçois sous 24 heures ouvrées un diagnostic écrit avec les douze points remplis, les fichiers concernés, l'ordre de traitement et le chiffrage de la remise à niveau. C'est gratuit et sans engagement.

Si tu décides ensuite de faire la migration toi-même avec ce rapport, c'est très bien aussi.

Prêt à faire le point ? Faire auditer mon serveur MCP →

Lectures liées

• Migrer un serveur MCP vers la spec 2026-07-28 : le guide complet
• Serveur MCP sans session : remplacer Mcp-Session-Id par des handles
• Mcp-Method et Mcp-Name : router du trafic MCP sans lire le body