Commande claude mcp add : portées, utilisateur ou projet, et serveurs HTTP

Vous collez l’URL d’un serveur dans claude mcp add, vous appuyez sur Entrée, et le serveur apparaît dans un projet mais disparaît dans le suivant. Ou il atterrit dans le dépôt d’un coéquipier et demande une approbation que personne n’attendait. Presque tous les résultats déroutants de cette commande remontent à deux décisions : la portée que vous avez choisie et le transport que vous avez utilisé. Cet article passe la commande en revue option par option, montre où chaque portée stocke ses données, explique comment les portées utilisateur et projet interagissent, et donne des exemples fonctionnels pour les serveurs HTTP et stdio, y compris la particularité de Windows qui piège beaucoup de monde.

Ce que fait la commande add

claude mcp add enregistre un serveur Model Context Protocol auprès de Claude Code afin que l’assistant puisse appeler ses outils, lire ses ressources et exécuter ses prompts. La commande n’installe rien par elle-même. Elle écrit une petite entrée de configuration, que Claude Code lit au prochain démarrage d’une session ou lorsque vous vous reconnectez depuis le menu /mcp.

Trois décisions déterminent chaque appel :

• Transport : la manière dont Claude Code communique avec le serveur (http, sse ou stdio).
• Portée : l’endroit où l’entrée est stockée et qui peut la voir (local, project ou user).
• Nom : l’étiquette que vous saisirez plus tard dans claude mcp get, claude mcp remove et le menu /mcp.

La syntaxe de base

Deux formes suffisent pour presque tout ce que vous lancerez :

# Remote server reached over a URL
claude mcp add [options] <name> <url>

# Local process started by Claude Code
claude mcp add [options] <name> -- <command> [args...]

Copier le prompt

Placez --transport, --scope et --env avant le nom du serveur. Pour les processus locaux, le double tiret indique à l’analyseur que tout ce qui suit appartient au serveur et non à Claude Code.

💡 Astuce : indiquez --transport à chaque fois, même lorsqu’une valeur par défaut conviendrait. Une option explicite rend la commande identique dans l’historique du shell, les fichiers README et les échanges d’équipe, quelle que soit la version utilisée par chacun.

Les trois portées en un coup d’œil

Claude Code stocke chaque serveur à l’un de trois emplacements, et l’option --scope (forme courte -s) choisit cet emplacement. Si vous omettez l’option, vous obtenez local.

Le mot local prête à confusion, car il évoque « sur ma machine », et la portée utilisateur est aussi sur votre machine. La différence tient à l’étendue d’usage. La portée locale est privée et limitée à un seul projet, tandis que la portée utilisateur est privée et vous suit dans chaque dépôt.

La portée locale : la valeur par défaut

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

Copier le prompt

Utilisez la portée locale pour les expérimentations, pour les serveurs liés à un seul dépôt et pour tout ce qui contient un identifiant personnel. Rien n’est écrit dans le dépôt, donc aucun risque de commiter un jeton par erreur. C’est aussi la portée par défaut si vous oubliez l’option, ce qui explique pourquoi un serveur ajouté à la hâte semble disparaître lorsque vous ouvrez un autre dossier.

La portée projet : partagée dans Git

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

Copier le prompt

Cette commande crée ou met à jour .mcp.json à la racine du projet. Commitez-le et chaque coéquipier obtiendra la même liste de serveurs après un pull. Comme un fichier présent dans un dépôt peut lancer des processus sur votre machine, Claude Code demande à chaque personne d’approuver les serveurs projet dès leur première apparition. Si quelqu’un a refusé par erreur, claude mcp reset-project-choices efface les réponses précédentes afin que l’invite réapparaisse.

La portée utilisateur : partout où vous travaillez

claude mcp add --scope user --transport http notion https://mcp.notion.com/mcp

Copier le prompt

La portée utilisateur convient aux outils personnels que vous voulez dans chaque dépôt : une application de notes, un serveur de recherche dans la documentation, une aide pour le navigateur. L’entrée se trouve dans ~/.claude.json, suit votre compte sur cette machine et ne touche jamais un dépôt.

Utilisateur ou projet : lequel l’emporte ?

Le choix entre portée utilisateur et portée projet revient à une seule question : qui d’autre a besoin de ce serveur ? Si la réponse est « toute personne qui clone ce dépôt », utilisez la portée projet. Si la réponse est « moi seul, mais dans chaque dépôt », utilisez la portée utilisateur. Si la réponse est « moi seul, et seulement ici », restez sur la portée locale.

Quelle portée prime

Lorsque le même nom de serveur existe dans plusieurs portées, Claude Code utilise la définition la plus spécifique : locale l’emporte sur projet, et projet l’emporte sur utilisateur. Cet ordre vous permet de remplacer une entrée partagée sur votre propre machine sans modifier un fichier que tout le monde utilise.

Supposons que le fichier .mcp.json de l’équipe définisse un serveur nommé docs qui pointe vers la production. Vous pouvez exécuter ceci dans votre propre copie de travail :

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

Copier le prompt

L’entrée locale l’emporte, donc votre session communique avec la préproduction, tandis que vos coéquipiers continuent de communiquer avec la production. Supprimez l’entrée locale et vous revenez à l’entrée partagée.

Partager via .mcp.json

Une entrée de portée projet est du JSON simple, ce qui signifie que vous pouvez aussi l’écrire à la main :

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${DOCS_TOKEN}"
      }
    }
  }
}

Copier le prompt

Claude Code développe ${VAR} et ${VAR:-default} dans command, args, url, headers et env. C’est le schéma sûr pour les fichiers partagés : commitez la structure, et laissez chaque personne fournir son propre secret via une variable d’environnement. Un vrai jeton collé dans .mcp.json finit dans l’historique git, et la seule solution fiable consiste à le révoquer et le remplacer.

Ajouter des serveurs HTTP

HTTP est le transport recommandé pour les serveurs distants : pas de processus local, pas de runtime à installer, et le fournisseur gère les mises à jour. La plupart des serveurs MCP hébergés publient une URL se terminant par /mcp, et c’est cette adresse que vous transmettez à la commande.

L’option de transport

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

Copier le prompt

Si la documentation d’un fournisseur affiche encore une adresse /sse, vérifiez si le même service propose un point de terminaison /mcp avant d’enregistrer l’ancienne. Les serveurs utilisant le transport déprécié continuent de fonctionner pour le moment, mais les nouvelles configurations ne devraient pas commencer par là.

En-têtes et jetons Bearer

Les serveurs qui acceptent un identifiant statique le lisent dans un en-tête de requête. Transmettez-le avec --header (forme courte -H), et répétez l’option si vous en avez besoin de plusieurs :

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

claude mcp add --transport http api https://example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "X-Team: platform"

Copier le prompt

💡 Attention au shell : si vous saisissez $GITHUB_TOKEN entre guillemets doubles, votre shell le développe avant que Claude Code ne voie la commande, de sorte que l’entrée enregistrée contient le vrai jeton. Pour tout ce qui est partagé, écrivez plutôt la forme ${VAR} dans .mcp.json.

S’authentifier avec OAuth

De nombreux serveurs hébergés se passent de jetons statiques et utilisent OAuth. Ajoutez le serveur sans en-têtes, démarrez Claude Code, puis exécutez /mcp. Choisissez le serveur dans la liste et suivez la connexion dans le navigateur. Claude Code stocke les identifiants obtenus et les renouvelle pour vous : rien à coller dans un fichier de configuration, et rien à commiter par erreur.

Serveurs stdio et variables d’environnement

Avec stdio, Claude Code lance le serveur comme processus enfant et communique avec lui via l’entrée et la sortie standard. Choisissez-le pour les outils qui doivent tourner sur votre machine : un assistant de base de données local, un outil de système de fichiers, ou un script que vous avez écrit vous-même. Les variables d’environnement sont transmises avec l’option --env (forme courte -e).

Le séparateur double tiret

claude mcp add --transport stdio --env API_TOKEN=YOUR_TOKEN myserver \
  -- npx -y my-mcp-server

Copier le prompt

Tout ce qui précède -- s’adresse à Claude Code. Tout ce qui le suit correspond à la commande exacte qui lance votre serveur, arguments compris. Oublier le séparateur est l’erreur la plus fréquente avec stdio :

# Wrong: --port is parsed as a Claude Code option
claude mcp add --transport stdio myserver npx server --port 8080

# Right: the server command sits after the double dash
claude mcp add --transport stdio myserver -- npx server --port 8080

Copier le prompt

Windows exige cmd /c

Sous Windows natif (pas WSL), npx est un script batch et non un exécutable à proprement parler, donc Claude Code ne peut pas le lancer directement. Encapsulez la commande dans cmd /c :

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Copier le prompt

Sans cette enveloppe, vous voyez généralement une erreur « Connection closed » dans /mcp, qui ressemble à un bogue du serveur alors qu’il s’agit seulement d’un échec de lancement. La même correction s’applique si vous écrivez l’entrée à la main : définissez "command": "cmd" et faites commencer args par "/c", puis "npx".

Gérer les serveurs après l’ajout

Enregistrer un serveur ne représente que la moitié du travail. Trois commandes gèrent le reste de son cycle de vie :

claude mcp list            # every server and its connection status
claude mcp get docs        # details for one server
claude mcp remove docs     # delete it

Copier le prompt

Dans une session, /mcp affiche le même statut en temps réel, et c’est aussi là que vous vous connectez aux serveurs OAuth ou reconnectez un serveur qui s’est déconnecté.

Lister, consulter et supprimer

Exécutez d’abord claude mcp list dès que quelque chose semble anormal. La commande montre ce que Claude Code connaît réellement, toutes portées confondues, pour que vous puissiez savoir immédiatement si le serveur est absent ou simplement en échec. Utilisez claude mcp get <name> pour voir d’où provient une entrée. Si le même nom existe dans plusieurs portées, passez --scope à claude mcp remove pour supprimer la bonne copie.

Le raccourci add-json

Lorsqu’un fournisseur vous remet un extrait JSON, évitez les options et transmettez-le directement à la commande :

claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

Copier le prompt

add-json accepte la même option --scope, ce qui vous permet d’ajouter un extrait en portée utilisateur ou projet en une seule étape. Si vous avez déjà configuré un ensemble de serveurs dans Claude Desktop, claude mcp add-from-claude-desktop les importe de façon interactive sur macOS et WSL.

Corriger les échecs courants

La plupart des échecs entrent dans une courte liste. Identifiez d’abord le symptôme, et ne modifiez les fichiers qu’ensuite.

Lorsque le tableau ne suffit pas à résoudre le problème, effectuez ces quatre vérifications dans l’ordre :

1. claude mcp list pour confirmer que le serveur est enregistré et voir son statut.
2. claude mcp get <name> pour lire la commande ou l’URL exacte qu’utilise Claude Code.
3. /mcp dans une session pour voir l’état de la connexion en direct et vous reconnecter.
4. Collez la commande stdio dans un terminal simple. Si elle échoue là aussi, le problème vient du serveur et non de Claude Code.

Lorsqu’un serveur ne se connecte pas : pour un serveur distant, ouvrez l’URL dans un navigateur ou appelez-la avec curl. Une erreur 401 ou 403 signifie que votre en-tête ou votre connexion est incorrect, une erreur 404 indique généralement que le chemin est faux (/mcp au lieu de /sse), et un délai d’attente pointe vers le réseau. Pour un serveur stdio, la commande exacte que vous avez enregistrée doit s’exécuter seule, avec les mêmes variables d’environnement définies.

Faites travailler Claude et PicassoIA

Une fois les portées bien définies, MCP devient un moyen de donner à Claude de véritables capacités, et les images en sont un bon exemple. PicassoIA expose ses modèles de génération via une API développeur à https://api.picassoia.com/v1 et via des connexions MCP. Les quatre modèles disponibles sur cette plateforme sont PicassoIA Image, PicassoIA Image Editor Pro et deux modèles vidéo. Les tâches s’exécutent de manière asynchrone : Claude soumet une prédiction, l’interroge, puis lit le résultat final. La plateforme autorise 5 prédictions simultanées par compte, partagées entre toutes les connexions ouvertes, de sorte qu’un lot de requêtes issues d’une même session sera mis en file d’attente au lieu de s’exécuter d’un coup.

💡 Astuce sur la portée : la page tarifaire indique que les connexions MCP sont disponibles avec les forfaits Pro+, Elite et Infinite, alors vérifiez votre forfait avant de configurer la connexion. Enregistrez la connexion en portée utilisateur si vous voulez la génération d’images dans chaque dépôt, ou en portée locale si un seul projet en a besoin. Copiez l’URL de connexion depuis votre compte PicassoIA plutôt que de deviner une adresse.

Déboguer avec Claude sur PicassoIA

Vous n’avez pas besoin d’un terminal pour obtenir de l’aide sur une commande claude mcp add qui échoue. Claude Sonnet 5 fonctionne sur PicassoIA et gère très bien ce type de débogage :

1. Ouvrez la page du modèle depuis le lien ci-dessus.
2. Collez la commande exacte que vous avez lancée, ainsi que le message d’erreur de /mcp ou du terminal.
3. Indiquez le système d’exploitation que vous utilisez, et si le serveur est HTTP ou stdio.
4. Demandez la commande corrigée ainsi qu’une explication d’une ligne sur ce qui n’allait pas.
5. Appliquez la correction, puis confirmez-la avec claude mcp list.

Pour un raisonnement plus poussé sur un .mcp.json volumineux, Claude Opus 4.7 est disponible sur la même plateforme, et Claude 4.5 Haiku répond rapidement aux questions de syntaxe simples.

Créez vos propres images

Lire sur les portées est utile, mais le véritable intérêt vient de la possibilité de faire travailler Claude avec des visuels pendant que vous codez. Ouvrez Picasso IA, choisissez un modèle comme PicassoIA Image, et générez quelques images à partir de vos propres prompts. Essayez un visuel d’en-tête pour votre prochain README, une maquette de produit ou une scène façon photo pour un article de blog. Une fois satisfait des résultats, connectez la même capacité à Claude Code via MCP et laissez l’assistant produire des images au sein de votre flux de travail. Expérimentez librement, comparez les modèles côte à côte et conservez les prompts qui fonctionnent.