Connecter Claude Code aux outils via MCP

Claude Code peut se connecter à des centaines d’outils externes et de sources de données via le Model Context Protocol (MCP), une norme open source pour les intégrations IA-outils. Les serveurs MCP donnent à Claude Code accès à vos outils, bases de données et API. Connectez un serveur lorsque vous vous trouvez à copier des données dans le chat à partir d’un autre outil, comme un suivi de problèmes ou un tableau de bord de surveillance. Une fois connecté, Claude peut lire et agir sur ce système directement au lieu de travailler à partir de ce que vous collez. Si vous connectez votre premier serveur, commencez par le guide de démarrage MCP pour une procédure pas à pas. Cette page est la référence complète.

Ce que vous pouvez faire avec MCP

Avec les serveurs MCP connectés, vous pouvez demander à Claude Code de :

Implémenter des fonctionnalités à partir de suivi de problèmes : « Ajouter la fonctionnalité décrite dans le problème JIRA ENG-4521 et créer une PR sur GitHub. »
Analyser les données de surveillance : « Vérifier Sentry et Statsig pour vérifier l’utilisation de la fonctionnalité décrite dans ENG-4521. »
Interroger les bases de données : « Trouver les e-mails de 10 utilisateurs aléatoires qui ont utilisé la fonctionnalité ENG-4521, en fonction de notre base de données PostgreSQL. »
Intégrer les conceptions : « Mettre à jour notre modèle d’e-mail standard en fonction des nouvelles conceptions Figma qui ont été publiées sur Slack »
Automatiser les flux de travail : « Créer des brouillons Gmail invitant ces 10 utilisateurs à une session de rétroaction sur la nouvelle fonctionnalité. »
Réagir aux événements externes : Un serveur MCP peut également agir comme un canal qui pousse des messages dans votre session, afin que Claude réagisse aux messages Telegram, aux discussions Discord ou aux événements webhook pendant que vous êtes absent.

Trouver et créer des serveurs MCP

Parcourez les connecteurs vérifiés dans le Répertoire Anthropic. Les connecteurs du répertoire utilisent la même infrastructure MCP que Claude Code, vous pouvez donc ajouter n’importe quel serveur distant répertorié avec claude mcp add.

Vérifiez que vous faites confiance à chaque serveur avant de le connecter. Les serveurs qui récupèrent du contenu externe peuvent vous exposer à un risque d’injection de prompt.

Pour créer votre propre serveur, consultez le guide du serveur MCP pour les principes fondamentaux du protocole et la documentation de création de connecteurs Claude pour l’authentification, les tests et la soumission au répertoire. Vous pouvez également faire en sorte que Claude crée un serveur pour vous avec le plugin officiel mcp-server-dev.

Installer le plugin

Dans l’extension VS Code ou l’application de bureau, suivez Installer un plugin au lieu de cette étape. Dans un terminal, démarrez Claude Code en exécutant claude, puis saisissez ceci à son invite :

/plugin install mcp-server-dev@claude-plugins-official

Si l’installation échoue, faites correspondre le message que Claude Code signale :

Marketplace "claude-plugins-official" not found : ajoutez la marketplace avec /plugin marketplace add anthropics/claude-plugins-official, puis réessayez l’installation.
Plugin "<name>" not found in marketplace "claude-plugins-official" : votre copie locale du catalogue de la marketplace n’est peut-être pas à jour. Actualisez-la avec /plugin marketplace update claude-plugins-official, puis réessayez l’installation. Si la nouvelle tentative affiche le même message, consultez Plugin introuvable dans la marketplace.

Si le résumé de l’installation signale Run /reload-plugins to apply., Claude Code exécute ensuite ce rechargement pour vous. Si le rechargement vous avertit que votre prochain message relirait la conversation, exécutez /reload-plugins --force.

Exécuter le skill de création

/mcp-server-dev:build-mcp-server

Claude vous pose des questions sur votre cas d’usage et crée un serveur HTTP distant ou un serveur stdio local.

Installation des serveurs MCP

Les serveurs MCP peuvent être configurés de plusieurs façons selon vos besoins :

Option 1 : Ajouter un serveur HTTP distant

Les serveurs HTTP sont l’option recommandée pour se connecter à des serveurs MCP distants. C’est le transport le plus largement supporté pour les services basés sur le cloud.

# Syntaxe de base
claude mcp add --transport http <name> <url>

# Exemple réel : Se connecter à Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Exemple avec jeton Bearer
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Lors de la configuration des serveurs MCP via JSON dans .mcp.json, ~/.claude.json, ou claude mcp add-json, le champ type accepte streamable-http comme alias pour http. La spécification MCP utilise le nom streamable-http pour ce transport, donc les configurations copiées à partir de la documentation du serveur fonctionnent sans modification. Une entrée JSON qui a une url mais pas de type est une erreur de configuration, car Claude Code lit une entrée sans type comme un serveur stdio. Claude Code ignore ce serveur et signale MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. Seule une application hôte du SDK, telle qu’une application Agent SDK ou l’application de bureau, peut enregistrer un serveur "type": "sdk" en processus. Claude Code ignore une entrée "type": "sdk" dans .mcp.json, ~/.claude.json, ou les paramètres et signale Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register.

Dans les exécutions --output-format stream-json, Claude Code signale également une entrée --mcp-config ignorée dans le champ mcp_server_errors de l’événement system/init, afin que les scripts puissent détecter que le serveur n’a jamais été chargé.

Option 2 : Ajouter un serveur SSE distant

Le transport SSE (Server-Sent Events) est déprécié. Utilisez plutôt des serveurs HTTP, si disponibles.

Certains services exposent toujours uniquement un endpoint SSE. Ajoutez-les avec la même commande claude mcp add --transport http <name> <url> que un serveur HTTP. Claude Code essaie d’abord le transport HTTP et bascule vers SSE lorsque le serveur ne l’accepte pas. Le basculement automatique nécessite Claude Code v2.1.265 ou ultérieur. Sur une version antérieure, ou pour vous connecter directement via SSE, passez plutôt --transport sse :

# Syntaxe de base
claude mcp add --transport sse <name> <url>

# Exemple réel : Se connecter à Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Exemple avec en-tête d'authentification
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Option 3 : Ajouter un serveur stdio local

Les serveurs stdio s’exécutent en tant que processus locaux sur votre machine. Ils sont idéaux pour les outils qui ont besoin d’un accès direct au système ou de scripts personnalisés. Claude Code définit CLAUDE_PROJECT_DIR dans l’environnement du serveur généré pour la racine du projet, afin que votre serveur puisse résoudre les chemins relatifs au projet sans dépendre du répertoire de travail. C’est le même répertoire que les hooks reçoivent dans leur variable CLAUDE_PROJECT_DIR. Lisez-le depuis l’intérieur de votre processus serveur, par exemple process.env.CLAUDE_PROJECT_DIR en Node ou os.environ["CLAUDE_PROJECT_DIR"] en Python. CLAUDE_PROJECT_DIR est la racine de projet stable et ne change pas lorsque vous ajoutez ou supprimez des répertoires de travail en cours de session. Un serveur qui limite son propre accès au système de fichiers à un ensemble de répertoires autorisés devrait implémenter la requête MCP roots/list à la place. Claude Code répond à roots/list avec le répertoire de lancement de la session plus chaque répertoire de travail supplémentaire que vous avez accordé avec --add-dir, /add-dir, ou le paramètre additionalDirectories. Claude Code envoie notifications/roots/list_changed lorsque cet ensemble change. Cette variable est définie dans l’environnement du serveur, pas dans l’environnement de Claude Code lui-même, donc la référencer via l’expansion ${VAR} dans la command ou args d’une entrée .mcp.json de portée projet ou d’une entrée de serveur de portée locale ou utilisateur dans ~/.claude.json nécessite une valeur par défaut telle que ${CLAUDE_PROJECT_DIR:-.}. Les configurations MCP fournies par les plugins substituent ${CLAUDE_PROJECT_DIR} directement et n’ont pas besoin de la valeur par défaut.

# Syntaxe de base
claude mcp add [options] <name> -- <command> [args...]

# Exemple réel : Ajouter un serveur Airtable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Pour les serveurs stdio, le -- (double tiret) sépare les options propres à Claude, telles que --transport, --env, et --scope, de la commande et des arguments qui exécutent le serveur. Tout ce qui suit -- est transmis au serveur sans modification.Par exemple :

claude mcp add --transport stdio myserver -- npx server → exécute npx server
claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 → exécute python server.py --port 8080 avec KEY=value dans l’environnement

Sans --, Claude Code essaierait d’analyser les flags du serveur, comme --port ci-dessus, comme ses propres options.--env accepte plusieurs paires KEY=value. Si le nom du serveur vient directement après --env, la CLI lit le nom comme une autre paire et le rejette, donc placez au moins une autre option, telle que --transport stdio, entre --env et le nom du serveur.

Comment Claude Code arrête un serveur stdio

Lorsque Claude Code déconnecte un serveur stdio, par exemple à la fin de votre session, il envoie un signal au processus du serveur et attend brièvement qu’il se termine avant de le forcer à s’arrêter. Si votre serveur enregistre un état ou supprime des fichiers de verrouillage à l’arrêt, gérez le signal propre à votre plateforme et terminez dans ce délai :

Sur macOS et Linux : Claude Code envoie SIGINT, puis SIGTERM si le processus s’exécute toujours 100 millisecondes plus tard, puis SIGKILL après 400 millisecondes supplémentaires.
Sur Windows : Claude Code ferme le stdin du serveur, puis met fin à l’arborescence de processus du serveur si le processus s’exécute toujours 300 millisecondes plus tard.

Avant la v2.1.296, Claude Code sous Windows mettait fin immédiatement à l’arborescence de processus du serveur, sans fermer d’abord stdin ni attendre.

Option 4 : Ajouter un serveur WebSocket distant

Les serveurs WebSocket maintiennent une connexion bidirectionnelle persistante, ce qui convient aux serveurs MCP distants qui poussent des événements vers Claude sans être sollicités. Utilisez plutôt HTTP lorsque votre serveur répond uniquement aux requêtes, car HTTP supporte OAuth et le flag claude mcp add --transport, tandis que WebSocket ne supporte ni l’un ni l’autre. Configurez les serveurs WebSocket dans .mcp.json ou avec claude mcp add-json :

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

L’entrée type: "ws" accepte les mêmes champs url, headers, headersHelper, timeout, et alwaysLoad que http. L’authentification est basée sur les en-têtes uniquement, donc passez un jeton statique dans headers ou générez-en un au moment de la connexion avec headersHelper. Le flag claude mcp add --transport n’accepte pas ws.

Ajouter un serveur à partir d’instructions de configuration écrites pour un autre client

Les serveurs MCP ne sont pas spécifiques à Claude Code, donc les instructions de configuration d’un serveur peuvent être écrites pour Claude Desktop, Cursor, ou un autre client MCP et ne pas donner de commande claude mcp add. Pour ajouter le serveur quand même, cherchez dans ces instructions une URL, une commande de lancement, ou un bloc JSON :

Une URL telle que https://mcp.example.com/mcp : le serveur est distant.
Une commande de lancement telle que npx -y @example/mcp-server : le serveur s’exécute sur votre machine.
Un bloc JSON mcpServers : configuration écrite pour le fichier de paramètres d’un autre client.

Chacun est l’une des entrées que les quatre options dans Installation des serveurs MCP prennent. Trouvez la forme que vous avez ci-dessous pour la transformer en commande que Claude Code accepte. Chaque commande écrit dans la portée locale sauf si vous ajoutez --scope project ou --scope user.

Ajouter un serveur à partir d’une URL

Une URL signifie que le serveur est distant. Pour un endpoint https://, ajoutez-le avec --transport http, ou suivez Option 2 lorsque les instructions indiquent que l’endpoint utilise SSE. Pour un endpoint wss://, utilisez plutôt Option 4, car --transport n’accepte pas ws :

claude mcp add --transport http example https://mcp.example.com/mcp

Si les instructions donnent également une clé API ou un en-tête de jeton, passez-le avec --header comme montré dans Option 1.

Ajouter un serveur à partir d’une commande `npx`, `uvx`, ou binaire

Une commande de lancement signifie que le serveur s’exécute en tant que processus stdio local. Mettez la commande entière après --, afin que Claude Code transmette les flags tels que -y à la commande qui démarre le serveur au lieu de les lire comme ses propres options. Passez toutes les variables d’environnement que les instructions demandent avec --env, après le nom du serveur et avant -- :

claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

Option 3 couvre le séparateur -- en détail.

Ajouter un serveur à partir d’un bloc JSON `mcpServers`

Un bloc mcpServers écrit pour un autre client MCP, tel que Claude Desktop, utilise la clé wrapper et la forme d’entrée que Claude Code lit. Passez à claude mcp add-json l’objet à l’intérieur de mcpServers, pas le wrapper. Deux entrées ont besoin d’une réparation d’abord :

Une url sans type : ajoutez "type": "http", "type": "sse", ou "type": "ws" pour correspondre à l’endpoint. Claude Code lit une entrée sans type comme un serveur stdio, donc une entrée url sans type échoue.
Une clé avec des caractères autres que des lettres, des chiffres, des tirets, et des traits de soulignement : choisissez un nom de serveur qui utilise uniquement ces caractères. Sinon, la clé est le nom du serveur.

Par exemple, ce bloc :

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

devient cette commande :

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Ajouter des serveurs MCP à partir de la configuration JSON couvre l’échappement du shell et le flag --scope pour add-json. Pour partager le serveur avec votre équipe à la place, ajoutez --scope project, ou ajoutez l’entrée sous mcpServers dans .mcp.json à la racine de votre projet et faites-en un commit. Portée du projet couvre comment Claude Code charge et approuve ce fichier. Chaque commande claude mcp add et claude mcp add-json imprime une ligne Added ... en cas de succès. Pour vérifier que Claude Code s’est connecté, exécutez claude mcp get <name> ; État du serveur couvre les statuts qu’il affiche et l’étape d’approbation pour les serveurs .mcp.json.

Gestion de vos serveurs

Une fois configurés, vous pouvez gérer vos serveurs MCP avec ces commandes :

# Lister tous les serveurs configurés
claude mcp list

# Obtenir les détails d'un serveur spécifique
claude mcp get notion

# Supprimer un serveur
claude mcp remove notion

# (dans Claude Code) Vérifier l'état du serveur
/mcp

Lorsque vous supprimez un serveur distant, Claude Code supprime également les jetons OAuth et l’enregistrement client qu’il avait stockés pour ce serveur. Claude Code ne révoque pas les jetons auprès du serveur d’autorisation qui les a émis. Pour révoquer les jetons lorsque le serveur d’autorisation prend en charge la révocation, exécutez claude mcp logout <name> dans votre shell avant claude mcp remove <name>.

État du serveur

claude mcp add confirme un ajout réussi en imprimant une ligne Added ..., ce qui signifie que la configuration a été écrite. Si la commande imprime plutôt un message was not saved, voir MCP server was not saved or removed ; pour un message may not have been saved, voir MCP server may not have been saved or removed. claude mcp list affiche un statut de santé à côté de chaque serveur qu’il liste, tel que ✔ Connected, ! Needs authentication, ou ✘ Failed to connect. Un statut d’échec signifie que Claude Code n’a pas pu se connecter à ce serveur, pas que la commande list a échoué. Les statuts dans cette liste signalent une décision de configuration plutôt qu’une tentative de connexion, donc Claude Code les imprime sans se connecter au serveur :

⏸ Pending approval (run `claude` to approve) : un serveur de portée projet issu de .mcp.json que vous n’avez pas encore approuvé. Claude Code l’affiche à la fois dans claude mcp list et claude mcp get <name>. Exécutez claude en mode interactif pour l’examiner et l’approuver.
✘ Rejected (see disabledMcpjsonServers in settings) : un serveur .mcp.json qu’une entrée disabledMcpjsonServers rejette. Claude Code l’affiche uniquement dans claude mcp get <name>.
⊘ Disabled for this project (re-enable via /mcp) : un serveur que la liste disabledMcpServers du projet nomme. Claude Code l’affiche à la fois dans claude mcp list et claude mcp get <name>. Réactivez le serveur à partir du panneau /mcp.
✘ Blocked by enterprise managed policy : un serveur refusé par l’une des politiques de votre organisation. Claude Code l’affiche à la fois dans claude mcp list et claude mcp get <name>. Un serveur bloqué par une liste d’autorisation, une liste de refus ou une autre restriction de la configuration MCP gérée est masqué dans les deux commandes plutôt qu’affiché avec ce statut. Demandez à votre administrateur quelle politique bloque le serveur.

Approbations des serveurs de projet et confiance de l’espace de travail

claude mcp list et claude mcp get lisent les approbations .mcp.json uniquement à partir des fichiers de paramètres qui ne sont pas commités dans le dépôt jusqu’à ce que vous fassiez confiance à l’espace de travail en y exécutant claude et en acceptant la boîte de dialogue de confiance de l’espace de travail. Un dépôt cloné ne peut pas approuver ses propres serveurs : enableAllProjectMcpServers ou enabledMcpjsonServers commité dans le .claude/settings.json du projet est ignoré dans un dossier non approuvé, et le serveur reste à ⏸ Pending approval au lieu d’être connecté et vérifié. Les approbations de ces sources s’appliquent toujours dans un dossier non approuvé :

votre ~/.claude/settings.json utilisateur
paramètres gérés
paramètres passés avec --settings

Claude Code applique également les approbations à partir d’un .claude/settings.local.json non suivi, mais il exécute git pour vérifier si le fichier est suivi, et il n’exécute cette vérification que dans un dossier approuvé. Dans un dossier que vous n’avez jamais approuvé, Claude Code attend la boîte de dialogue de confiance avant d’appliquer les approbations du fichier, sauf si le dossier est votre répertoire de configuration personnel : votre répertoire personnel, ou un répertoire dont vous avez défini le .claude comme CLAUDE_CONFIG_DIR. Avant la v2.1.207, Claude Code appliquait les approbations à partir d’un .claude/settings.local.json non suivi même dans un dossier que vous n’aviez jamais approuvé. Une entrée disabledMcpjsonServers dans n’importe quel fichier de paramètres rejette toujours le serveur.

Détail de l’état du serveur

Dans /mcp, y compris le menu d’un serveur là-bas, et dans le gestionnaire /plugin, un serveur HTTP ou SSE distant que vous avez utilisé auparavant peut afficher un statut cached tel que cached 2h ago · connects on first use · 5 tools. Claude Code a chargé la liste d’outils du serveur à partir de son cache de découverte, enregistré dans une session précédente, au lieu de se connecter au démarrage, et Claude Code connecte le serveur la première fois que Claude appelle l’un des outils du serveur. Les outils sont disponibles à partir de votre premier message, donc vous n’avez rien à faire. Le cache de découverte et son statut cached nécessitent Claude Code v2.1.221 ou ultérieur. Le cache de découverte est désactivé par défaut sauf si un déploiement progressif l’a activé pour votre compte. Définissez MCP_DISCOVERY_CACHE=1 pour l’activer, ou 0 pour le garder désactivé même lorsque le déploiement l’a activé. Avant la v2.1.238, le cache était activé par défaut. Lorsque vous sélectionnez Disable ou Clear authentication dans le menu d’un serveur dans /mcp, Claude Code supprime également l’entrée du cache de ce serveur. Reconnect la supprime également sur un serveur connecté ou défaillant ; sur un serveur cached, Reconnect connecte le serveur maintenant et conserve l’entrée. La prochaine fois que Claude Code se connecte au serveur après suppression de l’entrée, il récupère la liste d’outils du serveur au lieu du cache. Lorsque le statut d’un serveur est ✘ Failed to connect, claude mcp list ajoute le détail de l’échec à cette ligne de statut, et claude mcp get <name> l’affiche sur une ligne Issue:. Le détail correspond au statut HTTP ou au code d’erreur, ainsi qu’à tout texte d’erreur renvoyé par le serveur. La vue détaillée du serveur dans /mcp inclut le même texte signalé par le serveur dans sa ligne Issue:. Claude Code masque dans ce détail tout texte ressemblant à des identifiants et n’inclut jamais l’URL développée du serveur, qui peut contenir des secrets. Claude Code n’ajoute aucun détail à un statut ✘ Connection error, car le texte d’exception qu’il y afficherait peut intégrer cette URL. Lorsque vous terminez l’authentification à partir de /mcp et que la connexion échoue toujours avec un code de statut HTTP ou un code d’erreur de transport, Claude Code ajoute ce code et l’origine de l’URL du serveur au message qu’il imprime après la tentative. L’origine est le schéma et l’hôte, plus le port lorsque l’URL en nomme un, tel que https://mcp.example.com.

Le chemin et la chaîne de requête n’apparaissent jamais dans ce message.
Pour un serveur dans la portée locale, projet ou utilisateur, ou dans la configuration MCP gérée, l’origine affiche l’hôte tel qu’écrit dans cette configuration, donc une référence ${VAR} dans l’hôte n’est pas développée dans le message.
Pour un échec sans code de statut ou d’erreur, Claude Code affiche le texte d’erreur sans l’origine.

Un serveur distant dont la configuration a une url vide s’affiche comme not configured dans /mcp, dans claude mcp list, et dans le gestionnaire /plugin, et Claude Code ne tente pas de s’y connecter. Un plugin peut inclure une entrée d’espace réservé comme celle-ci pour un connecteur que vous configurez plus tard, afin que Claude Code ne le signale pas comme une erreur ou un problème de configuration. La vue détaillée du serveur dans /mcp indique No URL configured for this server ; définissez la url de l’entrée pour la connecter.

Avertissements de configuration

Claude Code avertit des problèmes de configuration ci-dessous. Chaque entrée indique ce que Claude Code vérifie et comment effacer l’avertissement :

Espaces blancs cachés : Claude Code avertit lorsqu’une valeur de configuration MCP porte des espaces blancs cachés en début ou en fin, ce qui provient souvent du collage d’un jeton avec une nouvelle ligne de fin. Claude Code vérifie command, url, chaque entrée args, et les valeurs et noms de clés sous env et headers. Claude Code affiche l’avertissement dans la sortie de claude mcp list et dans /mcp, en nommant les champs affectés sans répéter leurs valeurs, par exemple Leading or trailing whitespace in: headers.Authorization. Claude Code ne supprime pas les espaces blancs et utilise les valeurs exactement telles qu’écrites, donc modifiez la configuration pour les supprimer.
Même nom dans plus d’une portée : si vous définissez le même nom de serveur dans plus d’une portée avec des endpoints différents, Claude Code avertit du conflit dans la sortie de claude mcp list et dans /mcp. Claude Code stocke les connexions OAuth par endpoint, donc lorsque vous authentifiez la définition qui se charge dans un projet, vous devez toujours vous connecter séparément dans un projet où une définition différente se charge. Conservez l’endpoint que vous voulez et supprimez les autres avec claude mcp remove <name> --scope <scope>. Dans l’avertissement, Claude Code cite l’endpoint de chaque portée tel qu’écrit dans votre configuration, avec les références ${VAR} non développées, donc il n’affiche jamais une valeur résolue telle qu’une clé API.
Noms réservés : Claude Code réserve les noms de ses serveurs intégrés, y compris workspace, claude-in-chrome, computer-use, Claude Preview, et Claude Browser. Si votre configuration définit un serveur avec un nom réservé, Claude Code l’ignore au moment du chargement et affiche un avertissement vous demandant de le renommer. claude mcp add rejette un nom réservé avec une erreur. Claude Preview et Claude Browser nomment tous deux le serveur intégré que le volet d’aperçu de l’application de bureau Claude Code utilise.
Variable d’environnement manquante : si une référence ${VAR} dans la configuration d’un serveur nomme une variable qui n’est pas définie et n’a pas de :-default, Claude Code avertit dans la sortie de claude mcp list et dans /mcp, en nommant la variable, et charge toujours le serveur avec le texte ${VAR} non développé. Définissez la variable ou ajoutez une valeur de secours ${VAR:-default}. Dans l’url et les headers d’un serveur distant, certaines variables d’identifiants sont lues comme vides à la place, sans avertissement.

Disponibilité des outils

Le panneau /mcp affiche le nombre d’outils à côté de chaque serveur connecté et signale les serveurs qui annoncent la capacité des outils mais n’exposent aucun outil. Si votre demande a besoin d’outils d’un serveur qui se connecte toujours en arrière-plan, Claude attend ce serveur avant de continuer. La façon dont l’attente se produit dépend de votre configuration :

Avec la recherche d’outils, la valeur par défaut : l’attente se produit à l’intérieur de l’appel ToolSearch.
Sans recherche d’outils : Claude utilise plutôt l’outil WaitForMcpServers. Les configurations sans recherche d’outils incluent ENABLE_TOOL_SEARCH=false et un modèle antérieur à Claude Opus 4.5, Claude Sonnet 4.5 et Claude Haiku 4.5 sur la plateforme Agent de Google Cloud. Pour une passerelle ANTHROPIC_BASE_URL, voir Recherche d’outils via une passerelle LLM.
Sur un déploiement Microsoft Foundry hébergé sur Azure : Claude commence sur le chemin de recherche d’outils plutôt qu’avec WaitForMcpServers, car Claude Code découvre le rejet côté serveur du déploiement uniquement à partir de l’API. Après que Claude Code a basculé ce déploiement vers le chargement en amont, les outils d’un serveur qui termine de se connecter deviennent disponibles à la requête suivante de Claude.

Avec la recherche d’outils activée, lorsqu’un serveur termine de se connecter pendant que Claude travaille, Claude Code liste les noms d’outils du serveur à Claude lors de sa requête suivante dans le même tour. Claude peut alors rechercher et appeler ces outils sans attendre votre message suivant. Après la reprise d’une session, Claude peut appeler un outil issu de la conversation enregistrée alors que le serveur MCP de cet outil est toujours en cours de connexion. Pendant la première tentative de connexion du serveur, Claude Code retient l’appel jusqu’à 10 secondes et l’exécute dès que l’outil est disponible. Si le serveur ne se connecte pas à temps, ou s’il est déjà en train de réessayer après une tentative échouée, l’appel échoue avec l’erreur d’outil No such tool available.

Désactiver un serveur sans le supprimer

Désactivez un serveur dans le panneau /mcp pour empêcher Claude Code de s’y connecter sans perdre sa configuration. Claude Code liste toujours le serveur dans /mcp, marqué comme désactivé. Lorsque vous basculez un serveur, Claude Code enregistre votre choix par projet dans ~/.claude.json, dans l’une de deux listes qui couvrent des ensembles disjoints de serveurs :

disabledMcpServers : une liste d’exclusion pour les serveurs configurés par l’utilisateur, les serveurs de plugins, les serveurs que votre organisation fournit via les paramètres gérés, les connecteurs claude.ai que Claude Code récupère lui-même, et les serveurs intégrés qui sont activés par défaut. Claude Code ne se connecte pas à un serveur que vous listez ici. Lorsque vous désactivez un connecteur claude.ai avec le basculement /mcp par projet décrit dans Désactiver les connecteurs claude.ai, Claude Code l’écrit dans cette liste sous son nom d’affichage, par exemple claude.ai Slack.
enabledMcpServers : une liste d’inclusion pour les serveurs intégrés qui sont désactivés par défaut, tels que computer-use. Claude Code se connecte à un serveur désactivé par défaut uniquement lorsque vous le listez ici.

Claude Code consulte exactement l’une des deux listes pour chaque serveur, donc aucune des deux listes ne remplace l’autre. Si vous ajoutez un serveur ordinaire à enabledMcpServers, ou un serveur intégré désactivé par défaut à disabledMcpServers, Claude Code ignore l’entrée. disabledMcpServers et enabledMcpServers ne sont pas liés à enabledMcpjsonServers et disabledMcpjsonServers, qui contrôlent l’approbation des serveurs définis dans le fichier .mcp.json d’un projet.

Runtimes clients MCP

Claude Code se connecte aux serveurs MCP via l’un de deux runtimes clients. Le runtime v1 s’appuie sur MCP TypeScript SDK 1.x. Le runtime v2 est le même code sur MCP TypeScript SDK 2.0, qui ajoute la révision de protocole MCP 2026-07-28. Le reste de cette page s’applique aux deux runtimes, sauf si une section nomme le runtime v2. Claude Code choisit un runtime chaque fois que vous le démarrez et le conserve jusqu’à ce que vous quittiez. Dans les sessions où il récupère les feature flags, il utilise le runtime v2 sur Claude Code v2.1.232 ou ultérieur. Dans les sessions où il ne récupère pas les feature flags, Claude Code utilise le runtime v2 par défaut sur Claude Code v2.1.274 ou ultérieur :

Sessions sur Amazon Bedrock, Claude Platform sur AWS, la plateforme Agent de Google Cloud, ou Microsoft Foundry, sauf si une plateforme hôte qui intègre Claude Code définit CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST
Sessions connectées via une passerelle d’applications Claude
Sessions où vous désactivez la télémétrie ou la récupération des feature flags, par exemple avec DISABLE_TELEMETRY

Sur v2, Claude Code également :

Demande aux serveurs HTTP, stdio et de connecteurs claude.ai s’ils supportent la révision plus récente, et l’utilise avec ceux qui la supportent. Cela inclut les connecteurs des sessions cloud et Remote Control. Claude Code se connecte à tous les autres serveurs comme le fait v1.
Reçoit les notifications list_changed des serveurs sur la révision plus récente via un flux qu’il maintient ouvert.
N’enregistre pas un serveur de canal qui se connecte sur la révision plus récente, car cette révision ne peut pas transporter les messages de canal.
Fait échouer une connexion OAuth MCP dont la réponse d’autorisation nomme un émetteur inattendu.
Envoie les identifiants OAuth MCP uniquement à un endpoint de jeton servi via HTTPS ou à localhost, 127.0.0.1, ou ::1. La connexion échoue pour un serveur dont l’endpoint de jeton est en http:// simple n’importe où ailleurs, tel qu’un appareil sur votre réseau local. Voir Refusing to send credentials to non-https token endpoint.

Anthropic peut maintenir un serveur spécifique sur le protocole antérieur, ou hors de ce flux, avec un feature flag que Claude Code récupère. Pour choisir le runtime vous-même, définissez MCP_SDK_GENERATION à v1 ou v2. Pour décider si Claude Code pose la question, définissez MCP_PROTOCOL_NEGOTIATION à auto ou legacy.

Mises à jour dynamiques des outils

Un serveur MCP peut modifier les outils, prompts ou ressources qu’il propose pendant qu’il est connecté et envoyer une notification list_changed. Lorsqu’une telle notification arrive :

Dans une session de terminal interactive, Claude Code récupère la liste mise à jour auprès de ce serveur, vous n’avez donc pas besoin de le reconnecter.
En mode non interactif avec le flag -p et dans l’Agent SDK, Claude Code actualise uniquement la liste des outils lors de ces notifications.

Si une requête d’actualisation échoue, Claude Code conserve les outils, prompts et ressources précédemment découverts du serveur jusqu’à ce qu’une actualisation ultérieure réussisse.

Flux de notification sur le runtime v2

Sur le runtime v2, Claude Code reçoit les notifications list_changed d’un serveur sur la révision de protocole plus récente via un flux qu’il maintient ouvert. Lorsque le flux se ferme, Claude Code le rouvre, avec deux limites :

Le flux se ferme à nouveau dans les 10 secondes : Claude Code le rouvre jusqu’à trois fois, puis s’arrête pour cette connexion.
Le flux reste ouvert plus de 10 secondes, puis se ferme, comme le font couramment les flux vers des hôtes serverless : après cinq réouvertures en une heure, Claude Code attend environ six heures avant la suivante.

Jusqu’à ce que le flux se rouvre, vous conservez les derniers outils, prompts et ressources récupérés du serveur. Pour récupérer ses modifications plus tôt, reconnectez le serveur à partir de /mcp.

Reconnexion automatique

Claude Code reconnecte un serveur distant qui se déconnecte en cours de session et réessaie la première connexion d’un serveur HTTP ou SSE après une erreur transitoire. Pour un serveur stdio, voir Serveurs stdio qui se terminent ou ne démarrent pas.

Déconnexions en cours de session d’un serveur distant

Claude Code tente d’abord de reconnecter un serveur distant déconnecté jusqu’à cinq fois avec un backoff exponentiel, en commençant par un délai d’une seconde et en le doublant à chaque fois :

Dans une session interactive : /mcp affiche le serveur comme en attente pendant que Claude Code se reconnecte. Après cinq tentatives échouées, Claude Code marque le serveur comme défaillant, ou comme nécessitant une authentification lorsque le serveur doit être autorisé à nouveau. Lorsqu’il marque le serveur comme défaillant, vous voyez une notification MCP server "<name>" disconnected · open /mcp to reconnect. Vous pouvez réessayer manuellement à partir de /mcp.
Dans les exécutions claude -p et les sessions Agent SDK : Claude Code effectue les mêmes cinq tentatives, sans panneau /mcp pour les afficher. Si les cinq échouent, l’exécution se poursuit sans les outils du serveur :
- Après une erreur transitoire, telle qu’une réponse 5xx ou un délai d’expiration : Claude Code continue de réessayer de connecter un serveur HTTP ou SSE en arrière-plan. Les nouvelles tentatives durent jusqu’à environ une demi-heure, et les outils du serveur redeviennent disponibles lorsque l’une d’elles parvient à se connecter. D’ici là, une session Agent SDK signale le statut failed, et votre code peut reconnecter le serveur. Pour le reconnecter dans claude -p, relancez l’exécution.
- Lorsque le serveur nécessite que vous vous reconnectiez : Claude Code cesse de réessayer, et une session Agent SDK signale le statut du serveur comme needs-auth. Connectez-vous avec claude mcp login <name> dans votre shell. Ensuite, relancez l’exécution ou, dans une session Agent SDK, reconnectez le serveur à la place.

Échecs de première connexion

Lorsque la première connexion d’un serveur HTTP ou SSE échoue avec une erreur transitoire, telle qu’une réponse 5xx, une connexion refusée, ou un délai d’expiration, Claude Code réessaie jusqu’à trois fois. Si la connexion échoue toujours, Claude Code marque le serveur comme défaillant. Ces nouvelles tentatives ne s’appliquent pas dans ces cas :

La première connexion d’un serveur stdio. Pour la réessayer, voir Serveurs stdio qui se terminent ou ne démarrent pas
La première connexion d’un serveur WebSocket. Pour la retenter dans une session de terminal interactive, sélectionnez Reconnect dans le menu du serveur dans /mcp
Une erreur d’authentification ou de ressource introuvable, car elle nécessite une modification de configuration pour être résolue. Lorsqu’un headersHelper est la seule source de l’en-tête Authorization du serveur, Claude Code réessaie quand même après une erreur d’authentification, car il réexécute le helper à chaque tentative et peut récupérer des identifiants frais

Serveurs stdio qui se terminent ou ne démarrent pas

Pour redémarrer un serveur stdio, lisez la colonne qui correspond à ce qui lui est arrivé. Trouvez votre ligne selon la façon dont vous exécutez Claude Code : une session interactive, une exécution claude -p, ou une session Agent SDK.

Comment vous exécutez Claude Code	Le processus du serveur se termine en cours de session	La première connexion du serveur échoue
Session interactive	Claude Code marque le serveur comme défaillant. Pour le redémarrer, sélectionnez Reconnect dans le menu du serveur dans `/mcp`	Claude Code marque le serveur comme défaillant. Pour le redémarrer, sélectionnez Reconnect dans le menu du serveur dans `/mcp`
Exécution `claude -p`	Claude Code redémarre le serveur la prochaine fois que Claude appelle l’un des outils du serveur, et l’appel s’exécute dès que le serveur se connecte	L’exécution se poursuit sans les outils du serveur. Pour que Claude Code réessaie la connexion, relancez l’exécution. Lorsqu’un plugin fournit le serveur, les nouvelles exécutions ignorent la connexion pendant 15 minutes après un échec ; attendez donc ce délai d’abord ou réessayez plus tôt
Session Agent SDK	Claude Code redémarre le serveur la prochaine fois que Claude appelle l’un des outils du serveur, et l’appel s’exécute dès que le serveur se connecte	La session se poursuit sans les outils du serveur. Votre code peut reconnecter le serveur

Requêtes de découverte échouées

Après qu’un serveur s’est connecté, Claude Code lui envoie des requêtes de découverte de capacités telles que tools/list, prompts/list, et resources/list. Claude Code réessaie ces requêtes jusqu’à trois fois avec un backoff court après une erreur réseau ou serveur transitoire. Il ne réessaie pas après les erreurs d’authentification, les réponses 4xx, ou les expirations de requête.

Réessayer vous-même les serveurs en échec

Pour réessayer tous les serveurs en échec ou nécessitant une authentification, exécutez /mcp reconnect all à l’invite de Claude Code dans une session de terminal interactive. Cela nécessite Claude Code v2.1.284 ou une version ultérieure. Les versions antérieures affichent MCP server "all" not found.

Comment Claude apprend qu’un serveur a échoué

Le fait que Claude Code indique à Claude qu’un serveur configuré n’a pas pu se connecter dépend de la recherche d’outils, qui est activée par défaut :

Avec la recherche d’outils, Claude Code indique à Claude quel serveur a échoué et son erreur de connexion, donc Claude signale l’échec de la connexion dans sa réponse. Claude Code inclut les mêmes informations dans les résultats ToolSearch qui ne trouvent aucun outil correspondant.
Dans toute configuration sans recherche d’outils, Claude Code ne signale pas les échecs de connexion des serveurs à Claude.

Pousser des messages avec des canaux

Un serveur MCP peut également pousser des messages directement dans votre session afin que Claude puisse réagir à des événements externes comme les résultats CI, les alertes de surveillance, ou les messages de chat. Pour activer cela, votre serveur déclare la capacité claude/channel et vous l’activez avec le flag --channels au démarrage. Voir Canaux pour utiliser un canal officiellement supporté, ou Référence des canaux pour créer le vôtre. Sur le runtime v2, un serveur de canal qui négocie la révision de protocole MCP 2026-07-28 ne peut pas livrer les messages de canal, donc Claude Code ne l’enregistre pas comme un canal. Un serveur de canal qui ne supporte pas cette révision se connecte avec la poignée de main antérieure et s’enregistre comme auparavant. Claude Code demande cette révision aux serveurs stdio par défaut. Pour maintenir un serveur de canal stdio sur la poignée de main antérieure, définissez MCP_PROTOCOL_NEGOTIATION à legacy, ce qui y maintient tous les serveurs.

Conseils :

Utilisez le flag -s ou --scope pour spécifier où la configuration est stockée :
- local (par défaut) : disponible uniquement pour vous dans le projet actuel
- project : partagé avec tout le monde dans le projet via le fichier .mcp.json
- user : disponible pour vous dans tous les projets
Définissez les variables d’environnement avec les flags -e ou --env (par exemple, -e KEY=value)
Les flags --transport et --header acceptent également les formes courtes -t et -H
Configurez le délai d’expiration de démarrage du serveur MCP en utilisant la variable d’environnement MCP_TIMEOUT (par exemple, MCP_TIMEOUT=10000 claude définit un délai d’expiration de 10 secondes)
Définissez un délai d’expiration d’exécution d’outil par serveur en ajoutant un champ timeout en millisecondes à l’entrée .mcp.json de ce serveur, par exemple "timeout": 600000 pour dix minutes. Cela remplace la variable d’environnement MCP_TOOL_TIMEOUT pour ce serveur uniquement
Claude Code affiche un avertissement lorsque la sortie de l’outil MCP dépasse 10 000 tokens et limite la sortie à 25 000 tokens par défaut. Pour modifier la limite de tokens, définissez la variable d’environnement MAX_MCP_OUTPUT_TOKENS, par exemple MAX_MCP_OUTPUT_TOKENS=50000. Le seuil d’avertissement est fixe. Sauf si le serveur augmente la limite propre d’un outil, les résultats textuels réussis de plus de 50 000 caractères sont enregistrés dans un fichier, quelle que soit la valeur de cette variable. Voir Limites et avertissements de sortie MCP
Utilisez /mcp pour vous authentifier auprès des serveurs distants qui nécessitent une authentification OAuth 2.0

Limites de temps des appels d’outils MCP

Pour limiter la durée d’exécution d’un appel d’outil MCP :

Par serveur : ajoutez un champ timeout en millisecondes à l’entrée de configuration de ce serveur
Pour l’ensemble des serveurs : définissez MCP_TOOL_TIMEOUT

Le timeout par serveur est une limite stricte en temps réel par appel d’outil, et les notifications de progression du serveur ne la prolongent pas. Les valeurs inférieures à 1000 sont ignorées et se rabattent sur MCP_TOOL_TIMEOUT, ou sur sa valeur par défaut d’environ 28 heures lorsque cette variable n’est pas définie. Pour un serveur HTTP, SSE, ou de connecteur claude.ai, il existe également un second minuteur, par requête, qui couvre chaque requête jusqu’au premier octet de réponse du serveur. Claude Code définit ce minuteur à la plus grande de trois valeurs : 60 secondes, le délai d’expiration d’outil qui s’applique au serveur, et MCP_TIMEOUT. La valeur par défaut de 28 heures d’un MCP_TOOL_TIMEOUT non défini n’entre pas dans cette comparaison, et une valeur inférieure à 60 secondes ne raccourcit pas le minuteur. Les serveurs stdio et WebSocket n’ont pas de minuteur par requête. Un timeout par serveur d’au moins 1000 agit également comme un plancher pour le délai d’inactivité décrit ci-dessous : Claude Code n’abandonne jamais les appels d’outils de ce serveur pour inactivité plus tôt que le timeout par serveur. Un appel d’outil à un serveur MCP qui n’envoie aucune réponse et aucune notification de progression pendant la fenêtre d’inactivité est abandonné avec une erreur au lieu d’attendre la limite en temps réel. Le délai d’inactivité s’applique à tous les types de serveurs sauf les serveurs IDE et les serveurs en processus du SDK. La fenêtre d’inactivité par défaut est de cinq minutes pour les serveurs HTTP, SSE, WebSocket, et de connecteur claude.ai, et de 30 minutes pour les serveurs stdio. Définissez la variable d’environnement CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT en millisecondes pour changer la fenêtre d’inactivité, ou définissez-la à 0 pour désactiver la vérification. Ces délais d’expiration limitent la durée pendant laquelle un appel peut s’exécuter, pas toujours la durée pendant laquelle il bloque la session : un appel de la conversation principale qui s’exécute au-delà de deux minutes passe d’abord dans une tâche en arrière-plan. Voir Mise en arrière-plan automatique des appels d’outils longs.

Mise en arrière-plan automatique des appels d’outils longs

Si la vue détaillée d’un appel en arrière-plan dans /tasks affiche runs on the server; survives exiting this session, consultez Tâches MCP exécutées sur le serveur. Un appel d’outil MCP dans la conversation principale qui s’exécute toujours après deux minutes passe dans une tâche en arrière-plan au lieu de bloquer la session. Claude reçoit immédiatement l’ID de la tâche et continue de travailler, et le résultat arrive sous forme de notification de tâche lorsque l’appel se termine. La tâche apparaît dans /tasks, où vous pouvez également l’arrêter, et elle ne survit pas à la sortie de la session. L’entrée de la tâche affiche la dernière progression que le serveur a signalée. Si vous arrêtez la tâche, Claude Code annule l’appel et indique à Claude qu’aucun résultat n’arrivera. L’arrêt ne garantit pas que le serveur s’arrête : il a peut-être déjà effectué une partie du travail, ou peut encore le terminer. Les limites par appel s’appliquent toujours pendant que l’appel s’exécute en arrière-plan : la limite en temps réel définie par le timeout par serveur ou MCP_TOOL_TIMEOUT, et le délai d’inactivité défini par CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT. Pour modifier ou désactiver la mise en arrière-plan automatique :

Définissez la variable d’environnement CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS en millisecondes pour modifier le seuil, ou définissez-la sur 0 pour désactiver la mise en arrière-plan automatique. Avec 0, Claude attend également les tâches MCP dans une session interactive
Définissez CLAUDE_CODE_DISABLE_BACKGROUND_TASKS sur 1 pour désactiver la mise en arrière-plan automatique et les commandes en arrière-plan

Certains appels ne passent jamais en arrière-plan :

Les appels provenant de sous-agents ; Claude Code met en arrière-plan uniquement les appels de la conversation principale
Les appels aux serveurs IDE
Les appels en mode non interactif, sauf si CLAUDE_AUTO_BACKGROUND_TASKS est défini à 1, car une exécution ponctuelle peut se terminer avant l’arrivée du résultat

Un appel en attente d’une boîte de dialogue d’élicitation ouverte n’est pas mis en arrière-plan tant que la boîte de dialogue est ouverte ; le serveur est bloqué en attente de votre saisie, il n’est pas lent, donc Claude Code diffère le passage en arrière-plan jusqu’à la fermeture de la boîte de dialogue.

Tâches MCP exécutées sur le serveur

Une tâche MCP est un travail de longue durée, tel qu’un export de rapport ou un build, qu’un serveur MCP exécute lui-même à l’aide de l’extension MCP tasks. L’appel d’outil de Claude se termine dès que le serveur accepte le travail, de sorte que Claude continue de travailler, sauf si vous faites attendre Claude. Lorsque le travail se termine, la transcription l’indique et Claude reçoit le résultat. Demandez-le à Claude. Entre-temps, le pied de page affiche un décompte tel que 1 MCP task, et Claude Code suit la tâche en vérifiant son statut auprès du serveur. Une tâche sur un serveur distant continue de s’exécuter après que vous avez quitté. Pour la suivre à nouveau, reprenez la même session.

Les tâches MCP sont en bêta publique dans la CLI Claude Code et nécessitent Claude Code v2.1.304 ou une version ultérieure. Ce dont un appel a besoin pour devenir une tâche MCP liste les sessions et les serveurs qui en bénéficient.

Arrêter une tâche MCP ou obtenir son résultat

Pour arrêter une tâche en cours, sélectionnez-la dans /tasks et appuyez sur x, ou demandez-le à Claude. Claude Code cesse de suivre la tâche et demande au serveur de l’annuler, bien que le serveur puisse encore la terminer. Reconnectez d’abord un serveur déconnecté depuis /mcp, sinon aucune requête d’annulation n’est envoyée et Claude Code oublie la tâche et ne peut plus la suivre. Appuyer sur Esc n’arrête pas une tâche en arrière-plan. Lorsque la tâche se termine, une ligne comme celle-ci apparaît dans la transcription :

MCP task <server task id> (<server>/<tool>) completed.

Le résultat est transmis à Claude, et non à la transcription ; demandez-le donc à Claude. Si Claude est inactif lorsque le résultat arrive, Claude s’en occupe sans sollicitation.

Répondre à une question d’une tâche MCP

Une tâche en cours peut ouvrir une boîte de dialogue d’élicitation pour vous demander une saisie. Tant que /tasks est ouvert, la boîte de dialogue reste masquée ; fermez donc /tasks pour répondre. Refuser ou appuyer sur Esc constitue une réponse au serveur, qui décide alors si la tâche se poursuit. Dans une session non interactive, Claude Code demande au serveur d’annuler une tâche qui demande une saisie, sans exécuter vos hooks Elicitation ni appeler le callback onElicitation de l’Agent SDK.

Quitter, effacer ou reprendre pendant l’exécution d’une tâche MCP

Une tâche sur un serveur distant continue de s’exécuter après que vous avez quitté. Le processus d’un serveur stdio s’arrête lorsque Claude Code se ferme, bien que ses tâches affichent runs on the server; survives exiting this session dans /tasks. Sauf si la documentation de ce serveur indique que le travail survit au processus, laissez d’abord ces tâches se terminer ou arrêtez-les dans /tasks.

Situation	Ce qu’il advient de la tâche	Ce que vous pouvez faire
Vous exécutez `/clear` ou `/branch`, ou `/resume` une autre session	Tant que Claude Code reste ouvert, le résultat arrive dans votre conversation actuelle	Après avoir quitté, exécutez `claude --resume` sur la session dans laquelle la tâche a démarré
Vous quittez Claude Code	Aucune option de sortie n’annule la tâche d’un serveur distant, même lorsque la boîte de dialogue de sortie la liste sous `The following will stop when you exit:`	Arrêtez-la d’abord dans `/tasks`, ou reprenez la même session plus tard
Vous revenez à la session de la tâche en mode interactif : `claude --resume`, `claude --continue` ou `/resume`	Une fois le serveur connecté, Claude Code suit à nouveau la tâche, et Claude reçoit le résultat si elle s’est terminée entre-temps et que le serveur la connaît encore	Conservez le nom du serveur et ses paramètres de connexion inchangés
Vous reprenez la session de la tâche avec `--resume` ou `--continue` dans une exécution ponctuelle `claude -p "<prompt>"`	Cette exécution ne suit pas la tâche	Reprenez en mode interactif, ou avec `--input-format stream-json`
Vous démarrez une nouvelle session ou utilisez `--fork-session`	La nouvelle session ne suit pas la tâche	Reprenez la session qui l’a démarrée

Ce dont un appel a besoin pour devenir une tâche MCP

Un appel d’outil ne devient une tâche MCP que lorsque toutes ces conditions sont réunies :

Le serveur prend en charge les tâches
Le serveur est un serveur HTTP, stdio ou connecteur claude.ai connecté avec la révision de protocole 2026-07-28. Définir MCP_SDK_GENERATION=v1 ou MCP_PROTOCOL_NEGOTIATION=legacy l’exclut
La session récupère les feature flags, donc pas sur un fournisseur tiers tel qu’Amazon Bedrock, ni avec la télémétrie ou la récupération des flags désactivée
Anthropic a activé les tâches MCP pour votre type de session. Sur v2.1.304 ou une version ultérieure, cela couvre les sessions CLI dans le terminal, les sessions Agent SDK et les exécutions GitHub Actions. Les autres surfaces, telles que l’extension VS Code et l’application de bureau, ne disposent pas des tâches MCP
L’appel provient de la conversation principale, et non d’un sous-agent
Soit la session est interactive, soit une session Agent SDK ou une exécution claude -p lisant --input-format stream-json a :
- CLAUDE_AUTO_BACKGROUND_TASKS à 1
- CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND différent de 1
- CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS différent de 0

Tout autre appel est un appel d’outil ordinaire, et Mise en arrière-plan automatique des appels d’outils longs indique lesquels passent en arrière-plan. Gardez l’entrée d’une session Agent SDK ou stream-json ouverte, car l’exécution n’attend pas les tâches MCP une fois l’entrée fermée. Une exécution ponctuelle claude -p "<prompt>" ne bénéficie pas des tâches MCP.

Messages de statut d’une tâche MCP

Ces messages, dans l’entrée /tasks d’une tâche ou dans sa ligne de transcription finale, signifient que Claude Code ne peut pas joindre le serveur ou la tâche. Tant que l’un d’eux s’affiche dans /tasks, le travail est peut-être toujours en cours : Claude Code le laisse tranquille et continue de vérifier. Les messages 300s et de configuration restent sur l’entrée même après le rétablissement du contact.

Message	Ce qui se passe	Ce que vous pouvez faire
`reconnecting…`	Le serveur n’a pas répondu depuis une reprise, ou les vérifications de statut restent sans réponse	S’il persiste, reconnectez depuis `/mcp`
`needs a sign-in to <server>`	Le serveur a refusé une vérification de statut	Connectez-vous depuis `/mcp`
`status requests come back with errors; retrying…`	Le serveur, ou un proxy placé devant lui, répond aux vérifications de statut par des erreurs	Patientez pendant que Claude Code réessaie
`server '<name>' did not reconnect within 300s`	Aucune vérification n’a obtenu de réponse pendant cinq minutes, par exemple parce que la connexion est coupée ou le serveur désactivé	Reconnectez depuis `/mcp`
`server '<name>' asked for a sign-in, and none was accepted within 300s`	Après cinq minutes, le serveur demande toujours une connexion	Connectez-vous depuis `/mcp`
`status requests to server '<name>' came back with errors, and none succeeded in 300s`	Cinq minutes de réponses d’erreur	Vérifiez l’état de santé ou les logs du serveur lui-même
`server '<name>' is not configured in this session; the task may still be running on it`	La session n’a aucun serveur de ce nom, par exemple parce qu’il a été supprimé, renommé ou omis de `--mcp-config`, ou qu’un connecteur claude.ai est encore en cours de chargement	Restaurez le serveur sous le même nom, puis reprenez à nouveau la session. Pour un connecteur en cours de chargement, rien : Claude Code suit la tâche dès qu’il apparaît
Un message commençant par `server '<name>' was reconfigured to a different transport since this task was created`	Un serveur de ce nom existe, mais ses paramètres de connexion ont changé depuis le démarrage de la tâche, tels que son URL, sa commande, ses args, son env, ses en-têtes ou son délai d’expiration	Restaurez les paramètres précédents, puis reprenez à nouveau la session
`the server rejected this task's id; asking again…`	Le serveur indique qu’il ne connaît pas l’ID de la tâche. Claude Code continue de demander pendant jusqu’à cinq minutes	Patientez : le message disparaît si le serveur reconnaît à nouveau l’ID, sinon la ligne `outcome unknown.` suit
Une ligne de transcription se terminant par `outcome unknown.`, sous une forme `expired on the server: outcome unknown.`	Le serveur a rejeté l’ID ou a refusé avec une autre erreur permanente, et Claude Code a cessé de suivre la tâche	Un second appel peut répéter le travail. Avant d’appeler à nouveau l’outil, vérifiez auprès du serveur ce qui a été fait, par exemple en demandant à Claude d’utiliser les autres outils du serveur

Limites de temps des tâches MCP

Par défaut, une tâche en arrière-plan n’a aucune limite de temps imposée par Claude Code. Les limites de temps des appels d’outils, y compris la limite en temps réel et le délai d’inactivité, s’appliquent jusqu’à ce que le serveur réponde à l’appel avec la tâche. Si vous faites attendre Claude, elles s’appliquent pendant toute la durée de la tâche. Les vérifications de statut ayant obtenu une réponse comptent comme une activité pour le délai d’inactivité.

Faire attendre Claude le résultat d’une tâche MCP

Pour que Claude attende le résultat d’une tâche dans une session interactive, définissez l’une de deux variables d’environnement, par exemple dans le bloc env de settings.json :

CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS défini sur 0 : Claude attend chaque appel d’outil MCP jusqu’à sa fin
CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND défini sur 1 : Claude attend le résultat d’une tâche. Tant que la mise en arrière-plan automatique est activée, elle déplace l’appel après deux minutes par défaut, de sorte que les tâches courtes se terminent sur place et que les longues ne vous bloquent pas. L’appel déplacé est un appel en arrière-plan ordinaire plutôt qu’une tâche MCP. Il ne survit pas à la fermeture de la session

Pendant que Claude attend, appuyer sur Esc ou atteindre la limite en temps réel ou le délai d’inactivité met fin à l’appel, et Claude Code demande au serveur d’annuler la tâche. Si vous définissez CLAUDE_CODE_DISABLE_BACKGROUND_TASKS sur 1 ou démarrez en mode bare, cela seul ne fait pas attendre Claude pour les tâches MCP. Cet exemple définit CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS sur 0, de sorte que Claude attend chaque appel d’outil MCP :

settings.json

{
  "env": {
    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "0"
  }
}

Tâches MCP pour les auteurs de serveurs

Si vous développez un serveur MCP, vous pouvez répondre à un tools/call de longue durée avec une tâche. L’extension MCP tasks définit les messages que vous envoyez. Sur une connexion utilisant la révision de protocole 2026-07-28, chaque requête transporte les capacités client de Claude Code à params._meta["io.modelcontextprotocol/clientCapabilities"], avec "io.modelcontextprotocol/tasks": {} sous extensions. Une requête tools/call qui ne peut pas devenir une tâche omet cette extension.

Répondre à l’appel avec une tâche

Ne répondez avec une tâche que lorsque la requête transporte l’extension, sinon Claude reçoit l’erreur d’outil Unsupported result type 'task' for tools/call. Claude reçoit la même erreur lorsque taskId, status, createdAt, lastUpdatedAt ou ttlMs est manquant. L’objet tâche est le result JSON-RPC de votre réponse tools/call, ne nécessite pas de tableau content et inclut ici les champs facultatifs statusMessage et pollIntervalMs :

{
  "resultType": "task",
  "taskId": "build-7f3a9c2e",
  "status": "working",
  "statusMessage": "Compiling, 40 of 212 files done",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:03:07Z",
  "ttlMs": null,
  "pollIntervalMs": 5000
}

Champ	Comment Claude Code le traite
`resultType`	Définissez-le sur `"task"` pour marquer la réponse comme une tâche. Sans lui, Claude Code lit la réponse comme un résultat ordinaire
`taskId`	Obligatoire. Au maximum 128 caractères ASCII imprimables sans espaces, sinon Claude reçoit une erreur d’outil commençant par `MCP server "<name>" returned a malformed task handle for tool "<tool>"`. Veillez à ce que l’ID puisse obtenir une réponse d’une connexion à l’autre, car après une reprise, Claude Code l’interroge sur une nouvelle connexion
`status`	Obligatoire. L’une des valeurs `working`, `input_required`, `completed`, `failed` ou `cancelled`. Une autre valeur provoque l’erreur `Unsupported result type`
`createdAt`, `lastUpdatedAt`, `ttlMs`	Obligatoires, et `ttlMs` peut être `null`. Claude Code n’abandonne pas une tâche parce que son `ttlMs` est dépassé
`pollIntervalMs`	Facultatif, mais pas `null`. Nombre de millisecondes entre les requêtes `tasks/get`, borné entre 250 et 30000. Claude Code utilise 2000 lorsque le champ est absent, et relit la valeur dans chaque réponse `tasks/get`
`statusMessage`	Facultatif. `/tasks` affiche la valeur de votre dernière réponse `tasks/get`, et non de cette première réponse, et une réponse qui omet le champ l’efface. Un message de statut de Claude Code peut le remplacer

Sur un serveur HTTP ou connecteur claude.ai, la réponse de tâche doit commencer dans le délai du minuteur par requête ; acceptez donc le travail et répondez d’abord, puis effectuez le travail.

Signaler le statut, les résultats et les questions

Juste après la réponse de tâche, Claude Code envoie tasks/get avec { "taskId": ... }, puis le répète une fois par intervalle d’interrogation. L’extension tasks exige que votre réponse contienne "resultType": "complete" ainsi que taskId, status, createdAt, lastUpdatedAt et ttlMs. ttlMs peut être null, et statusMessage et pollIntervalMs sont facultatifs. Cet exemple signale que le build est terminé :

{
  "resultType": "complete",
  "taskId": "build-7f3a9c2e",
  "status": "completed",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:09:41Z",
  "ttlMs": null,
  "result": {
    "content": [{ "type": "text", "text": "Build succeeded: 212 files, 0 warnings" }]
  }
}

Statut, méthode ou réponse	Comment Claude Code le traite
`working`	Continue d’interroger
`completed`	Transmet à Claude le résultat `tools/call` normal contenu dans l’objet `result` de niveau supérieur. Un `isError: true` dans celui-ci est signalé comme un échec
`failed`	Transmet à Claude le `message` de l’objet `error` de niveau supérieur `{ code, message, data }`, que l’extension tasks exige pour une tâche en échec. Sans ce `message`, Claude reçoit plutôt `statusMessage`, ou à défaut `Task failed`
`cancelled`	Transmet à Claude `statusMessage`, ou à défaut `Task was cancelled by the server`
`input_required`	Lit `inputRequests`, un objet qui associe une clé de votre choix à `{ method, params }`. Claude Code répond une fois à chaque clé via `tasks/update` avec `{ taskId, inputResponses }`, où `inputResponses` associe la même clé au résultat de cette requête. Les clés au-delà de 16 par tâche sont ignorées
Méthodes dans `inputRequests`	`elicitation/create` n’est servie que dans les sessions de terminal interactives, et `roots/list` partout. Lorsque Claude Code ne peut pas servir une requête, il demande au serveur d’annuler la tâche
Une autre valeur de `status`	Claude Code demande au serveur d’annuler la tâche et la signale à Claude comme en échec
Erreur JSON-RPC `-32602`	Lue comme un ID de tâche inconnu. Pour une tâche en arrière-plan, Claude Code continue de demander pendant jusqu’à cinq minutes, puis signale le résultat à Claude comme inconnu
`tasks/cancel`	Envoyée, par exemple, lorsque Claude ou la personne arrête la tâche alors que le serveur est connecté. Non envoyée à la fermeture
`tasks/result`, `tasks/list`, `notifications/tasks`	Non utilisées ; placez donc le résultat dans vos réponses `tasks/get`

Serveurs MCP fournis par les plugins

Les plugins peuvent regrouper des serveurs MCP qui fournissent des outils et des intégrations lorsque vous activez le plugin. Comment fonctionnent les serveurs MCP des plugins :

Les plugins définissent les serveurs MCP dans .mcp.json à la racine du plugin ou en ligne dans plugin.json
Lorsque vous activez un plugin, Claude Code démarre automatiquement ses serveurs MCP
Claude Code propose les outils MCP des plugins aux côtés des outils MCP configurés manuellement
Vous ajoutez et supprimez les serveurs de plugins en installant ou en désinstallant le plugin, pas avec les commandes /mcp. Vous pouvez toujours désactiver un serveur de plugin installé dans /mcp, ce qui empêche Claude Code de s’y connecter sans supprimer le plugin

Exemple de configuration MCP de plugin : Dans .mcp.json à la racine du plugin :

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

Ou en ligne dans plugin.json :

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Fonctionnalités MCP des plugins :

Cycle de vie automatique : les serveurs se connectent et se déconnectent aux moments suivants :
- Au démarrage de la session, Claude Code connecte automatiquement les serveurs des plugins activés. Dans /mcp, un serveur de plugin distant (HTTP ou SSE) que vous avez utilisé auparavant peut afficher le statut cached à la place ; Claude Code le connecte lorsque Claude appelle pour la première fois l’un de ses outils. Lorsque la connexion d’un serveur de plugin stdio a échoué moins de 15 minutes auparavant, Claude Code ignore la connexion
- Si vous activez ou désactivez un plugin pendant une session, Claude Code connecte ou déconnecte ses serveurs MCP lorsque la modification s’applique. Appliquer les modifications de plugin sans redémarrer décrit quand c’est le cas. Dans une session sans terminal interactif, /reload-plugins ne connecte ni ne déconnecte les serveurs MCP des plugins ; ces modifications prennent effet dans votre session suivante
- Lorsque vous rechargez, Claude Code conserve les connexions actives des serveurs de plugins dont la configuration est inchangée, et fait de même lorsque vous remplacez la liste des serveurs MCP de la session à partir de l’Agent SDK sans les nommer
- Lorsque vous déplacez la session avec /cd sur v2.1.246 ou ultérieur, Claude Code connecte les serveurs des plugins que les paramètres du nouveau répertoire activent et déconnecte les serveurs des plugins qui ne sont plus activés, afin que vous n’ayez pas besoin d’exécuter /reload-plugins après le déplacement
- Dans les sessions cloud, un appel MCP à un serveur de plugin qui n’est pas encore connecté, par exemple juste après le réveil d’une session inactive, démarre le serveur à la demande et attend qu’il se connecte
Espaces réservés de chemin : ${CLAUDE_PLUGIN_ROOT} se résout au répertoire d’installation du plugin, ${CLAUDE_PLUGIN_DATA} à son répertoire d’état persistant, et ${CLAUDE_PROJECT_DIR} à la racine de projet stable. La substitution s’applique à :
- serveurs stdio : command, args, env
- serveurs http, sse, et ws : url, headers, et headersHelper
Accès à l’environnement utilisateur : accès aux mêmes variables d’environnement que les serveurs configurés manuellement
Types de transport multiples : support des transports stdio, SSE, HTTP, et WebSocket, bien que le support de transport puisse varier selon le serveur

Les serveurs de plugins apparaissent dans /mcp avec des indicateurs montrant qu’ils proviennent de plugins. claude mcp get masque les valeurs configurées pour le serveur stdio ou WebSocket d’un plugin, car elles peuvent contenir des identifiants :

Serveur stdio : il imprime Command: stdio, une ligne Args: vide, et chaque variable d’environnement sous la forme NAME=[REDACTED]
Serveur WebSocket : il imprime URL: ws et chaque en-tête sous la forme <name>: [REDACTED], et claude mcp list affiche ws à la place de l’URL

Pour voir ce que le plugin a configuré, trouvez le plugin sur le disque et lisez son .mcp.json ou son plugin.json. Noms d’outils MCP des plugins : Les outils d’un serveur MCP regroupé dans un plugin incluent à la fois le nom du plugin et la clé du serveur dans leur nom appelable. La forme complète est mcp__plugin_<plugin-name>_<server-name>__<tool-name>, où tout caractère en dehors de A-Z, a-z, 0-9, _, et - est remplacé par _. Pour le serveur database-tools regroupé dans un plugin nommé my-plugin, un outil query est appelable sous la forme :

mcp__plugin_my-plugin_database-tools__query

Utilisez ce nom complet lorsque vous référencez l’outil dans les règles de permission, la liste allowed-tools d’un skill, le champ tools d’un sous-agent, ou un matcher de hook. Un matcher de hook écrit avec la clé de serveur seule, telle que mcp__database-tools__.*, ne se déclenche jamais pour un serveur regroupé dans un plugin. Le serveur lui-même s’enregistre sous le nom préfixé plugin:<plugin-name>:<server-name>, tel que plugin:my-plugin:database-tools. Utilisez ce nom là où un nom de serveur configuré est attendu, tel que le champ server d’un hook mcp_tool. Voir la référence des composants de plugin pour les détails sur le regroupement de serveurs MCP avec les plugins.

Portées d’installation MCP

Les serveurs MCP peuvent être configurés à trois portées différentes. La portée que vous choisissez contrôle les projets dans lesquels le serveur se charge et si la configuration est partagée avec votre équipe. Les administrateurs peuvent également déployer ou fournir des serveurs pour chaque utilisateur via la configuration gérée.

Portée	Se charge dans	Partagé avec l’équipe	Stocké dans
Local	Projet actuel uniquement	Non	`~/.claude.json`
Projet	Projet actuel uniquement	Oui, via le contrôle de version	`.mcp.json` à la racine du projet
Utilisateur	Tous vos projets	Non	`~/.claude.json`

Portée locale

La portée locale est la portée par défaut. Un serveur à portée locale se charge uniquement dans le projet où vous l’avez ajouté et reste privé pour vous. Claude Code le stocke dans ~/.claude.json sous le chemin de ce projet, donc le même serveur n’apparaîtra pas dans vos autres projets. Utilisez la portée locale pour les serveurs de développement personnels, les configurations expérimentales ou les serveurs avec des identifiants que vous ne voulez pas dans le contrôle de version.

Le terme « portée locale » pour les serveurs MCP diffère des paramètres locaux généraux. Les serveurs MCP à portée locale sont stockés dans ~/.claude.json (votre répertoire personnel), tandis que les paramètres locaux généraux utilisent .claude/settings.local.json (dans le répertoire du projet). Consultez Paramètres pour plus de détails sur les emplacements des fichiers de paramètres.

# Ajouter un serveur à portée locale (par défaut)
claude mcp add --transport http stripe https://mcp.stripe.com

# Spécifier explicitement la portée locale
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

La commande écrit le serveur dans l’entrée de votre projet actuel dans ~/.claude.json. L’exemple ci-dessous montre le résultat lorsque vous l’exécutez à partir de /path/to/your/project :

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Portée du projet

Les serveurs à portée de projet permettent la collaboration d’équipe en stockant les configurations dans un fichier .mcp.json à la racine de votre projet. Lorsque vous ajoutez un serveur à portée de projet, Claude Code crée ou met à jour automatiquement ce fichier avec la structure de configuration appropriée. Archivez .mcp.json dans le contrôle de version pour que tous les membres de votre équipe obtiennent les mêmes outils et services MCP.

# Ajouter un serveur à portée de projet
claude mcp add --transport http shared-server --scope project https://example.com/mcp

Le fichier .mcp.json résultant suit un format standardisé :

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Pour des raisons de sécurité, Claude Code demande une approbation dans les sessions interactives avant d’utiliser les serveurs à portée de projet à partir des fichiers .mcp.json. Pour réinitialiser ces choix d’approbation, exécutez claude mcp reset-project-choices. Dans les exécutions claude -p, les sessions du SDK Agent et les sessions cloud en dehors des fils d’un projet, Claude Code ne peut pas afficher cette demande : il charge les serveurs à portée de projet sans demander. Claude Code ignore également la demande dans une session que vous démarrez en mode bypassPermissions avec skipDangerousModePermissionPrompt défini dans vos paramètres utilisateur ou dans les paramètres gérés. Pour garder un serveur à l’écart de toute façon :

Ajoutez-le à disabledMcpjsonServers, qui le bloque dans tous les modes de permission.
Excluez entièrement les paramètres du projet avec --setting-sources ou l’option settingSources du SDK.
Démarrez la session avec --strict-mcp-config. Claude Code utilise alors uniquement les serveurs MCP que vous transmettez avec --mcp-config. Ignorer l’invite d’approbation pour les serveurs à portée de projet que Claude Code ne charge pas nécessite Claude Code v2.1.246 ou ultérieur ; avant v2.1.246, une session stricte attendait toujours l’approbation pour eux, ce qui laissait les sessions en arrière-plan en attente au démarrage. Consultez Contrôle exclusif avec managed-mcp.json pour voir ce que le drapeau fait sous un fichier MCP géré.

Approbations des serveurs de projet et confiance de l’espace de travail couvre la façon dont les approbations validées dans le référentiel interagissent avec la confiance de l’espace de travail.

Portée utilisateur

Les serveurs à portée utilisateur sont stockés dans ~/.claude.json et offrent une accessibilité inter-projets, les rendant disponibles dans tous les projets de votre machine tout en restant privés pour votre compte utilisateur. Cette portée fonctionne bien pour les serveurs utilitaires personnels, les outils de développement ou les services que vous utilisez fréquemment dans différents projets.

# Ajouter un serveur utilisateur
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Hiérarchie de portée et précédence

Lorsque le même serveur est défini à plus d’un endroit, Claude Code s’y connecte une fois, en utilisant la définition de la source avec la plus haute priorité. L’entrée de serveur entière de cette source est utilisée ; les champs ne sont pas fusionnés entre les portées.

Portée locale
Portée du projet
Portée utilisateur
Serveurs fournis par les plugins
Connecteurs claude.ai

Les trois portées correspondent aux doublons par nom. Les plugins et les connecteurs correspondent par point de terminaison, donc celui qui pointe vers la même URL ou commande qu’un serveur ci-dessus est traité comme un doublon. Deux orthographes d’URL comptent comme le même point de terminaison lorsqu’elles diffèrent uniquement par la casse des lettres du schéma ou de l’hôte, le port par défaut du schéma, tel que :443 sur https, ou une barre oblique finale. Un chemin différent, une chaîne de requête, des informations utilisateur ou un port non-défaut font deux serveurs. Un serveur que votre organisation fournit via le paramètre géré managedMcpServers se classe au-dessus de tous ceux-ci, donc lorsque l’un d’eux le duplique, Claude Code se connecte à la définition de l’organisation. Nécessite Claude Code v2.1.259 ou ultérieur. Si vous ouvrez une session locale dans l’onglet Code de l’application de bureau avec le même nom de serveur stdio au niveau supérieur de ~/.claude.json (portée utilisateur) et dans .mcp.json, l’onglet Code utilise la définition ~/.claude.json.

Expansion des variables d’environnement dans `.mcp.json`

Claude Code supporte l’expansion des variables d’environnement dans les fichiers .mcp.json, permettant aux équipes de partager des configurations tout en maintenant la flexibilité pour les chemins spécifiques à la machine et les valeurs sensibles comme les clés API. Vous pouvez référencer une variable d’environnement dans la valeur command, args, env, url ou headers d’un serveur, sous l’une de ces deux formes :

${VAR} : se développe à la valeur de la variable d’environnement VAR
${VAR:-default} : se développe en la valeur de VAR si VAR est définie, ou en default si elle ne l’est pas

Exemple avec expansion de variable

Dans cette entrée de serveur, l’URL est la valeur de API_BASE_URL suivie de /mcp, avec https://api.example.com comme valeur par défaut, et la clé API provient de API_KEY :

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Variables non définies sans valeur par défaut

Si une variable d’environnement requise n’est pas définie et n’a pas de valeur par défaut, la configuration se charge toujours : Claude Code signale un avertissement de variable manquante pour ce serveur dans la sortie claude mcp list et utilise le texte non développé ${VAR} tel quel. Définissez la variable ou ajoutez un fallback :-default pour que le serveur démarre avec la valeur que vous avez l’intention d’utiliser. Dans l’url et les headers d’un serveur distant, certaines variables d’identification se lisent comme vides à la place, sans avertissement.

Variables définies sur une chaîne vide

Si vous définissez une variable sur une chaîne vide, elle compte comme définie, de sorte qu’une référence ${VAR:-default} se développe en chaîne vide plutôt qu’en default. Avec le serveur d’exemple, si vous définissez API_BASE_URL sur une chaîne vide, son url devient /mcp et claude mcp list signale 'url' is not a valid URL. Pour utiliser la valeur par défaut, supprimez la variable plutôt que de la définir sur une chaîne vide.

Variables d’identification qui se lisent comme vides

Dans l’url et les headers d’un serveur distant, Claude Code lit les variables d’identification de votre environnement comme vides plutôt que de les développer. Cela empêche le .mcp.json d’un projet ou un plugin d’envoyer vos identifiants Claude Code ou de fournisseur cloud à un serveur qu’il nomme. Si vous écrivez Bearer ${ANTHROPIC_AUTH_TOKEN}, le serveur reçoit Bearer sans identifiant et rejette la demande, généralement avec un 401. Claude Code signale cela comme une connexion échouée. Les noms couverts sont :

Les identifiants propres de Claude Code, tels que ANTHROPIC_API_KEY et ANTHROPIC_AUTH_TOKEN
Les identifiants de votre fournisseur cloud, tels que AWS_BEARER_TOKEN_BEDROCK
Autres identifiants que votre environnement porte, tels que HTTPS_PROXY et NPM_TOKEN

Un nom couvert se lit comme vide que vous ayez défini la variable ou non, et un fallback :-default sur celui-ci est ignoré. Une URL de base de fournisseur telle que ANTHROPIC_BASE_URL se développe toujours, donc "url": "${ANTHROPIC_BASE_URL}/mcp" fonctionne, sauf si la valeur de l’URL elle-même intègre un identifiant tel qu’un nom d’utilisateur et un mot de passe. Un nom en dehors de cet ensemble, tel que API_KEY, se développe tel qu’écrit. Pour donner au serveur l’un des identifiants couverts, copiez-le dans une variable avec un nom de votre choix et référencez ce nom à la place. Lorsque l’url ou les headers d’un serveur distant référencent une variable couverte que vous avez définie, Claude Code la nomme dans une ligne de journal de débogage. Pour lire la ligne, exécutez claude --debug-file /tmp/claude-debug.log et recherchez dans ce fichier never expanded toward a remote server.

Comment les références apparaissent dans `/mcp` et la sortie CLI

Pour un serveur dans la portée locale, de projet ou utilisateur, les surfaces suivantes affichent une référence ${VAR} par nom plutôt que comme sa valeur résolue :

L’URL ou la ligne de commande dans la vue de détail /mcp d’un serveur
Sortie claude mcp list et claude mcp get

La vue de détail /mcp affiche les références de cette façon dans Claude Code v2.1.268 ou ultérieur. Pour un serveur que votre organisation fournit via le paramètre managedMcpServers, ces surfaces affichent uniquement l’hôte de l’URL. Pour vérifier ce que claude mcp list, claude mcp get et /mcp affichent lorsqu’une connexion échoue, consultez Détail du statut du serveur.

Exemples pratiques

Exemple : Se connecter à GitHub pour les révisions de code

Le serveur MCP distant de GitHub s’authentifie avec un jeton d’accès personnel GitHub transmis en tant qu’en-tête. Pour en obtenir un, ouvrez vos paramètres de jeton GitHub, générez un nouveau jeton à granularité fine avec accès aux référentiels avec lesquels vous souhaitez que Claude travaille, puis ajoutez le serveur :

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

Remplacez YOUR_GITHUB_PAT par votre jeton d’accès personnel. La commande claude mcp add enregistre la configuration sans valider les identifiants, donc une valeur d’espace réservé est acceptée ici mais le serveur ne parvient pas à se connecter ultérieurement. Pour vérifier la connexion, exécutez /mcp et vérifiez que la ligne du serveur affiche une coche. Un serveur avec de mauvais identifiants affiche plutôt un ✘, et son détail de l’échec inclut le statut HTTP que le serveur a renvoyé, comme un 401. Ensuite, travaillez avec GitHub :

Examinez la PR #456 et suggérez des améliorations

Créer un nouveau problème pour le bogue que nous venons de trouver

Montrez-moi toutes les PR ouvertes qui me sont assignées

Exemple : Interroger votre base de données PostgreSQL

DBHub, le package @bytebase/dbhub, est un serveur MCP qui connecte Claude à une base de données relationnelle via la chaîne de connexion que vous transmettez dans --dsn. Utilisez un utilisateur de base de données en lecture seule dans la chaîne de connexion afin que les requêtes que Claude exécute ne puissent pas modifier les données :

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

Pour confirmer que le serveur démarre, exécutez /mcp et vérifiez que la ligne db affiche une coche. Ensuite, interrogez votre base de données naturellement :

Quel est notre revenu total ce mois-ci ?

Montrez-moi le schéma de la table des commandes

Trouver les clients qui n'ont pas effectué d'achat depuis 90 jours

S’authentifier auprès des serveurs MCP distants

De nombreux serveurs MCP basés sur le cloud nécessitent une authentification. Claude Code supporte OAuth 2.0 pour les connexions sécurisées. Claude Code marque un serveur distant comme nécessitant une authentification lorsque le serveur répond avec 401 Unauthorized ou 403 Forbidden. Ce que Claude Code affiche dépend du serveur :

Pour un serveur auprès duquel vous ne vous êtes pas connecté, l’un ou l’autre code de statut le signale dans /mcp afin que vous puissiez compléter le flux OAuth.
Pour un connecteur claude.ai, un 401 causé par le rejet de votre jeton de session par claude.ai ne signale pas le connecteur, car la réautorisation du connecteur ne peut pas corriger votre connexion. Claude Code affiche plutôt l’état de rejet du jeton de session.
Pour un serveur dont vous avez configuré l’en-tête Authorization, dans headers ou via un headersHelper, un 401 ou 403 lors de la connexion ne signale pas le serveur, car l’identifiant à corriger est celui que vous avez configuré. Claude Code signale plutôt la connexion comme échouée. Si vous avez défini cet en-tête à partir d’une référence ${VAR}, vérifiez si cette variable est l’une que Claude Code lit comme vide.
Pour un connecteur livré à une session cloud, Claude Code n’exécute pas de flux de connexion, car le proxy de la session s’authentifie auprès du connecteur avec l’autorisation que vous avez accordée dans claude.ai. Lorsqu’un connecteur là-bas a besoin d’être autorisé à nouveau, reconnectez-le à claude.ai/customize/connectors plutôt que depuis la session.

Lorsqu’un serveur OAuth auprès duquel vous vous êtes déjà connecté rejette votre jeton stocké avec 401 Unauthorized, Claude Code se reconnecte avec ou sans nouveau jeton :

Votre connexion stockée dispose d’un jeton d’actualisation : il actualise le jeton, se reconnecte et réessaie la requête une fois. Le serveur est signalé dans /mcp uniquement si cette nouvelle tentative échoue également.
Votre connexion stockée ne dispose pas de jeton d’actualisation : il se connecte une fois sans le jeton. Si le serveur répond, ses outils fonctionnent alors que vous êtes déconnecté, et le jeton rejeté est supprimé. Si le serveur rejette également cette connexion, /mcp indique que le serveur nécessite une authentification.

Dans une exécution claude -p ou Agent SDK sur macOS, une requête que Claude Code a envoyée alors qu’il ne pouvait pas lire votre jeton stocké échoue avec une erreur d’identifiants stockés. Lorsque le serveur rejette le jeton d’actualisation stocké, Claude Code affiche immédiatement un avis pointant vers /mcp. Ouvrez /mcp et sélectionnez Re-authenticate sur le serveur pour vous connecter à nouveau avant que le prochain appel d’outil échoue. Un serveur personnalisé qui retourne un en-tête WWW-Authenticate pointant vers son serveur d’autorisation obtient la même découverte automatique que tout autre serveur distant. Claude Code affiche également un avis de démarrage lorsqu’un ou plusieurs serveurs configurés nécessitent une authentification, vous n’avez donc pas besoin d’ouvrir /mcp pour découvrir quels serveurs nécessitent une connexion. L’avis compte uniquement les serveurs auprès desquels vous pouvez vous connecter à partir de Claude Code. Avant la v2.1.218, il comptait également les connecteurs claude.ai qui n’étaient pas connectés dans claude.ai, que vous pouvez connecter uniquement à partir des paramètres claude.ai. L’avis annonce chaque serveur une fois et l’exclut du décompte aux lancements ultérieurs jusqu’à ce que ce serveur se soit connecté et ait besoin d’une connexion à nouveau. /mcp liste toujours chaque serveur qui nécessite une connexion. Une exécution claude -p ou Agent SDK n’a pas de panneau /mcp, donc Claude Code ne peut pas y exécuter le flux OAuth. Pour utiliser un serveur qui nécessite une authentification, effectuez d’abord la connexion à partir d’une session interactive : exécutez /mcp dans la session, ou claude mcp login <name> dans votre shell. Lorsqu’un serveur configuré nécessite une authentification lors d’une exécution claude -p ou Agent SDK avec la recherche d’outils activée, Claude Code indique à Claude que les outils du serveur ne sont pas disponibles jusqu’à ce que vous l’autorisiez. Si vous avez configuré headers.Authorization pour le serveur et que le serveur rejette cet en-tête, Claude Code signale la connexion comme échouée au lieu de revenir à OAuth. Vérifiez que le jeton est valide pour l’endpoint MCP, ou supprimez l’en-tête pour utiliser le flux OAuth.

Ajouter le serveur qui nécessite une authentification

Si vous avez déjà ajouté le serveur sentry dans le démarrage rapide MCP, ignorez cette étape : exécuter claude mcp add à nouveau avec le même nom de serveur à la même portée échoue avec MCP server sentry already exists in local config. Sinon, exécutez :

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Utiliser la commande /mcp dans Claude Code

Dans Claude Code, utilisez la commande :

/mcp

Ensuite, suivez les étapes dans votre navigateur pour vous connecter.

Conseils :

Les jetons d’authentification sont stockés de manière sécurisée et actualisés automatiquement
Utilisez « Clear authentication » dans le menu /mcp pour révoquer l’accès
Si votre navigateur ne s’ouvre pas automatiquement, copiez l’URL fournie et ouvrez-la manuellement
Si la redirection du navigateur échoue avec une erreur de connexion après l’authentification, collez l’URL de rappel complète de la barre d’adresse de votre navigateur dans l’invite d’URL qui apparaît dans Claude Code
L’authentification OAuth fonctionne avec les serveurs HTTP

S’authentifier à partir de la ligne de commande

La commande claude mcp login <name> exécute le flux OAuth d’un serveur configuré directement depuis votre shell, vous n’avez donc pas besoin d’ouvrir le panneau /mcp dans une session. Pour un connecteur claude.ai, suivez Autoriser à nouveau un connecteur depuis votre shell.

claude mcp login sentry

Pour effacer les identifiants stockés ultérieurement, exécutez claude mcp logout <name>. claude mcp login détecte lorsqu’aucun navigateur local n’est disponible, par exemple lors d’une session SSH ou sur Linux sans serveur d’affichage, et imprime l’URL d’autorisation au lieu d’essayer d’ouvrir un navigateur. Ouvrez l’URL sur votre machine locale, puis collez l’URL de redirection complète de la barre d’adresse de votre navigateur à l’invite. La commande a besoin d’un terminal interactif pour l’étape de collage, donc connectez-vous avec ssh -t. Passez --no-browser pour forcer l’invite d’URL même lorsqu’un navigateur local est détecté.

claude mcp login sentry --no-browser

Utiliser un port de rappel OAuth fixe

Certains serveurs MCP nécessitent un URI de redirection spécifique enregistré à l’avance. Par défaut, Claude Code choisit un port disponible aléatoire pour le rappel OAuth. Utilisez --callback-port pour fixer le port afin qu’il corresponde à un URI de redirection pré-enregistré de la forme http://localhost:PORT/callback. Si la connexion échoue sur Claude Code v2.1.229 avec une erreur de non-concordance d’URI de redirection, consultez la note de version sous Utiliser les identifiants OAuth pré-configurés. Vous pouvez utiliser --callback-port seul (avec l’enregistrement dynamique du client) ou ensemble avec --client-id (avec les identifiants pré-configurés).

# Port de rappel fixe avec enregistrement dynamique du client
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Utiliser les identifiants OAuth pré-configurés

Certains serveurs MCP ne supportent pas la configuration OAuth automatique via l’enregistrement dynamique du client. Si vous voyez une erreur comme « Incompatible auth server: does not support dynamic client registration », le serveur nécessite des identifiants pré-configurés. Claude Code supporte également les serveurs qui utilisent un document de métadonnées d’ID client (CIMD) au lieu de l’enregistrement dynamique du client, et les découvre automatiquement. Si la découverte automatique échoue, enregistrez d’abord une application OAuth via le portail des développeurs du serveur, puis fournissez les identifiants lors de l’ajout du serveur.

Enregistrer une application OAuth auprès du serveur

Créez une application via le portail des développeurs du serveur et notez votre ID client et votre secret client.Si le formulaire d’enregistrement demande un URI de redirection, choisissez un port disponible et entrez http://localhost:PORT/callback avec ce port. Vous utiliserez le même port à l’étape suivante.Dans la v2.1.229, Claude Code envoyait http://127.0.0.1:PORT/callback à la place, et les serveurs qui correspondent exactement à l’URI de redirection enregistré rejetaient la connexion avec une erreur de non-concordance d’URI de redirection. Claude Code v2.1.231 a restauré la forme localhost. Pour récupérer sur la v2.1.229, mettez à niveau Claude Code, ou ajoutez temporairement la forme http://127.0.0.1:PORT/callback aux URI de redirection enregistrés du serveur.

Ajouter le serveur avec vos identifiants

Les onglets couvrent les deux commandes : claude mcp add prend votre ID client et votre port de rappel comme flags, et claude mcp add-json les prend dans un objet oauth. Si vous avez enregistré un URI de redirection, définissez le port de rappel sur le port dans cet URI.

claude mcp add
claude mcp add-json
claude mcp add-json (port de rappel uniquement)
CI / variable d'environnement

Utilisez --client-id pour passer l’ID client de votre application. Le flag --client-secret demande le secret avec une entrée masquée :

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Incluez l’objet oauth dans la configuration JSON et passez --client-secret comme flag séparé :

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

Pour fixer uniquement le port de rappel et laisser Claude Code enregistrer le client automatiquement, définissez callbackPort seul :

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

Définissez le secret via une variable d’environnement pour ignorer l’invite interactive :

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

S'authentifier dans Claude Code

Exécutez /mcp dans Claude Code et suivez le flux de connexion du navigateur.

Conseils :

Le secret client est stocké de manière sécurisée dans votre trousseau système (macOS) ou un fichier d’identifiants, pas dans votre configuration
Vous pouvez définir le secret client uniquement lorsque vous ajoutez le serveur. Lorsque vous vous authentifiez avec claude mcp login ou à partir de /mcp, Claude Code utilise le secret stocké et ne demande pas de secret ou ne lit pas MCP_CLIENT_SECRET
Pour ajouter ou modifier le secret ultérieurement, supprimez le serveur avec claude mcp remove <name>, puis ajoutez-le à nouveau avec --client-secret et le même --scope
Si le serveur utilise un client OAuth public sans secret, utilisez uniquement --client-id sans --client-secret
Ces flags s’appliquent uniquement aux transports HTTP et SSE. Ils n’ont aucun effet sur les serveurs stdio
Utilisez claude mcp get <name> pour vérifier que les identifiants OAuth sont configurés pour un serveur

Remplacer la découverte des métadonnées OAuth

Pointez Claude Code vers une URL de métadonnées spécifique du serveur d’autorisation OAuth pour contourner la chaîne de découverte par défaut. Définissez authServerMetadataUrl lorsque les endpoints standard du serveur MCP génèrent des erreurs, ou lorsque vous souhaitez acheminer la découverte via un proxy interne. Par défaut, Claude Code vérifie d’abord les métadonnées de ressource protégée RFC 9728 à /.well-known/oauth-protected-resource, puis revient aux métadonnées du serveur d’autorisation RFC 8414 à /.well-known/oauth-authorization-server. Définissez authServerMetadataUrl dans l’objet oauth de la configuration de votre serveur dans .mcp.json :

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

L’URL doit utiliser https://. Les scopes_supported de l’URL des métadonnées remplacent les scopes que le serveur en amont annonce.

Restreindre les scopes OAuth

Définissez oauth.scopes pour épingler les scopes que Claude Code demande pendant le flux d’autorisation. C’est la façon supportée de restreindre un serveur MCP à un sous-ensemble approuvé par l’équipe de sécurité lorsque le serveur d’autorisation en amont annonce plus de scopes que vous ne souhaitez accorder. La valeur est une seule chaîne séparée par des espaces, correspondant au format du paramètre scope dans RFC 6749 §3.3.

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

oauth.scopes a la priorité sur authServerMetadataUrl et les scopes que le serveur découvre à /.well-known. Laissez-le non défini pour laisser le serveur MCP déterminer l’ensemble de scopes demandés. Lorsque oauth.scopes n’est pas défini, Claude Code ne demande pas le catalogue complet scopes_supported issu des métadonnées du serveur d’autorisation découvertes automatiquement. Les métadonnées récupérées à partir d’une authServerMetadataUrl configurée fournissent toujours leurs scopes_supported comme scopes demandés. Si le serveur d’autorisation annonce offline_access dans scopes_supported, Claude Code l’ajoute aux scopes épinglés afin que le jeton d’accès puisse être actualisé sans une nouvelle connexion au navigateur. Si le serveur retourne ultérieurement un 403 insufficient_scope pour un appel d’outil, l’appel échoue avec un message needs additional permissions qui nomme le scope que le serveur demande. Le serveur s’affiche comme nécessitant une authentification dans /mcp. Si ce scope ne figure pas dans votre oauth.scopes épinglé, ajoutez-le, puis exécutez /mcp et authentifiez le serveur à nouveau. Claude Code demande les scopes épinglés plutôt que le scope que le serveur a nommé, donc si vous vous authentifiez à nouveau sans l’ajouter, le jeton que vous obtenez ne l’a toujours pas.

Utiliser OAuth avec un serveur derrière un proxy d’authentification

Si votre serveur MCP utilise OAuth derrière un proxy ou une passerelle qui vérifie son propre en-tête, la connexion échoue lorsque les requêtes OAuth arrivent sans cet en-tête. La connexion via le proxy nécessite Claude Code v2.1.299 ou une version ultérieure, avec l’en-tête et la connexion tous deux configurés :

L’en-tête du proxy : transmettez-le avec --header, le champ headers ou un headersHelper, sous le nom que le proxy lit
La connexion OAuth : n’incluez pas Authorization dans les en-têtes configurés, puis connectez-vous avec claude mcp login <name> dans votre shell. Si vous configurez un en-tête Authorization, Claude Code l’utilise comme identifiant du serveur et ne revient pas à OAuth pour ce serveur.

Utiliser des en-têtes dynamiques pour l’authentification personnalisée

Lorsqu’une authentification telle que Kerberos, des jetons de courte durée ou un SSO interne nécessite des en-têtes générés au moment de la connexion, définissez le headersHelper du serveur sur une commande. Claude Code l’exécute lors de la connexion et fusionne sa sortie dans les en-têtes qu’il envoie. Cet exemple utilise un script :

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

La commande peut également être en ligne :

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

Exigences :

La commande doit écrire un objet JSON de paires clé-valeur de chaîne sur stdout
Claude Code exécute la commande dans un shell et abandonne après 10 secondes
Claude Code choisit le répertoire de travail de la commande en fonction de l’endroit où vous avez configuré le serveur, donc fournissez le script comme chemin absolu ou mettez-le sur PATH
Les en-têtes dynamiques remplacent tous les headers statiques portant le même nom

Claude Code exécute l’assistant à nouveau à chaque connexion, au démarrage de la session et à la reconnexion, une fois que la règle de confiance pour les serveurs de portée projet et locale le permet. Il ne met pas en cache le résultat, donc votre script est responsable de toute réutilisation de jetons. Si un appel d’outil retourne 401 Unauthorized ou 403 Forbidden, Claude Code réexécute automatiquement l’assistant selon la même règle, se reconnecte avec les en-têtes frais et réessaie l’appel une fois. Claude Code marque le serveur comme nécessitant une authentification dans /mcp uniquement si cette nouvelle tentative échoue également. Lorsque la sortie de l’assistant inclut un en-tête Authorization, Claude Code utilise cet identifiant comme authentification du serveur et ne revient pas à OAuth pour le serveur. Si le serveur rejette l’identifiant de l’assistant lors de la connexion, Claude Code signale la connexion comme échouée plutôt que de marquer le serveur comme nécessitant une authentification. Corrigez l’identifiant que votre assistant retourne, puis reconnectez-vous à partir de /mcp pour réexécuter l’assistant. Claude Code définit ces variables d’environnement lors de l’exécution de l’assistant :

Variable	Valeur
`CLAUDE_CODE_MCP_SERVER_NAME`	le nom du serveur MCP
`CLAUDE_CODE_MCP_SERVER_URL`	l’URL du serveur MCP
`CLAUDE_PLUGIN_ROOT`	le répertoire racine du plugin. Défini uniquement lorsqu’un plugin fournit le serveur

Utilisez-les pour écrire un script d’assistant unique qui sert plusieurs serveurs MCP. Un headersHelper fourni par un plugin ne peut pas référencer les valeurs ${user_config.*} du plugin, car la commande s’exécute via un shell. Claude Code signale le serveur comme mal configuré avec une erreur et ne substitue pas la valeur. Mettez ${user_config.KEY} dans le champ headers du serveur à la place, qui n’est pas analysé par shell, ou faites en sorte que le script d’assistant lise la valeur à partir d’un fichier de configuration. Avant la v2.1.207, headersHelper substituait les valeurs ${user_config.*}.

Où l’assistant s’exécute

Claude Code choisit le répertoire de travail de la commande headersHelper à partir de la configuration qui déclare le serveur. Un cd que Claude exécute dans Bash ne le déplace pas, et /cd ne le déplace que pour les serveurs qui s’exécutent à partir du répertoire de travail principal de la session. Chaque ligne ci-dessous donne le répertoire contre lequel un chemin relatif dans votre commande headersHelper se résout.

Où vous avez configuré le serveur	Répertoire de travail
Un plugin	Le répertoire racine du plugin
Un `.mcp.json` de projet ou un serveur de portée locale	Le répertoire du projet dans lequel le serveur est déclaré
Un fichier agent dans votre projet, un serveur de l’option `mcpServers` du SDK ou de la méthode `setMcpServers()`, ou `--mcp-config`	Le répertoire de travail principal de la session
Portée utilisateur, MCP géré, un connecteur claude.ai, ou un fichier agent en dehors de votre projet, y compris un d’un répertoire `--add-dir`	Votre répertoire de configuration, `~/.claude` sauf si vous avez défini `CLAUDE_CONFIG_DIR`

Avant la v2.1.238, Claude Code exécutait également les assistants des serveurs de portée utilisateur, gérés et connecteur claude.ai, et des fichiers agent en dehors de votre projet, à partir du répertoire à partir duquel vous l’aviez démarré.

Quelles variables un assistant peut lire

Un headersHelper qu’un dépôt ou un plugin fournit est une commande que vous n’avez pas écrite, donc Claude Code l’exécute sans les variables d’identifiant de votre environnement, telles que ANTHROPIC_API_KEY. L’endroit où vous avez configuré le serveur détermine si cela s’applique :

Supprimées : un serveur dans un .mcp.json de projet ou dans un plugin, et un serveur en ligne dans un fichier agent de votre projet ou d’un répertoire --add-dir
Non supprimées : un serveur à portée utilisateur ou portée locale, dans MCP géré, à partir d’un connecteur claude.ai, ou fourni par le SDK ou --mcp-config, et un serveur en ligne dans un fichier agent de ~/.claude/agents/, à partir des paramètres gérés, ou passé avec --agents

À part les variables GIT_CONFIG_KEY_<n> de Git, Claude Code supprime chaque variable de votre environnement dont le nom ressemble à un identifiant, comme un nom avec TOKEN, SECRET, PASSWORD, KEY ou AUTH dedans en l’une ou l’autre casse, donc ANTHROPIC_API_KEY et MY_REGISTRY_TOKEN sont tous deux supprimés. Claude Code supprime également une liste fixe de variables d’identifiant dont les noms ne suivent pas ce modèle, telles que ANTHROPIC_CUSTOM_HEADERS. Lorsque cela s’applique à votre assistant, faites en sorte que le script lise son identifiant à partir d’un fichier ou d’un magasin d’identifiants. Si l’url du serveur contient la valeur réelle de l’une de ces variables, comme MY_REGISTRY_TOKEN, la valeur CLAUDE_CODE_MCP_SERVER_URL que l’assistant reçoit a également cette partie remplacée par REDACTED.

Faire confiance à un dossier avant que son headersHelper s’exécute

Claude Code exécute un headersHelper comme une commande shell arbitraire. Pour un serveur dans un .mcp.json de projet ou à portée locale, il exécute l’assistant uniquement après que vous ayez accepté la boîte de dialogue de confiance pour le répertoire du projet dans lequel le serveur est déclaré. Avant la v2.1.238, une session claude -p ou SDK exécutait ces assistants sans vérifier la confiance, et une session interactive les exécutait une fois que vous aviez fait confiance à un dossier parent.

Confiance qui ne compte pas : la confiance d’un dossier parent, et la confiance automatique qu’une session claude -p ou SDK obtient pour les hooks dans les fichiers de paramètres
Jusqu’à ce que vous fassiez confiance au dossier : Claude Code connecte le serveur avec ses headers statiques seuls. Dans une session claude -p ou SDK, il imprime également une ligne headersHelper not run par serveur sur stderr, vous indiquant comment accorder la confiance.
Confiance sans boîte de dialogue : définissez projects["<path>"].hasTrustDialogAccepted à true dans ~/.claude.json. <path> est le dossier sur lequel Règles d’autorisation de projet et confiance de l’espace de travail dit que Claude Code base la confiance.

Claude Code applique la même règle à un serveur déclaré en ligne dans un fichier agent, en vérifiant d’où ce fichier agent provient : votre projet, pour un fichier dans son répertoire .claude/agents/, ou un répertoire --add-dir. Jusqu’à ce que vous fassiez confiance à ce projet ou répertoire lui-même, Claude Code ne charge pas le serveur du tout, donc son assistant ne s’exécute jamais non plus. La connexion OAuth à un serveur MCP échoue lorsqu’une passerelle exige un en-tête, tel que X-API-Key, et que Claude Code ne l’envoie pas. Pour que Claude Code envoie cet en-tête, ajoutez-le à la configuration du serveur et utilisez Claude Code v2.1.299 ou une version ultérieure :

Un serveur dont vous pouvez modifier la configuration : définissez-le dans headers ou renvoyez-le depuis un headersHelper
Un serveur fourni par le MCP géré ou un plugin : demandez à votre administrateur ou à l’auteur du plugin d’ajouter l’en-tête à l’entrée du serveur

Claude Code ajoute alors les en-têtes configurés, à l’exception de Authorization, aux requêtes de connexion, d’actualisation de jeton et de révocation de jeton qu’il envoie à l’origine du serveur. L’origine du serveur correspond au schéma, à l’hôte et au port de son url. Une passerelle qui exige l’en-tête peut toujours bloquer la connexion au niveau de la page d’autorisation ou d’un serveur d’autorisation situé sur une autre origine :

La page d’autorisation : vous vous connectez sur cette page dans votre navigateur, qui n’envoie pas les en-têtes configurés. Si votre navigateur reçoit l’erreur de la passerelle au lieu de la page, demandez au responsable de la passerelle de laisser passer la page sans l’en-tête.
Un serveur d’autorisation sur une autre origine : si une passerelle placée devant ce serveur exige également l’en-tête, la connexion y échoue. Demandez au responsable de cette passerelle de laisser passer les requêtes OAuth sans l’en-tête.

Ajouter des serveurs MCP à partir de la configuration JSON

Si vous avez une configuration JSON pour un serveur MCP, vous pouvez l’ajouter directement :

Ajouter un serveur MCP à partir de JSON

# Syntaxe de base
claude mcp add-json <name> '<json>'

# Exemple : Ajouter un serveur HTTP avec configuration JSON
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Exemple : Ajouter un serveur stdio avec configuration JSON
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Exemple : Ajouter un serveur HTTP avec identifiants OAuth pré-configurés
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

Vérifier que le serveur a été ajouté

claude mcp get weather-api

Conseils :

Assurez-vous que le JSON est correctement échappé dans votre shell
Le JSON doit se conformer au schéma de configuration du serveur MCP
Vous pouvez utiliser --scope user pour ajouter le serveur à votre configuration utilisateur au lieu de celle spécifique au projet

Importer les serveurs MCP à partir de Claude Desktop

Si vous avez déjà configuré des serveurs MCP dans Claude Desktop, vous pouvez les importer :

Importer les serveurs à partir de Claude Desktop

# Syntaxe de base 
claude mcp add-from-claude-desktop 

Sélectionner les serveurs à importer

Après avoir exécuté la commande, vous verrez une boîte de dialogue interactive qui vous permet de sélectionner les serveurs que vous souhaitez importer.

Vérifier que les serveurs ont été importés

claude mcp list

Les noms de serveurs ajoutés via les commandes claude mcp ne peuvent contenir que des lettres, des chiffres, des tirets et des traits de soulignement. Claude Desktop n’applique pas cette restriction, donc un serveur Claude Desktop dont le nom contient un autre caractère, comme un espace, ne peut pas être importé. L’importation signale chaque nom qu’elle rejette et importe toujours les autres serveurs que vous avez sélectionnés.

Conseils :

Cette fonctionnalité ne fonctionne que sur macOS et Windows Subsystem for Linux (WSL)
Elle lit le fichier de configuration de Claude Desktop à partir de son emplacement standard sur ces plates-formes
Utilisez le drapeau --scope user pour ajouter les serveurs à votre configuration utilisateur
Les serveurs importés conservent les mêmes noms que dans Claude Desktop lorsque le nom ne contient que des lettres, des chiffres, des tirets et des traits de soulignement. Claude Code signale un serveur dont le nom contient un autre caractère et l’ignore
Si des serveurs portant les mêmes noms existent déjà, ils recevront un suffixe numérique (par exemple, server_1)

Utiliser les serveurs MCP depuis claude.ai

Si vous vous êtes connecté à Claude Code avec un compte claude.ai, les serveurs MCP que vous avez ajoutés dans claude.ai, connus sous le nom de connecteurs, sont automatiquement disponibles dans Claude Code :

Configurer les serveurs MCP dans claude.ai

Ajoutez des serveurs à claude.ai/customize/connectors. Sur les plans Team et Enterprise, seuls les administrateurs peuvent ajouter des serveurs.

Authentifier le serveur MCP

Complétez les étapes d’authentification requises dans claude.ai.

Afficher et gérer les serveurs dans Claude Code

Dans Claude Code, utilisez la commande :

/mcp

Les serveurs de claude.ai apparaissent dans la liste avec des indicateurs montrant qu’ils proviennent de claude.ai.

Anthropic fournit également certains connecteurs lui-même, sans que vous ou un administrateur les ajoute. Sur les comptes où Claude Docs est disponible, /mcp liste claude.ai Claude Docs sans configuration, et Claude l’utilise lorsque vous demandez un document destiné à d’autres personnes. Pour désactiver uniquement ce connecteur, consultez Désactiver les connecteurs claude.ai. Claude Code marque un connecteur comme managed dans /mcp et dans le gestionnaire /plugin lorsque votre organisation gère son authentification dans claude.ai. Le statut managed ne change pas la façon dont Claude Code se connecte au connecteur ou applique les contrôles d’outils de votre organisation. Les connecteurs auxquels vous ne vous êtes jamais connecté sont réduits derrière une ligne Show unused connectors à la fin de la section claude.ai, de sorte qu’une liste fournie par l’organisation ne remplit pas le panneau. Sélectionnez la ligne pour les développer. Un connecteur auquel vous vous êtes connecté avant reste visible même s’il a actuellement besoin d’une nouvelle authentification. Les connecteurs de claude.ai ne sont récupérés que lorsque votre méthode d’authentification active est une connexion par abonnement claude.ai. Ils ne sont pas chargés, même si vous avez précédemment exécuté /login, lorsque :

ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ou apiKeyHelper est actif
Un fournisseur tiers tel qu’Amazon Bedrock ou Agent Platform de Google Cloud est actif
ANTHROPIC_PROFILE, les variables de fédération, ou un profil Anthropic actif fournit les identifiants
CLAUDE_CODE_OAUTH_TOKEN contient un jeton de claude setup-token, qui ne peut faire que des requêtes de modèle

Si /mcp ne liste pas un connecteur que vous avez ajouté, exécutez /status pour confirmer quelle méthode d’authentification est active. Supprimez cette variable d’environnement, retirez le paramètre apiKeyHelper, ou désactivez le profil, puis exécutez /login pour sélectionner votre compte claude.ai. Si un problème réseau temporaire empêche la liste des connecteurs de se charger au démarrage de votre session, Claude Code réessaie la récupération jusqu’à trois fois en arrière-plan, et les connecteurs apparaissent une fois qu’une tentative réussit. S’ils n’ont toujours pas apparu, redémarrez Claude Code pour récupérer la liste à nouveau. Si /mcp affiche un connecteur comme session token rejected, ou sa vue détaillée affiche claude.ai rejected the session token, claude.ai a rejeté le jeton de votre connexion Claude Code. Autoriser à nouveau le connecteur n’efface pas cet état, car l’autorisation propre du connecteur dans claude.ai n’est pas ce qui a été rejeté. Pour l’effacer :

Exécutez /login pour vous reconnecter.
Reconnectez le connecteur depuis /mcp.

Avant la v2.1.222, Claude Code marquait plutôt les connecteurs comme ayant besoin d’authentification, et les autoriser ne le résolvait pas. Un serveur que vous avez ajouté dans Claude Code a priorité sur un connecteur claude.ai qui pointe vers la même URL. Quand cela se produit, /mcp liste le connecteur comme caché et montre comment supprimer le doublon si vous préférez utiliser le connecteur. Certains connecteurs hébergés par Anthropic, tels que Microsoft 365, Gmail et Google Calendar, ne supportent pas OAuth local depuis Claude Code car le fournisseur d’identité en amont n’accepte que l’URL de redirection que claude.ai a enregistrée. Quand un serveur que vous avez ajouté avec claude mcp add ou dans .mcp.json pointe vers l’un de ces hôtes et que vous vous y connectez depuis /mcp ou avec claude mcp login, Claude Code affiche is Anthropic-hosted and doesn't support local OAuth, vous dirigeant pour connecter le service à claude.ai/customize/connectors à la place. Après avoir supprimé votre entrée avec claude mcp remove <name> et connecté le service sur claude.ai, le connecteur apparaît dans Claude Code automatiquement.

Comment les connecteurs atteignent Claude Code

Les paramètres qui gouvernent un connecteur claude.ai dépendent de l’endroit où votre session s’exécute, car seules certaines sessions récupèrent les connecteurs de claude.ai elles-mêmes. Chaque ligne ci-dessous nomme comment les connecteurs arrivent dans un type de session et ce qui les contrôle là. Les sessions WSL de l’application de bureau n’ont pas de ligne car les connecteurs sont encore en cours de déploiement pour celles-ci.

Où la session s’exécute	Comment les connecteurs arrivent	Ce qui les gouverne
Sessions Terminal, VS Code, JetBrains, et Agent SDK	Claude Code les récupère depuis claude.ai	Les paramètres de cette section et configuration MCP gérée
Sessions cloud	L’hôte cloud les transmet	Vos paramètres d’organisation claude.ai, plus les paramètres de liste d’autorisation et liste de refus qui atteignent la session et tout `managed-mcp.json` sur l’hôte qui l’exécute
Les sessions locales et SSH de l’application de bureau	L’application de bureau les livre en processus	Les entrées `blocked` dans les contrôles d’outils de connecteur de votre organisation

disableClaudeAiConnectors, ENABLE_CLAUDEAI_MCP_SERVERS, et allowAllClaudeAiMcps agissent uniquement sur la première ligne, les connecteurs que Claude Code récupère lui-même. Les deux autres lignes en diffèrent de ces façons :

Sessions cloud : les entrées allowedMcpServers et deniedMcpServers qui atteignent la session, par exemple via les paramètres gérés par le serveur, filtrent également les connecteurs livrés. Le proxy de la session réécrit l’URL de chaque connecteur, donc un motif serverUrl écrit pour l’URL propre du connecteur ne lui correspond pas. Pour admettre les connecteurs livrés aux côtés d’une liste d’autorisation d’URL dans un environnement auto-hébergé, ajoutez les entrées serverUrl listées sous Le trafic des connecteurs quitte votre réseau. Claude Code supprime les connecteurs livrés quand un managed-mcp.json est présent sur l’hôte qui exécute la session, comme un hôte de runner auto-hébergé, que vous ayez défini allowAllClaudeAiMcps ou non.
Sessions locales et SSH de l’application de bureau : l’application de bureau enregistre les connecteurs en tant que serveurs type: "sdk" en processus, et aucun paramètre MCP ou managed-mcp.json ne les atteint. Un utilisateur garde un connecteur hors de ses propres sessions en le déconnectant à claude.ai/customize/connectors. Une organisation bloque les outils d’un connecteur ou désactive entièrement Claude Code dans l’application de bureau.

Contrôles d’organisation sur les outils de connecteur

Votre organisation peut définir des contrôles par outil sur les connecteurs claude.ai. Claude Code lit ces paramètres au démarrage et les applique localement, sauf dans les sessions locales et SSH de l’application de bureau. Là, l’application de bureau retient les outils blocked avant de livrer un connecteur, et le paramètre ask n’atteint pas Claude Code, donc il applique les règles de permission ordinaires de la session à ces outils au lieu de demander à chaque appel. Dans les sessions où Claude Code récupère les connecteurs lui-même, exécutez /mcp pour voir quel paramètre s’applique à chaque outil sur un connecteur.

Outil défini sur ask : Claude Code demande à chaque appel avec la raison Your organization requires approval for this tool. La demande apparaît même dans les modes de permission acceptEdits, auto, et bypassPermissions. Dans le terminal, la demande n’offre aucune option pour mémoriser votre choix. Les règles Allow qui correspondent à l’outil ne sautent pas non plus la demande. En mode dontAsk, qui ne demande jamais, Claude Code refuse l’appel à la place.
Outil défini sur blocked : Claude Code filtre l’outil avant que Claude ne le voie, donc il n’apparaît jamais dans la liste des outils de Claude. Dans les sessions où Claude Code récupère les connecteurs lui-même, la liste d’outils /mcp affiche toujours l’outil, marqué disabled by your organization.

L’application de bureau et le chat claude.ai appliquent le même paramètre blocked, donc Claude ne peut pas non plus y utiliser un outil bloqué, et vous ne pouvez pas retenir un outil des sessions de l’application de bureau tout en le gardant disponible dans le chat. L’application de bureau saute un connecteur dont tous les outils sont bloqués.

Désactiver les connecteurs claude.ai

Claude Code applique disableClaudeAiConnectors uniquement aux connecteurs qu’il récupère lui-même, pas aux connecteurs qu’un hôte cloud ou l’application de bureau livre. Pour désactiver les connecteurs qu’il récupère, définissez le paramètre sur true dans n’importe quelle portée de paramètres :

{
  "disableClaudeAiConnectors": true
}

Ce paramètre utilise la sémantique any-source-true : true dans n’importe quelle source de paramètres a priorité. Un .claude/settings.json de projet enregistré peut exclure un dépôt des connecteurs que Claude Code récupère lui-même, mais un false au niveau du projet ne peut pas réactiver les connecteurs qu’un true au niveau utilisateur ou politique a désactivés. Les serveurs passés explicitement via --mcp-config ne sont pas affectés. Vous pouvez également définir la variable d’environnement ENABLE_CLAUDEAI_MCP_SERVERS sur false, qui a le même effet pour la session shell actuelle :

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Pour bloquer les connecteurs claude.ai individuels au lieu de tous les bloquer, ajoutez-les à deniedMcpServers par nom ou par motif d’URL. Par exemple, une entrée serverName de "claude.ai Slack" bloque le connecteur Slack. Vous pouvez également exécuter /mcp pour basculer n’importe quel connecteur que Claude Code récupère activé ou désactivé pour le projet actuel uniquement.

Utiliser Claude Code comme serveur MCP

Vous pouvez utiliser Claude Code lui-même comme serveur MCP que d’autres applications peuvent connecter :

# Démarrer Claude en tant que serveur MCP stdio
claude mcp serve

La commande n’affiche rien au démarrage. Un serveur MCP stdio communique via stdin et stdout, donc un terminal silencieux et bloqué signifie que le serveur est en cours d’exécution et attend qu’un client se connecte. Vous pouvez utiliser ceci dans Claude Desktop en ajoutant cette configuration à claude_desktop_config.json :

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Configuration du chemin exécutable : le champ command doit référencer l’exécutable Claude Code. Si la commande claude ne se trouve pas dans le PATH de votre système, vous devrez spécifier le chemin complet vers l’exécutable.Pour trouver le chemin complet :

which claude

Utilisez ensuite le chemin complet dans votre configuration :

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Sans le chemin exécutable correct, vous rencontrerez des erreurs comme spawn claude ENOENT.

Conseils :

Dans Claude Desktop, essayez de demander à Claude de lire les fichiers d’un répertoire, de faire des modifications, et bien plus.
Ce serveur MCP expose uniquement les outils de Claude Code à votre client MCP, donc votre propre client est responsable de l’implémentation de la confirmation de l’utilisateur pour les appels d’outils individuels.

Lire la sortie d’une commande en arrière-plan en tant que client MCP

Un champ backgroundOutputPath dans un résultat Bash ou PowerShell de claude mcp serve signifie que l’appel a laissé sa commande s’exécuter en arrière-plan. Une commande s’exécute en arrière-plan lorsque votre client définit run_in_background: true sur l’appel. Une commande au premier plan peut également passer en arrière-plan lorsqu’elle atteint son délai d’expiration. Le champ se trouve dans le texte JSON du résultat et contient le chemin du fichier de sortie de la commande.

Pour lire la sortie écrite jusqu’ici : ouvrez le fichier situé à ce chemin depuis votre client, ou transmettez le chemin comme file_path à l’outil Read du serveur
Pour savoir quand la commande est terminée : ajoutez un echo d’une chaîne fixe à la valeur de command, comme dans npm test; echo DONE. La commande est terminée dès que cette chaîne apparaît dans le fichier. Sans cette chaîne, rien ne marque la fin, car Claude Code n’ajoute aucune ligne de clôture au fichier et ne notifie pas votre client.
Pour lire la fin d’une sortie longue : Read avec uniquement file_path renvoie la première page, ou échoue lorsque le fichier dépasse la taille limite. Transmettez également offset et limit, ce qui fonctionne quelle que soit la taille du fichier :
1. Appelez Read avec offset et limit tous deux définis sur 1, et récupérez totalLines dans le résultat
2. Appelez à nouveau Read avec offset défini sur totalLines moins neuf et limit défini sur 10
3. Recherchez votre chaîne echo dans les dix dernières lignes, que renvoie le second appel

Le champ backgroundOutputPath nécessite Claude Code v2.1.295 ou une version ultérieure.

Limites de sortie MCP et avertissements

Lorsque les outils MCP produisent des sorties volumineuses, Claude Code aide à gérer l’utilisation des tokens pour éviter de surcharger le contexte de votre conversation :

Seuil d’avertissement de sortie : Claude Code affiche un avertissement lorsque la sortie de tout outil MCP dépasse 10 000 tokens
Limite configurable : vous pouvez ajuster le nombre maximum de tokens de sortie MCP autorisés à l’aide de la variable d’environnement MAX_MCP_OUTPUT_TOKENS
Limite par défaut : le maximum par défaut est de 25 000 tokens
Portée : la variable d’environnement s’applique aux outils qui ne déclarent pas leur propre limite. Les outils qui définissent anthropic/maxResultSizeChars utilisent cette valeur à la place pour le contenu textuel, indépendamment de la valeur définie pour MAX_MCP_OUTPUT_TOKENS. Les outils qui retournent des données d’image restent soumis à MAX_MCP_OUTPUT_TOKENS
Au-delà de la limite : lorsqu’un résultat réussi sans contenu d’image dépasse la limite de tokens, Claude Code l’enregistre dans un fichier et le remplace dans la conversation par un message qui indique le chemin du fichier, de sorte que Claude lit le fichier lorsqu’il a besoin du contenu. Le fichier se trouve dans le répertoire tool-results de la session sous ~/.claude/projects/.
Taille des réponses des serveurs HTTP et SSE : lorsqu’une réponse d’un serveur HTTP ou SSE dépasse 16 Mio, Claude Code arrête de la lire et la requête échoue. La limite s’applique après décompression à un corps de réponse JSON ou à un événement d’un flux d’événements. Si vous maintenez le serveur, renvoyez moins de données par réponse pour rester sous la limite, par exemple en paginant les résultats
Taille des messages des serveurs WebSocket : lorsqu’un serveur WebSocket envoie un message de plus de 16 Mio, Claude Code ferme la connexion, et les appels en cours sur ce serveur échouent. Si vous maintenez le serveur, renvoyez moins de données par message pour rester sous la limite

Un appel que Claude Code a déplacé vers une tâche en arrière-plan transmet son résultat via la notification de tâche. Deux limites supplémentaires s’appliquent à un appel qui se termine au premier plan :

Limite de caractères pour les résultats textuels : pour un outil qui ne déclare pas anthropic/maxResultSizeChars, Claude Code enregistre dans un fichier un résultat réussi sans contenu d’image dès qu’il dépasse 50 000 caractères, quel que soit son nombre de tokens. Définir MAX_MCP_OUTPUT_TOKENS ne modifie pas ce seuil
Résultats d’erreur : lorsqu’un outil retourne un résultat marqué isError: true, Claude reçoit le texte du résultat comme message d’erreur de l’outil. Un texte d’erreur de plus d’environ 11 000 caractères ne conserve que ses 5 000 premiers et ses 5 000 derniers caractères, avec entre les deux un marqueur indiquant le nombre de caractères supprimés

Pour modifier la limite de tokens, définissez MAX_MCP_OUTPUT_TOKENS dans votre shell avant de démarrer Claude Code :

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Augmenter la limite pour un outil spécifique

Si vous créez un serveur MCP, vous pouvez permettre aux outils individuels de retourner des résultats plus volumineux que le seuil de persistance sur disque par défaut de 50 000 caractères en définissant _meta["anthropic/maxResultSizeChars"] dans l’entrée de réponse tools/list de l’outil. Claude Code augmente le seuil de cet outil à la valeur annotée, jusqu’à un plafond maximal de 500 000 caractères. Ceci est utile pour les outils qui retournent des sorties intrinsèquement volumineuses mais nécessaires, telles que les schémas de base de données ou les arbres de fichiers complets. Sans l’annotation, les résultats réussis qui dépassent le seuil par défaut sont persistés sur disque et remplacés par une référence de fichier dans la conversation.

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

L’annotation s’applique indépendamment de MAX_MCP_OUTPUT_TOKENS pour le contenu textuel, de sorte que les utilisateurs n’ont pas besoin d’augmenter la variable d’environnement pour les outils qui la déclarent. Les outils qui retournent des données d’image restent soumis à la limite de tokens.

Images dans les résultats des outils

Lorsqu’un outil MCP retourne une image PNG, JPEG, GIF ou WebP, Claude voit l’image en ligne dans la conversation. La copie en ligne peut être réduite ou compressée pour s’adapter aux limites de taille d’image du modèle. Claude Code enregistre également les octets originaux dans un fichier du répertoire tool-results de la session sous ~/.claude/projects/ et donne le chemin à Claude. Claude peut ensuite recadrer, convertir ou réutiliser le fichier en pleine résolution avec des outils tels que Bash. Si vous désactivez la persistance de session avec --no-session-persistence ou CLAUDE_CODE_SKIP_PROMPT_HISTORY, Claude Code n’écrit aucun fichier image et Claude reçoit uniquement la copie en ligne. L’enregistrement des résultats d’image MCP dans un fichier nécessite Claude Code v2.1.283 ou version ultérieure.

Schémas d’entrée d’outil avec un combinateur au niveau racine

Certains serveurs MCP déclarent le schéma d’entrée d’un outil comme une union JSON Schema, avec anyOf, oneOf, ou allOf au niveau supérieur du schéma. L’API Claude n’accepte pas ces mots-clés à la racine du schéma. Elle accepte les combinateurs imbriqués dans properties, que Claude Code envoie inchangés. Les outils avec un combinateur au niveau racine restent disponibles. Avant d’envoyer l’outil à l’API, Claude Code aplatit le schéma en un seul objet et ajoute une phrase au début de la description de l’outil qui indique à Claude quels groupes de paramètres vont ensemble :

allOf : les propriétés de chaque branche sont fusionnées, et la liste required de chaque branche s’applique toujours
anyOf et oneOf : les propriétés de chaque branche sont fusionnées, et la liste required de chaque branche est décrite dans la description de l’outil au lieu d’être appliquée par le schéma

Votre serveur reçoit les arguments que Claude a choisis, alors continuez à valider la combinaison côté serveur. Quand Claude Code ne peut pas produire un schéma que l’API accepte, ou sur un déploiement qui ne reçoit pas la configuration distante qui active la réécriture, il ignore cet outil, enregistre la raison dans le journal du serveur, et laisse les autres outils du serveur disponibles.

Outils avec des schémas d’entrée invalides

Si votre session échoue avec une erreur 400 qui nomme un outil par sa position, suivez les étapes de Tool input schema is invalid.

Si l’un des outils de votre serveur MCP possède un schéma d’entrée qui enfreint l’une des deux règles appliquées par l’API, Claude Code exclut cet outil. Les autres outils du serveur ne sont pas affectés. Claude Code vérifie les deux règles lorsqu’il charge les outils du serveur :

Les noms de propriétés au niveau supérieur doivent faire entre 1 et 64 caractères et utiliser uniquement des lettres ASCII et des chiffres, _, . et -
Le schéma doit être valide par rapport au méta-schéma JSON Schema draft 2020-12. Claude Code applique cette vérification aux schémas qui ne déclarent pas de $schema et aux schémas qui déclarent draft 2020-12. Un schéma qui déclare un autre dialecte ignore cette vérification, bien que la vérification du nom de propriété ci-dessus s’applique toujours

Lorsque Claude Code exclut un outil, il enregistre la raison dans le journal du serveur et indique à Claude quels outils il a exclus et pourquoi, afin que vous puissiez demander à Claude pourquoi un outil est manquant. Si vous corrigez le schéma sur le serveur, l’outil réapparaît la prochaine fois que Claude Code charge les outils du serveur. Lorsque la récupération des feature flags est désactivée ou que les flags n’ont jamais été reçus, comme sur une machine isolée du réseau, un outil qui enfreint une règle n’est pas exclu :

Claude reçoit l’outil tel quel, et le log du serveur consigne input schema would be rejected by the Anthropic API pour cet outil
Si l’API rejette ensuite le schéma, consultez Outils dont l’API refuse le schéma d’entrée

Avant la v2.1.216, aucun déploiement n’exécutait ces vérifications. La gestion du combinateur au niveau racine est séparée et conserve son propre comportement lorsque la récupération de drapeaux est désactivée ou que les drapeaux n’ont jamais été reçus.

Outils dont l’API refuse le schéma d’entrée

Si une ligne du log de débogage contient the API refused this tool's input schema, elle nomme un outil dont l’API a rejeté le schéma dans une requête. Claude Code renvoie cette requête en déclarant l’outil sans paramètres.

Si votre session échoue avec une erreur 400 qui nomme un outil par sa position : suivez les étapes de Tool input schema is invalid
Si vous utilisez le serveur : vous n’avez rien à faire. Claude peut toujours appeler l’outil, mais ne voit pas ses paramètres
Si vous maintenez le serveur : corrigez le schéma d’entrée de l’outil sur le serveur. La ligne du log se termine par The API said: suivi de la raison pour laquelle l’API a rejeté le schéma. Validez les arguments que reçoit le serveur, car Claude appelle l’outil sans voir ses paramètres

Avant la v2.1.300, chaque tour incluant le schéma refusé échouait avec une erreur 400 nommant l’outil par sa position.

Outils dont le nom dépasse 128 caractères

Si /mcp répertorie un outil que Claude ne peut pas appeler, vérifiez si le nom complet de l’outil dépasse 128 caractères. Exécutez /mcp dans votre session et sélectionnez l’outil pour afficher son nom complet, par exemple mcp__<server>__<tool>. Claude Code exclut un outil MCP des outils qu’il envoie à Claude lorsque son nom complet dépasse 128 caractères. L’API Claude rejette toute requête qui inclut un tel outil ; exclure cet outil permet donc aux autres outils du serveur de continuer à fonctionner. Pour le message qui nomme l’outil et les moyens de raccourcir son nom complet, consultez Nom d’outil MCP de plus de 128 caractères.

Exiger une approbation pour un outil spécifique

Si vous créez un serveur MCP, vous pouvez marquer un outil comme nécessitant une approbation explicite à chaque appel en définissant _meta["anthropic/requiresUserInteraction"] sur true dans l’entrée de réponse tools/list de l’outil. La valeur doit être le booléen JSON true ; toute autre valeur est ignorée. Claude Code affiche l’invite de permission de cet outil à chaque appel, même dans les modes de permission acceptEdits, auto et bypassPermissions, et n’offre pas d’option « ne plus demander » pour celui-ci. Les règles d’autorisation qui correspondent à l’outil ne contournent pas non plus l’invite. En mode dontAsk, qui ne demande jamais, Claude Code refuse l’appel à la place. L’invite doit atteindre une personne. En mode non interactif avec --permission-prompt-tool, un résultat allow de l’outil d’invite de permission pour un outil signalé est converti en refus avec le message MCP tool requires user interaction; not supported via --permission-prompt-tool. Le callback canUseTool du SDK Agent reçoit bien ces appels et peut les approuver, car votre application SDK est censée les montrer à un utilisateur. Utilisez ceci pour les outils dont l’invite de permission est elle-même le point, comme une étape de consentement ou d’octroi d’accès où l’approbation automatique signifierait qu’aucun humain n’a jamais accepté. Les autres outils du même serveur conservent leur comportement de permission normal. L’entrée tools/list suivante marque un outil comme nécessitant toujours une approbation.

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

Certaines surfaces, comme Remote Control et les applications construites sur le SDK Agent, vous permettent normalement d’approuver les appels d’outils en un seul geste. Pour un outil marqué avec cette annotation, Claude Code retient l’action en un geste et affiche l’invite de permission complète de l’outil à la place, de sorte que l’approbation provient toujours d’une personne répondant à l’invite plutôt que d’un geste. Claude Code retient l’approbation en un geste de la même manière pour toute demande de permission que seul le dialogue du terminal peut afficher complètement, comme celle qui porte un avertissement de sécurité ou une option d’autorisation permanente que la surface distante ne peut pas afficher. Vous répondez à cette demande dans le dialogue du terminal plutôt que depuis Remote Control.

Marquer les outils qui peuvent être appelés deux fois sans risque

Si vous développez un serveur MCP, marquez les outils qui peuvent être appelés deux fois sans risque afin que Claude Code puisse répéter un appel qui était en attente lorsqu’une connexion s’est fermée. Claude Code peut répéter un tel appel vers un serveur HTTP ou un connecteur claude.ai une seule fois, sur une nouvelle connexion. Un appel que Claude Code ne répète pas peut échouer avec connection closed before the tool call was answered. Pour marquer un outil, définissez l’une de ces annotations sur true dans son entrée tools/list :

idempotentHint : l’outil peut modifier quelque chose, et l’appeler à nouveau avec les mêmes arguments est sans risque
readOnlyHint : l’outil ne modifie rien. Claude Code exécute également les appels de l’outil en parallèle avec d’autres appels en lecture seule.

Par exemple, ces champs dans une entrée tools/list indiquent que l’outil set_issue_status peut être répété sans risque :

{
  "name": "set_issue_status",
  "annotations": {
    "idempotentHint": true
  }
}

Répondre aux demandes d’élicitation MCP

Les serveurs MCP peuvent vous demander une entrée structurée au cours d’une tâche en utilisant l’élicitation. Lorsqu’un serveur a besoin d’informations qu’il ne peut pas obtenir seul, Claude Code affiche un dialogue interactif dans le terminal et transmet votre réponse au serveur. Aucune configuration n’est requise de votre côté : les dialogues d’élicitation apparaissent automatiquement lorsqu’un serveur les demande. Les serveurs peuvent demander une entrée de deux façons :

Mode formulaire : Claude Code affiche un dialogue avec des champs de formulaire définis par le serveur (par exemple, une invite de nom d’utilisateur et de mot de passe). Remplissez les champs et soumettez.
Mode URL : Claude Code vous demande si vous souhaitez ouvrir un lien dans votre navigateur. Les serveurs utilisent ce mode pour un flux qui se termine en dehors du terminal, comme la connexion.

En mode URL, Claude Code transmet l’URL en tant qu’argument de ligne de commande au gestionnaire d’URL de votre système, et limite la longueur de cet argument. Lorsque l’URL, une fois échappée pour la ligne de commande, dépasse cette limite, vous ne pouvez que refuser la demande. Chaque caractère qui doit être échappé, tel que % ou &, compte quatre fois vers la limite : son propre caractère plus trois caractères d’échappement. Une URL sans aucun d’entre eux atteint la limite à environ 8 000 caractères. Une URL construite largement à partir d’échappements de pourcentage, où chaque tiers caractère est un %, l’atteint à environ 4 000. Pour répondre automatiquement aux demandes d’élicitation sans afficher de dialogue, utilisez le hook Elicitation. Si vous créez un serveur MCP qui utilise l’élicitation, consultez la spécification d’élicitation MCP pour les détails du protocole et les exemples de schéma.

Répondre à une demande d’élicitation dans une session cloud

Lorsque la tâche de Claude dans votre session cloud attend une requête d’un serveur MCP, le serveur a besoin de quelque chose de votre part, comme une valeur ou une connexion. Si la demande apparaît sous forme de carte sur claude.ai/code ou dans l’onglet Code de l’application Desktop, répondez sur la carte :

Mode formulaire : remplissez les champs, puis cliquez sur Submit
Mode URL : cliquez sur Open link, terminez le flux qui s’ouvre, puis cliquez sur I’m done, continue sur la carte

Pour refuser la demande, cliquez sur Decline. Claude reprend dès que le serveur répond. Si vous ne voyez de carte à aucun de ces deux endroits, vous ne pouvez pas y répondre à la demande. Dans votre propre session, cliquez sur le bouton d’arrêt à cet endroit pour mettre fin au tour.

Modes d’élicitation déclarés par Claude Code

Si vous créez un serveur MCP, les capacités client que Claude Code envoie lors de la connexion indiquent à votre serveur quels modes d’élicitation il peut demander. Claude Code déclare elicitation: {form: {}, url: {}} sur les connexions suivantes, de sorte qu’un serveur sur l’une d’entre elles peut demander les deux modes :

Les connexions qui utilisent la révision de protocole 2026-07-28
Les connexions utilisant les révisions de protocole antérieures, 2025-11-25 et plus anciennes, vers les serveurs stdio, sse, http et ws présents dans la configuration MCP de Claude Code d’un utilisateur. Nécessite Claude Code v2.1.287 ou une version ultérieure

Sur ses autres connexions utilisant les révisions antérieures, comme celles vers les connecteurs claude.ai, Claude Code déclare simplement elicitation: {}, ce qui autorise les demandes d’élicitation en mode formulaire uniquement. Un serveur développé avec le SDK Java MCP 0.17.0 ou une version antérieure peut refuser une déclaration contenant form et url. Consultez MCP server rejected the elicitation capability.

Utiliser les ressources MCP

Les serveurs MCP peuvent exposer des ressources que vous pouvez référencer en utilisant des mentions @, de la même manière que vous référencez des fichiers.

Référencer les ressources MCP

Lister les ressources disponibles

Tapez @ dans votre invite pour voir les ressources disponibles de tous les serveurs MCP connectés. Les ressources apparaissent aux côtés des fichiers dans le menu d’autocomplétion.

Référencer une ressource spécifique

Utilisez le format @server:protocol://resource/path pour référencer une ressource :

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

Références de ressources multiples

Vous pouvez référencer plusieurs ressources dans une seule invite :

Compare @postgres:schema://users with @docs:file://database/user-model

Conseils :

Les ressources sont automatiquement récupérées et incluses en tant que pièces jointes lorsqu’elles sont référencées
Les chemins de ressources sont recherchables de manière floue dans l’autocomplétion de mention @
Claude Code fournit automatiquement des outils pour lister et lire les ressources MCP lorsque les serveurs les supportent
Les ressources peuvent contenir n’importe quel type de contenu fourni par le serveur MCP (texte, JSON, données structurées, etc.)

Les ressources de l’interface utilisateur des applications MCP sont des entrées avec un URI ui:// ou le type de média text/html;profile=mcp-app : des pages destinées à être rendues par une application hôte plutôt que du contenu à lire par Claude. Elles n’apparaissent pas dans les suggestions @ ou dans les résultats de l’outil de liste des ressources, et un serveur qui n’offre que des ressources d’interface utilisateur affiche une liste de ressources vide. La lecture d’une ressource d’interface utilisateur par son URI fonctionne toujours.

Mettre à l’échelle avec la recherche d’outils MCP

La recherche d’outils maintient l’utilisation du contexte MCP faible en reportant les définitions d’outils jusqu’à ce que Claude en ait besoin. Seuls les noms d’outils et les instructions du serveur se chargent au démarrage de la session, donc l’ajout de plus de serveurs MCP a un impact minimal sur votre fenêtre de contexte. Claude Code n’impose pas de limite fixe d’outils par serveur ; la limite pratique est votre budget de fenêtre de contexte.

La recherche d’outils n’est pas prise en charge sur les déploiements Microsoft Foundry hébergés sur Azure, qui la rejettent côté serveur : Claude Code détecte le rejet et charge les outils MCP en amont pour ce déploiement à la place. ENABLE_TOOL_SEARCH ne peut pas contourner cela, puisque le rejet provient du déploiement lui-même.

Recherche d’outils pour les auteurs de serveurs MCP

Si vous créez un serveur MCP, le champ des instructions du serveur devient plus utile avec la recherche d’outils activée. Les instructions du serveur aident Claude à comprendre quand rechercher vos outils, de la même manière que les skills fonctionnent. Ajoutez des instructions de serveur claires et descriptives qui expliquent :

Quelle catégorie de tâches vos outils gèrent
Quand Claude doit rechercher vos outils
Les capacités clés que votre serveur fournit

Claude Code tronque une description d’outil ou des instructions de serveur qui dépassent ces limites par défaut, et Claude ne voit que le texte situé avant la coupure :

Instructions du serveur, et description d’un outil qui se charge en amont : 4 096 caractères
Description d’un outil que Claude charge via la recherche d’outils : 16 384 caractères

Gardez les descriptions et les instructions concises, et placez les détails critiques près du début. Lorsque la recherche d’outils compare la requête de Claude à la description d’un outil, elle ne lit que la partie comprise dans la limite la plus courte : placez donc aussi près du début les mots que Claude rechercherait. Un outil se charge en amont et conserve la limite la plus courte dès lors qu’il n’est pas reporté, par exemple lorsque la recherche d’outils est désactivée, lorsque l’outil est marqué pour se charger en amont, ou lorsque son serveur est exempté du report. Avant v2.1.296, la limite la plus courte était de 2 048 caractères, et avant v2.1.295, elle s’appliquait à chaque description d’outil, y compris celle d’un outil chargé via la recherche d’outils.

Modifier les limites de longueur des descriptions

Pour modifier les limites par défaut de 4 096 et 16 384 caractères pour les serveurs MCP de votre session, définissez CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH sur un nombre de caractères. Claude Code utilise ce nombre pour les deux limites. Avec 8192, par exemple, vous augmentez la limite de 4 096 caractères applicable aux instructions du serveur et aux descriptions d’outils chargés en amont, et vous abaissez la limite de 16 384 caractères applicable aux descriptions d’outils chargés via la recherche d’outils. Cette variable nécessite Claude Code v2.1.280 ou ultérieur. Les descriptions et les instructions de certains des serveurs MCP qu’Anthropic héberge sur api.anthropic.com parviennent à Claude dans leur intégralité, et la définition de cette variable ne les tronque pas.

Marquer un outil pour qu’il se charge en amont ou reste reporté

Pour contrôler la manière dont l’un des outils de votre serveur se charge, définissez "anthropic/alwaysLoad" dans l’objet _meta de cet outil. La personne qui ajoute votre serveur à Claude Code peut également définir alwaysLoad pour l’ensemble du serveur dans sa configuration, et son paramètre peut remplacer le vôtre :

Valeur de votre outil	Ce qui se passe
`true`	L’outil se charge en amont. Le démarrage n’attend pas votre serveur en raison de cette valeur. La personne qui configure votre serveur peut toujours reporter tous ses outils
`false`	L’outil reste reporté lorsque la configuration de cette personne définit `"alwaysLoad": true`. Cela s’applique lorsque votre serveur est transmis avec `--mcp-config`, fourni par une application Agent SDK, ou fourni par un plugin. Sur les autres serveurs, l’outil se charge en amont. Nécessite Claude Code v2.1.285 ou ultérieur

L’entrée tools/list suivante demande le chargement en amont d’un outil :

{
  "name": "search_tickets",
  "description": "Searches the ticket tracker by keyword",
  "_meta": {
    "anthropic/alwaysLoad": true
  }
}

Configurer la recherche d’outils

La recherche d’outils est activée par défaut : les outils MCP sont reportés et découverts à la demande. Définir CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS maintient la recherche d’outils désactivée. Vous ne pouvez pas la contourner en définissant ENABLE_TOOL_SEARCH vous-même. Sur Claude Code v2.1.227 ou ultérieur, votre organisation peut maintenir la recherche d’outils activée malgré cette variable via les paramètres gérés. Dans une session qui reçoit la configuration HIPAA, la recherche d’outils est désactivée, et ni ENABLE_TOOL_SEARCH ni les paramètres gérés ne la réactivent. Désactiver les capacités de pré-version couvre où le remplacement s’applique et ce que la variable supprime. Claude Code utilise la recherche d’outils sur Claude Opus 4, Claude Sonnet 4, Claude Haiku 4.5 et les modèles ultérieurs, ou sur Opus 4.5, Sonnet 4.5, Haiku 4.5 et les modèles ultérieurs sur la plateforme Agent de Google Cloud. Sur les modèles antérieurs, Claude Code charge tous les outils MCP en amont, et ENABLE_TOOL_SEARCH=true ne contourne pas cela. Sur la plateforme Agent de Google Cloud, Claude Code décide par génération de modèle :

Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, et ultérieur : la recherche d’outils est activée par défaut, comme sur l’API Anthropic.
Modèles Agent Platform antérieurs : Claude Code charge tous les outils MCP en amont, car leurs piles de service rejettent l’en-tête bêta requis. ENABLE_TOOL_SEARCH=true ne contourne pas cela.

Avant v2.1.221, Claude Code désactivait la recherche d’outils pour tous les modèles sur la plateforme Agent de Google Cloud sauf si vous définissiez ENABLE_TOOL_SEARCH=true. Contrôlez le comportement de la recherche d’outils avec la variable d’environnement ENABLE_TOOL_SEARCH :

Valeur	Comportement
(non défini)	Tous les outils MCP reportés et chargés à la demande. Chargés en amont sur les modèles antérieurs à Opus 4 et Sonnet 4, sur les modèles Agent Platform antérieurs, et sur les déploiements Microsoft Foundry hébergés sur Azure
`true`	Outils MCP reportés, avec les mêmes solutions de repli que (non défini)
`auto`	Mode seuil. Les outils qui seraient autrement reportés se chargent en amont tant que leurs définitions totalisent moins de 10 % de la fenêtre de contexte. À 10 % ou plus, la recherche d’outils s’active, et ces outils peuvent rester reportés même si le total repasse sous 10 %
`auto:N`	Mode seuil avec un pourcentage personnalisé, où `N` est 0-100. Par exemple, `auto:5` pour 5 %
`false`	Tous les outils MCP chargés en amont, pas de report

# Utiliser un seuil personnalisé de 5 %
ENABLE_TOOL_SEARCH=auto:5 claude

# Désactiver complètement la recherche d'outils
ENABLE_TOOL_SEARCH=false claude

Ou définissez la valeur dans le champ env de votre settings.json. Vous pouvez également désactiver l’outil ToolSearch spécifiquement :

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

Si vous refusez ToolSearch ou l’omettez de --tools, les outils MCP se chargent en amont à la place, mais une requête peut encore contenir une entrée defer_loading fictive. Si une passerelle rejette cette entrée, consultez Recherche d’outils via une passerelle LLM.

Recherche d’outils via une passerelle LLM

Ces cas sont traités ailleurs :

Vous avez défini CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS : consultez son effet sur la recherche d’outils
Une requête a échoué avec une erreur qui mentionne defer_loading ou tool_reference : consultez Extra inputs are not permitted

Lorsque ANTHROPIC_BASE_URL pointe vers une passerelle, Claude Code s’attend à ce que la passerelle transmette les champs d’outil defer_loading et les blocs tool_reference avec l’en-tête anthropic-beta. La recherche d’outils est activée par défaut derrière la passerelle : les outils MCP sont donc reportés et les requêtes incluent ces champs et ces blocs. Avant v2.1.304, la recherche d’outils était désactivée derrière une passerelle sauf si ENABLE_TOOL_SEARCH valait true, auto ou auto:N. Sur v2.1.305 ou ultérieur, Claude Code peut réessayer une requête sans la recherche d’outils après une erreur 400 ou 422. Lorsque la nouvelle tentative fonctionne, rien ne s’affiche à l’écran et vous n’avez rien à faire : les outils MCP se chargent en amont à la place. Claude Code réessaie la recherche d’outils plus tard, au prix d’une autre requête rejetée.

Outils qui restent reportés sous le seuil `ENABLE_TOOL_SEARCH=auto`

Si /context marque des outils comme (deferred) ou (loaded on-demand) alors que leurs définitions totalisent moins que le seuil auto, c’est que la recherche d’outils était déjà activée dans cette conversation et qu’elle est restée activée. Le total peut baisser ultérieurement, par exemple pendant que les serveurs MCP se reconnectent après la reprise d’une session. Vous n’avez rien à faire : Claude charge chacun de ces outils lorsqu’une tâche en a besoin.

Exempter un serveur du report

Si les outils d’un serveur doivent toujours être visibles pour Claude sans une étape de recherche, définissez alwaysLoad à true dans la configuration de ce serveur. Les outils du serveur se chargent alors dans le contexte indépendamment du paramètre ENABLE_TOOL_SEARCH. Utilisez ceci pour un petit nombre d’outils que Claude doit utiliser à chaque tour, puisque chaque outil en amont consomme du contexte qui serait autrement disponible pour votre conversation. L’entrée .mcp.json suivante exempte un serveur HTTP tout en laissant les autres serveurs reportés :

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

Le champ alwaysLoad est disponible sur tous les types de serveurs. Définir alwaysLoad: true fait également attendre le démarrage des outils du serveur, limité au délai d’expiration de connexion standard de 5 secondes, puisqu’ils doivent être présents lors de la construction du premier prompt. Un serveur distant avec une entrée cached valide fournit ses outils à partir du cache sans se connecter, donc il ne retarde pas le démarrage. Les autres serveurs se connectent en arrière-plan par défaut ; définissez MCP_CONNECTION_NONBLOCKING=0 pour faire attendre le démarrage pour eux aussi.

Reporter les outils d’un serveur

Pour garder tous les outils d’un serveur derrière la recherche d’outils, définissez "alwaysLoad": false dans l’entrée de ce serveur dans votre configuration MCP. Cela inclut les outils que l’auteur du serveur a marqués pour se charger en amont. Si vous omettez alwaysLoad, ces outils marqués se chargent en amont. Nécessite Claude Code v2.1.287 ou ultérieur.

Utiliser les invites MCP comme commandes

Les serveurs MCP peuvent exposer des invites qui deviennent disponibles en tant que commandes dans Claude Code. Les invites d’un serveur nommé anthropic-skills n’apparaissent pas, car Claude Code réserve ce nom pour les skills synchronisées depuis claude.ai. Les outils du serveur fonctionnent toujours. Renommez le serveur dans votre configuration MCP pour lister ses invites.

Exécuter les invites MCP

Découvrir les invites disponibles

Tapez / pour voir les commandes disponibles, y compris celles des serveurs MCP. Claude Code répertorie chaque invite MCP sous la forme /servername:promptname (MCP). Taper /mcp__servername__promptname l’exécute également.

Exécuter une invite sans arguments

/mcp__github__list_prs

Exécuter une invite avec des arguments

De nombreuses invites acceptent des arguments. Passez-les séparés par des espaces après la commande. Claude Code divise les arguments sur les espaces, donc chaque argument est un seul jeton :

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

Conseils :

Les invites MCP sont découvertes dynamiquement à partir des serveurs connectés
Les arguments sont analysés en fonction des paramètres définis de l’invite
Les résultats de l’invite sont injectés directement dans la conversation
Sous la forme /mcp__servername__promptname, Claude Code remplace tout caractère du nom du serveur en dehors de A-Z, a-z, 0-9, _ et - par _, et utilise le nom de l’invite tel que le serveur le déclare

Configuration MCP gérée

Pour les organisations qui ont besoin d’un contrôle centralisé sur les serveurs MCP auxquels les utilisateurs peuvent se connecter, consultez Configuration MCP gérée. Elle couvre le déploiement d’un ensemble fixe de serveurs avec managed-mcp.json, la fourniture de serveurs à chaque utilisateur avec managedMcpServers, la restriction des serveurs avec allowedMcpServers et deniedMcpServers, et ce que les utilisateurs voient lorsqu’un serveur est bloqué.

​Ce que vous pouvez faire avec MCP

​Trouver et créer des serveurs MCP

​Installation des serveurs MCP

​Option 1 : Ajouter un serveur HTTP distant

​Option 2 : Ajouter un serveur SSE distant

​Option 3 : Ajouter un serveur stdio local

​Comment Claude Code arrête un serveur stdio

​Option 4 : Ajouter un serveur WebSocket distant

​Ajouter un serveur à partir d’instructions de configuration écrites pour un autre client

​Ajouter un serveur à partir d’une URL

​Ajouter un serveur à partir d’une commande npx, uvx, ou binaire

​Ajouter un serveur à partir d’un bloc JSON mcpServers

​Gestion de vos serveurs

​État du serveur

​Approbations des serveurs de projet et confiance de l’espace de travail

​Détail de l’état du serveur

​Avertissements de configuration

​Disponibilité des outils

​Désactiver un serveur sans le supprimer

​Runtimes clients MCP

​Mises à jour dynamiques des outils

​Flux de notification sur le runtime v2

​Reconnexion automatique

​Déconnexions en cours de session d’un serveur distant

​Échecs de première connexion

​Serveurs stdio qui se terminent ou ne démarrent pas

​Requêtes de découverte échouées

​Réessayer vous-même les serveurs en échec

​Comment Claude apprend qu’un serveur a échoué

​Pousser des messages avec des canaux

​Limites de temps des appels d’outils MCP

​Mise en arrière-plan automatique des appels d’outils longs

​Tâches MCP exécutées sur le serveur

​Arrêter une tâche MCP ou obtenir son résultat

​Répondre à une question d’une tâche MCP

​Quitter, effacer ou reprendre pendant l’exécution d’une tâche MCP

​Ce dont un appel a besoin pour devenir une tâche MCP

​Messages de statut d’une tâche MCP

​Limites de temps des tâches MCP

​Faire attendre Claude le résultat d’une tâche MCP

​Tâches MCP pour les auteurs de serveurs

​Répondre à l’appel avec une tâche

​Signaler le statut, les résultats et les questions

​Serveurs MCP fournis par les plugins

​Portées d’installation MCP

​Portée locale

​Portée du projet

​Portée utilisateur

​Hiérarchie de portée et précédence

​Expansion des variables d’environnement dans .mcp.json

​Exemple avec expansion de variable

​Variables non définies sans valeur par défaut

​Variables définies sur une chaîne vide

​Variables d’identification qui se lisent comme vides

​Comment les références apparaissent dans /mcp et la sortie CLI

​Exemples pratiques

​Exemple : Se connecter à GitHub pour les révisions de code

​Exemple : Interroger votre base de données PostgreSQL

​S’authentifier auprès des serveurs MCP distants

​S’authentifier à partir de la ligne de commande

​Utiliser un port de rappel OAuth fixe

​Utiliser les identifiants OAuth pré-configurés

​Remplacer la découverte des métadonnées OAuth

​Restreindre les scopes OAuth

​Utiliser OAuth avec un serveur derrière un proxy d’authentification

​Utiliser des en-têtes dynamiques pour l’authentification personnalisée

​Où l’assistant s’exécute

​Quelles variables un assistant peut lire

​Faire confiance à un dossier avant que son headersHelper s’exécute

​Se connecter à un serveur MCP derrière une passerelle qui exige un en-tête

​Ajouter des serveurs MCP à partir de la configuration JSON

​Importer les serveurs MCP à partir de Claude Desktop

​Utiliser les serveurs MCP depuis claude.ai

​Comment les connecteurs atteignent Claude Code

​Contrôles d’organisation sur les outils de connecteur

​Désactiver les connecteurs claude.ai

​Utiliser Claude Code comme serveur MCP

​Lire la sortie d’une commande en arrière-plan en tant que client MCP

​Limites de sortie MCP et avertissements

​Augmenter la limite pour un outil spécifique

Ce que vous pouvez faire avec MCP

Trouver et créer des serveurs MCP

Installation des serveurs MCP

Option 1 : Ajouter un serveur HTTP distant

Option 2 : Ajouter un serveur SSE distant

Option 3 : Ajouter un serveur stdio local

Comment Claude Code arrête un serveur stdio

Option 4 : Ajouter un serveur WebSocket distant

Ajouter un serveur à partir d’instructions de configuration écrites pour un autre client

Ajouter un serveur à partir d’une URL

Ajouter un serveur à partir d’une commande `npx`, `uvx`, ou binaire

Ajouter un serveur à partir d’un bloc JSON `mcpServers`

Gestion de vos serveurs

État du serveur

Approbations des serveurs de projet et confiance de l’espace de travail

Détail de l’état du serveur

Avertissements de configuration

Disponibilité des outils

Désactiver un serveur sans le supprimer

Runtimes clients MCP

Mises à jour dynamiques des outils

Flux de notification sur le runtime v2

Reconnexion automatique

Déconnexions en cours de session d’un serveur distant

Échecs de première connexion

Serveurs stdio qui se terminent ou ne démarrent pas

Requêtes de découverte échouées

Réessayer vous-même les serveurs en échec

Comment Claude apprend qu’un serveur a échoué

Pousser des messages avec des canaux

Limites de temps des appels d’outils MCP

Mise en arrière-plan automatique des appels d’outils longs

Tâches MCP exécutées sur le serveur

Arrêter une tâche MCP ou obtenir son résultat

Répondre à une question d’une tâche MCP

Quitter, effacer ou reprendre pendant l’exécution d’une tâche MCP

Ce dont un appel a besoin pour devenir une tâche MCP

Messages de statut d’une tâche MCP

Limites de temps des tâches MCP

Faire attendre Claude le résultat d’une tâche MCP

Tâches MCP pour les auteurs de serveurs

Répondre à l’appel avec une tâche

Signaler le statut, les résultats et les questions

Serveurs MCP fournis par les plugins

Portées d’installation MCP

Portée locale

Portée du projet

Portée utilisateur

Hiérarchie de portée et précédence

Expansion des variables d’environnement dans `.mcp.json`

Exemple avec expansion de variable

Variables non définies sans valeur par défaut

Variables définies sur une chaîne vide

Variables d’identification qui se lisent comme vides

Comment les références apparaissent dans `/mcp` et la sortie CLI

Exemples pratiques

Exemple : Se connecter à GitHub pour les révisions de code

Exemple : Interroger votre base de données PostgreSQL

S’authentifier auprès des serveurs MCP distants

S’authentifier à partir de la ligne de commande

Utiliser un port de rappel OAuth fixe

Utiliser les identifiants OAuth pré-configurés

Remplacer la découverte des métadonnées OAuth

Restreindre les scopes OAuth

Utiliser OAuth avec un serveur derrière un proxy d’authentification

Utiliser des en-têtes dynamiques pour l’authentification personnalisée

Où l’assistant s’exécute

Quelles variables un assistant peut lire

Faire confiance à un dossier avant que son headersHelper s’exécute

Se connecter à un serveur MCP derrière une passerelle qui exige un en-tête

Ajouter des serveurs MCP à partir de la configuration JSON

Importer les serveurs MCP à partir de Claude Desktop

Utiliser les serveurs MCP depuis claude.ai

Comment les connecteurs atteignent Claude Code

Contrôles d’organisation sur les outils de connecteur

Désactiver les connecteurs claude.ai

Utiliser Claude Code comme serveur MCP

Lire la sortie d’une commande en arrière-plan en tant que client MCP

Limites de sortie MCP et avertissements

Augmenter la limite pour un outil spécifique