Vous collez une commande depuis un README, vous appuyez sur Entrée, et Claude Code affiche « Added. ». Puis vous ouvrez une nouvelle session et les outils ont disparu. Quand cela se produit, la configuration MCP de Claude Code se résume généralement à deux questions : dans quelle portée le serveur a été enregistré, et s'il s'est réellement connecté. Ce guide répond aux deux avec de vraies sorties de terminal de Claude Code 2.1.300, en prenant le serveur MCP Atlas Cloud comme exemple.
Points clés
- Exécutez claude mcp add avec un nom de serveur, deux tirets, puis la commande qui démarre le serveur.
- La portée locale est celle par défaut ; ajoutez --scope user pour tous les projets, ou --scope project pour partager .mcp.json.
- La commande claude mcp list affiche l'état en direct de chaque serveur, y compris les connecteurs de votre compte claude.ai.
- Claude Desktop lit son propre claude_desktop_config.json, donc les serveurs ajoutés dans Claude Code restent séparés.
- Le serveur MCP Atlas Cloud ajoute la génération vidéo Seedance 2.5 à Claude Code avec une seule commande.
Où Claude Code stocke la configuration MCP
Chaque serveur que vous ajoutez réside dans l'une de trois portées, et la portée détermine deux choses : quels projets peuvent le voir, et quel fichier le contient. La documentation MCP de Claude Code les définit ainsi.
| Portée | Option | Chargé dans | Enregistré dans | Partagé avec votre équipe |
|---|---|---|---|---|
| Locale (défaut) | --scope local, ou aucune | Le projet actuel seulement | ~/.claude.json, sous le chemin du projet | Non |
| Projet | --scope project | Le projet actuel seulement | .mcp.json à la racine du projet | Oui, via le contrôle de version |
| Utilisateur | --scope user | Tous vos projets | ~/.claude.json | Non |
Sous Windows, ~/.claude.json est le fichier de votre dossier utilisateur, par exemple C:\Users\you\.claude.json. Les entrées locale et utilisateur vont toutes deux dans ce seul fichier, c'est pourquoi « je l'ai ajouté mais il a disparu » signifie généralement que vous l'avez ajouté en local dans un autre dossier.
Lorsqu'un même nom existe dans plusieurs portées, Claude Code utilise une seule définition et ne fusionne pas les champs. La portée locale l'emporte sur celle du projet, et celle du projet l'emporte sur celle de l'utilisateur.
La commande Claude MCP Add, avec Atlas Cloud comme exemple
Atlas Cloud publie atlascloud-mcp, un serveur MCP (source sur GitHub) qui permet à Claude d'envoyer des tâches d'image et de vidéo aux modèles Atlas et de ramener les fichiers finis dans la session. Ce clip est ce que notre configuration finale a produit à partir d'une seule requête dans Claude Code :
Il s'exécute localement via npx, donc la seule installation nécessaire est Node.js 18 ou plus récent et une clé API. Voici la boucle complète d'ajout et de vérification en deux commandes.
Votre clé provient du panneau API Keys dans les paramètres de votre console Atlas Cloud. La liste complète des clients se trouve sur la page de configuration du serveur MCP.
Méthode 1 : Ajouter un serveur local avec claude mcp add
- Exportez votre clé, puis laissez Claude Code ajouter des serveurs MCP en une ligne. Les deux tirets comptent : tout ce qui précède leur est destiné à Claude Code (nom, portée, env), et tout ce qui suit est la commande qui démarre le serveur.
plaintext1export ATLASCLOUD_API_KEY="your-api-key" 2claude mcp add atlascloud --scope user -e ATLASCLOUD_API_KEY=$ATLASCLOUD_API_KEY -- npx -y atlascloud-mcp
2. Vérifiez le résultat. Dans la capture d'écran, la ligne Scope indique « User config (available in all your projects) » et Status indique Connected.
plaintext1claude mcp get atlascloud
Omettez --scope user et le serveur n'existera que dans le dossier depuis lequel vous avez exécuté la commande. L'option -e stocke la clé dans l'entrée du serveur, ainsi le serveur continue de fonctionner dans un terminal où vous ne l'avez pas exportée.
Une note pour les utilisateurs Windows : certains guides vous disent d'envelopper npx dans cmd /c. Sur Windows 11 avec Claude Code 2.1.300, la commande simple ci-dessus s'est connectée du premier coup, sans wrapper nécessaire.
Méthode 2 : Coller un bloc JSON avec claude mcp add-json
De nombreux README MCP et pages de configuration, y compris celui d'Atlas, vous fournissent un bloc JSON plutôt qu'une commande. Passez-le directement à add-json :
plaintext1claude mcp add-json atlascloud '{"command":"npx","args":["-y","atlascloud-mcp"],"env":{"ATLASCLOUD_API_KEY":"your-api-key"}}'
Notre entrée de test est nommée atlascloud-json pour que les deux puissent coexister. Entourez le JSON de guillemets simples dans bash ou zsh. Windows PowerShell 5.1 peut supprimer les guillemets doubles internes, donc exécutez celle-ci depuis Git Bash, WSL ou PowerShell 7.
Configuration du serveur MCP de Claude Code dans .mcp.json
Utilisez la portée projet quand toute une équipe doit disposer du même serveur. Elle écrit .mcp.json à la racine du projet, que vous validez comme n'importe quel fichier de configuration.
Le piège, c'est la clé API. Ne la validez pas. Claude Code développe VARet{VAR} et VARet{VAR:-default} à l'intérieur de .mcp.json, donc la variable d'environnement propre à chaque coéquipier remplit la valeur au lancement. Mettez la valeur de -e entre guillemets simples pour que votre shell transmette le nom de la variable au lieu de votre clé :
plaintext1claude mcp add atlascloud --scope project -e 'ATLASCLOUD_API_KEY=${ATLASCLOUD_API_KEY}' -- npx -y atlascloud-mcp
Un serveur .mcp.json fraîchement créé affiche « Pending approval » et ne se connecte pas tant que quelqu'un n'exécute pas claude dans ce dossier et ne l'approuve pas. C'est une vérification de sécurité : un dépôt cloné ne peut pas lancer de programmes sur votre machine tout seul.
| Vous avez | Utilisez | Aboutit dans |
|---|---|---|
| Une commande d'installation en une ligne | claude mcp add | Locale, ou la portée indiquée |
| Un bloc JSON depuis un README | claude mcp add-json | Locale, ou la portée indiquée |
| Un serveur dont tout le dépôt a besoin | --scope project, puis validez .mcp.json | .mcp.json |
Vérifier vos serveurs avec la commande Claude MCP List
La commande claude mcp list vérifie l'état de vos serveurs configurés et affiche une ligne chacun. L'état en fin de ligne est la partie à lire.
| État | Signification | Que faire |
|---|---|---|
| ✔ Connected | Le serveur a démarré et a répondu | Rien ; ouvrez une nouvelle session et les outils sont là |
| ! Needs authentication | Un serveur distant demande une connexion OAuth | Exécutez /mcp dans Claude Code et choisissez Authenticate |
| ✘ Failed to connect | La commande a échoué ou expiré | Exécutez la commande du serveur à la main pour voir l'erreur |
| ⏸ Pending approval | Une entrée .mcp.json non approuvée | Exécutez claude dans ce dossier et approuvez-la |
Si vous êtes connecté avec un compte claude.ai, la liste inclut aussi les connecteurs de ce compte, chacun précédé de « claude.ai ». Les nôtres en affichaient plus de 20. Pour ne voir que ce que vous avez configuré, définissez ENABLE_CLAUDEAI_MCP_SERVERS=false pour cette session de shell.
Claude Remove MCP : supprimer un serveur de la bonne portée
Ajoutez -s avec la portée quand vous la connaissez, et toujours lorsque le même nom existe dans plusieurs portées.
plaintext1claude mcp remove atlascloud -s user
La dernière ligne de claude mcp get affiche la commande de suppression exacte, portée comprise. Pour les serveurs distants, la suppression efface aussi les jetons OAuth stockés par Claude Code.
Configuration MCP de Claude Desktop dans claude_desktop_config.json
Claude Desktop ne lit pas ~/.claude.json. Il a son propre fichier, et vous le modifiez à la main : ouvrez Settings, choisissez Developer, cliquez sur Edit Config, collez le bloc, puis quittez et rouvrez l'application.
| Système | Emplacement de claude_desktop_config.json |
|---|---|
| macOS | ~/Library/Application Support/Claude/ |
| Windows | %APPDATA%\Claude\ |
plaintext1{ 2 "mcpServers": { 3 "atlascloud": { 4 "command": "npx", 5 "args": ["-y", "atlascloud-mcp"], 6 "env": { 7 "ATLASCLOUD_API_KEY": "your-api-key" 8 } 9 } 10 } 11}
Vous avez déjà des serveurs dans Desktop ? Claude Code peut les copier avec claude mcp add-from-claude-desktop, qui ouvre un sélecteur. La commande ne fonctionne que sur macOS et WSL, donc les utilisateurs de Windows natif collent le même JSON dans add-json à la place. Notre visite guidée vidéo de Claude montre les écrans de paramètres de Desktop étape par étape.
Tester la configuration avec une vidéo Seedance 2.5 depuis Claude Code
Un état Connected prouve seulement que le serveur a démarré. Pour voir une vraie tâche aboutir, nous avons envoyé le clip de la grue du début de ce guide. Avec atlascloud enregistré, Claude Code a appelé Seedance 2.5, le modèle vidéo phare de ByteDance, avec cette requête :
plaintext1Use the atlascloud MCP server to make an 8-second 16:9 video at 720p with bytedance/seedance-2.5/text-to-video, audio on. Prompt: Close-up on a walnut desk at blue hour. A white origami crane folded from graph paper slowly lifts its wings, hops once, then glides off the desk edge past a steaming ceramic mug while rain streaks the window behind. Warm desk-lamp key light, cool window fill, shallow depth of field, 50mm lens, slow push-in, subtle film grain. Sound: soft rain, a paper rustle, a faint lamp hum.
| Étape | Outil appelé par Claude | Ce qui est revenu |
|---|---|---|
| Lire les paramètres du modèle | atlas_get_model_info | Durée de 4 à 30 secondes, résolutions à partir de 480p, audio activé par défaut |
| Soumettre la tâche | atlas_generate_video | Un ID de prédiction |
| Vérifier la tâche | atlas_get_prediction | Un MP4 1280x720 de 8 secondes avec sa propre piste audio |
Le GIF en haut de ce guide est une coupe silencieuse de ce MP4. Vous pouvez exécuter le même prompt à la main dans le playground Seedance 2.5 pour comparer.
Comment ajouter des skills à Claude Code à côté de MCP
Un serveur MCP donne à Claude des outils à appeler. Un skill donne à Claude un savoir-faire écrit qu'il charge quand une tâche correspond, comme les paramètres qu'un modèle accepte ou comment planifier une vidéo multi-plans. Atlas fournit les deux.
plaintext1npx skills add AtlasCloudAI/atlas-cloud-skills
Cela installe trois skills depuis le dépôt atlas-cloud-skills. Vous pouvez aussi copier un dossier de skill dans ~/.claude/skills/ à la main. Les skills lisent la même variable ATLASCLOUD_API_KEY.
| Skill | Ce que Claude en retire |
|---|---|
atlas-cloud
plaintext1 | Référence API pour les modèles image, vidéo et chat, plus des modèles de code en Python, Node.js et cURL |
| seedance-2-5-skill | Planification de plans pour Seedance : choisir la route, assigner les références, vocabulaire de caméra et d'éclairage | | universal-video-prompt-skill | Structures de prompt qui fonctionnent sur tous les modèles vidéo |
Le seedance-2-5-skill référence universal-video-prompt-skill, donc installez les deux si vous voulez ses spécifications de prompt multi-modèles. Pour une version image fixe de la même configuration, consultez nos tests de génération d'images de Claude.
FAQ
Claude Code peut-il être utilisé comme serveur MCP ?
Oui. Exécutez claude mcp serve et Claude Code démarre comme serveur MCP stdio qui n'affiche rien et attend un client. Pour l'utiliser depuis Claude Desktop, ajoutez une entrée dont la command est claude et les args sont mcp et serve. Si claude n'est pas dans votre PATH, mettez le chemin complet de l'exécutable dans le champ command.
Quels serveurs MCP devrais-je ajouter à Claude Code ?
Ajoutez des serveurs pour le travail que vous répétez chaque semaine. Un serveur de base de données est rentable si vous écrivez des requêtes quotidiennement ; un serveur multimédia comme atlascloud est rentable si vous produisez des images ou des vidéos, puisque Claude écrit le prompt et récupère le fichier dans une seule session.
Pourquoi mon serveur MCP affiche-t-il « Failed to connect » ?
Exécutez d'abord la commande du serveur toute seule. Pour atlascloud, c'est npx -y atlascloud-mcp, qui échoue rapidement si Node.js est antérieur à 18 ou si npx n'est pas dans votre PATH. Si la commande fonctionne à la main, le serveur peut simplement démarrer lentement : lancez Claude Code avec MCP_TIMEOUT=10000 pour lui donner 10 secondes.
Claude Code et Claude Desktop partagent-ils les serveurs MCP ?
Non. Claude Code lit ~/.claude.json et .mcp.json, et Claude Desktop lit claude_desktop_config.json, donc un serveur ajouté dans l'un n'apparaît pas dans l'autre. Les connecteurs que vous ajoutez à votre compte claude.ai sont l'exception : ils apparaissent automatiquement dans Claude Code lorsque vous vous connectez avec ce compte.
Conclusion
Une configuration typique nécessite cinq commandes : add ou add-json pour enregistrer un serveur, list et get pour confirmer qu'il s'est connecté, et remove pour nettoyer. Choisissez la portée avant d'appuyer sur Entrée et le reste suit.
Réussissez la configuration MCP de Claude Code une fois, vérifiez-la avec claude mcp list, et les nouvelles sessions dans cette portée s'ouvrent avec les outils prêts. Si vous voulez que Claude produise des images et des vidéos en plus du code, le serveur atlascloud sur lequel vous venez de vous exercer est un bon choix à conserver.
