Accueil / Étendre : compétences, MCP, sous-agents, hooks, plugins

Connecter un serveur MCP et ce qui a changé

Un serveur MCP distant se connecte en une commande, claude mcp add, et Claude Code détecte lui-même si une authentification est nécessaire. claude mcp list affiche l'état réel de chaque serveur déclaré. Indépendamment de Claude Code, la spécification MCP a changé de cœur : un cœur sans état remplace le cœur avec état.

Un serveur MCP distant se connecte en une commande : claude mcp add --transport http nom-du-serveur https://exemple.example.com/mcp déclare l'entrée, et Claude Code détecte lui-même si une authentification est nécessaire. Quand le serveur répond 401 ou 403, Claude Code marque l'entrée comme nécessitant une authentification et propose claude mcp login pour ouvrir le flux OAuth, ou l'option --header "Authorization: Bearer ..." pour un jeton fixe passé à la main.

Vérifier avant de faire confiance

claude mcp list affiche l'état réel de chaque serveur déclaré, avec au moins six statuts possibles : connecté, authentification nécessaire, échec de connexion, approbation en attente, rejeté d'après le réglage disabledMcpjsonServers, ou désactivé pour ce projet et réactivable par /mcp ; un serveur HTTP ou SSE déjà utilisé peut aussi s'afficher en cache. Un échec de connexion signale que Claude Code n'a pas réussi à joindre ce serveur précis, pas que la commande list elle-même a échoué.

$ claude mcp list
depot-tickets       Connected
facturation-api      Needs authentication
brouillon-crm        Pending approval

La portée choisie à l'ajout détermine qui voit ce serveur. Par ordre de priorité décroissante : la portée locale (--scope local, la valeur par défaut, privée, stockée dans ~/.claude.json), puis la portée projet (--scope project, le fichier .mcp.json partagé par git, décrit dans la leçon précédente), puis la portée utilisateur (--scope user, disponible sur tous les projets du poste). Quand deux portées déclarent le même nom de serveur, l'entière configuration de la portée la plus forte est utilisée, rien ne se fusionne champ par champ entre les deux.

Le protocole a changé de cœur le 28 juillet 2026

Indépendamment de Claude Code, la spécification MCP elle-même a changé de forme. La révision publiée le 28 juillet 2026 remplace un cœur avec état, où client et serveur ouvraient d'abord une poignée de main initialize avant tout échange, par un cœur sans état où chaque requête porte ses propres informations de version dans un paramètre _meta. L'en-tête Mcp Session Id disparaît du transport HTTP. La fonctionnalité Tasks, qui permettait de suivre un travail long sans bloquer la réponse, sort du cœur du protocole et devient une extension officielle séparée, avec un sondage tasks/get à la place d'une attente bloquante. Un champ extensions s'ajoute par ailleurs aux capacités du client et du serveur, pour porter d'éventuelles extensions futures au-delà du cœur du protocole.

Claude Code choisit un runtime MCP au démarrage et le garde jusqu'à la sortie. Le runtime v2 demande aux serveurs HTTP, aux serveurs stdio et aux connecteurs claude.ai s'ils acceptent la révision la plus récente, et l'utilise avec ceux qui l'acceptent. Depuis octobre 2026, c'est le comportement par défaut pour un serveur stdio, y compris sur Bedrock, Vertex et Foundry : la variable MCP_PROTOCOL_NEGOTIATION=legacy le refuse. Un serveur ancien, écrit avant juillet 2026, continue de fonctionner, la négociation choisissant la révision qu'il comprend. Cette section décrit l'état du protocole au 24 octobre 2026, un sujet qui bouge au rythme de ses propres versions, pas de celui du cours. La leçon suivante montre comment écrire, côté serveur, le programme que cette commande claude mcp add vient de déclarer.

Relancer et filtrer

Dans le terminal interactif, /mcp reconnect all relance d'un coup tous les serveurs en échec ou à authentifier. Si vous gérez une liste blanche allowedMcpServers dans les réglages gérés, elle ne filtre plus, depuis octobre 2026, les serveurs stdio de managed-mcp.json qui n'utilisent ${VAR} que dans env : un serveur absent de la liste se charge après la mise à jour, et deniedMcpServers le garde éteint.