Toeverything·Publié 20 août 2026 · Mis à jour 21 août 2026
Ajouter un serveur MCP à Claude Code : guide complet
Productivité
L'essentiel en bref
Claude Code parle MCP nativement : pour un serveur distant, une seule commande claude mcp add et quelques minutes suffisent.
La configuration se range dans l'une des trois portées (local, project, user). Le partage d'équipe passe par project ; les identifiants, eux, restent dans une portée personnelle.
Claude Desktop suit deux voies : les Connecteurs pour les serveurs distants, le fichier de configuration pour les serveurs locaux. Sa configuration est indépendante de celle de Claude Code.
Un serveur invisible ? Dans la session, la commande /mcp affiche l'état de la connexion — c'est toujours le premier réflexe.
Ce guide couvre la commande claude mcp add et la logique des portées, l'authentification par jeton ou par OAuth, la configuration côté Claude Desktop, un exemple complet avec un espace AFFiNE, et la liste de dépannage quand rien n'apparaît. Si le concept est encore flou, commencez par ce qu'est un serveur MCP.
Ajouter un serveur MCP à Claude Code
Pour un serveur distant (HTTP) — le cas le plus courant avec les services hébergés :
Pour un serveur local (stdio), que Claude Code lance sur votre machine :
claude mcp add <nom> -- <commande-de-lancement>
Le double tiret n'est pas décoratif : ce qui le précède appartient à Claude Code, ce qui le suit est la commande du serveur, transmise sans retouche. Les variables d'environnement dont le serveur a besoin se passent avec l'option --env CLÉ=valeur, placée avant le --.
La maintenance tient en trois sous-commandes : claude mcp list pour l'inventaire, claude mcp get pour le détail, claude mcp remove pour supprimer. Si un produit fournit un JSON prêt à l'emploi, claude mcp add-json '' l'accepte tel quel. En session, la commande /mcp affiche l'état des connexions et les outils disponibles — à consulter en premier dès que quelque chose cloche.
Un mot sur l'authentification : l'en-tête Bearer ci-dessus vaut pour les serveurs à jeton, comme celui d'AFFiNE. Beaucoup de services hébergés (Notion, Sentry) passent plutôt par OAuth — ajoutez le serveur sans en-tête, lancez /mcp, et Claude Code ouvre le navigateur pour la connexion, puis stocke le jeton de façon sécurisée et le renouvelle sans intervention. Le même flux se déclenche hors session avec claude mcp login . Pour le reste des options, la référence est la documentation officielle de Claude Code.
Les portées : local, project, user
L'endroit où la configuration s'écrit détermine qui la voit :
local (par défaut) : ce projet, cette machine, vous seul. Pour les essais et les identifiants personnels.
project : la définition part dans un fichier .mcp.json à la racine du dépôt, versionné et partagé avec toute l'équipe. C'est la portée des serveurs communs — la base de connaissances, par exemple ; chaque personne approuve le serveur à la première utilisation, et claude mcp reset-project-choices remet ces choix à zéro.
user (--scope user) : valable pour vous dans tous les projets de la machine. Pour les serveurs personnels d'usage constant.
La règle simple : les identifiants restent personnels ; ce que l'on partage via project, c'est la définition du serveur, chacun fournissant son propre jeton par variable d'environnement. Et c'est prévu : .mcp.json accepte l'expansion ${VAR} — ou ${VAR:-défaut} avec valeur de repli — dans url, headers, command, args et env. On versionne donc un en-tête Authorization: Bearer ${AFFINE_TOKEN}, et chacun définit AFFINE_TOKEN sur son poste.
Ajouter dans Claude Desktop
Serveur distant : Paramètres → Connecteurs → ajouter un connecteur personnalisé, coller l'URL, autoriser. La méthode sans terminal — suffisante pour les serveurs hébergés comme celui d'AFFiNE ou de Notion.
Serveur local : éditer claude_desktop_config.json (Paramètres → Développeur → modifier la configuration), ajouter le serveur sous mcpServers, redémarrer l'application.
Les mêmes serveurs fonctionnent dans Claude Code et Claude Desktop, mais chaque application garde sa configuration locale. Deux passerelles évitent la double saisie : claude mcp add-from-claude-desktop importe dans Claude Code les serveurs du fichier de configuration de Claude Desktop (macOS et WSL) ; quant aux connecteurs distants, rattachés à votre compte claude.ai, ils apparaissent aussi dans Claude Code dès que vous vous y connectez avec ce compte.
De bout en bout : connecter sa base de connaissances
Le parcours complet avec le serveur MCP intégré d'AFFiNE, qui rend les documents et tableaux blancs de l'espace de travail interrogeables par n'importe quel client MCP :
Créer l'identifiant. Dans AFFiNE : Paramètres → Integrations → MCP Server → Create credential. Nommez-le d'après le client (« Claude Code » ; un identifiant par client rend la révocation indolore), laissez l'accès en lecture seule par défaut, fixez une date d'expiration.
Copier la configuration. Le jeton ne s'affiche qu'une fois, à côté du bouton Copy JSON qui génère la configuration complète — URL du point d'accès et en-tête d'authentification compris. Le point d'accès a la forme https://app.affine.pro/api/workspaces//mcp ; en auto-hébergement, c'est l'adresse de votre serveur.
Utiliser. Ouvrez une session et posez une question dont seules vos notes ont la réponse : « retrouve la conception de la relance de paiement et résume les points ouverts ». Claude Code appelle l'outil de recherche (mots-clés + sémantique, tableaux blancs compris), récupère le document en Markdown dans la limite de vos permissions et répond à partir de votre contenu réel.
Aucun coût supplémentaire : cela fonctionne sur AFFiNE Cloud comme sur une instance auto-hébergée avec les fonctions IA activées.
Le transport détermine où s’exécute le serveur ; les droits associés aux identifiants déterminent les outils et les données auxquels le client peut accéder.
La même configuration pour Cursor et ChatGPT
Cursor lit ~/.cursor/mcp.json (ou .cursor/mcp.json au niveau projet). La sortie Copy JSON d'AFFiNE correspond telle quelle au format de Cursor : coller, redémarrer, terminé.
ChatGPT se connecte aux serveurs MCP distants via les connecteurs ; les serveurs personnalisés demandent le mode développeur (Paramètres → Connecteurs → Avancé). Même point d'accès, même en-tête, aucune modification. Un serveur, tous les assistants — c'est tout l'intérêt de MCP.
Dépannage : le serveur n'apparaît pas
Descendez la liste dans l'ordre ; la grande majorité des cas s'y résout :
D'abord /mcp. Connecté, refusé à l'authentification, ou jamais démarré : tout est là. Mieux vaut lire l'erreur affichée que d'empiler les hypothèses.
Mauvais transport. Un serveur hébergé exige --transport http ; sans l'option, Claude Code traite l'URL comme une commande locale. Supprimez, puis rajoutez avec l'option. Et si un tutoriel un peu daté vous montre --transport sse, passez votre chemin : ce transport est déprécié, prenez http dès que le serveur le propose.
Coquille dans l'en-tête. Le format est Authorization: Bearer — un Bearer manquant ou un espace en trop produit un 401 muet. Ne tapez rien à la main ; collez depuis Copy JSON.
Identifiant expiré ou révoqué. Un jeton à durée limitée finit par expirer — c'est même le but. Émettez un nouvel identifiant et réenregistrez le serveur.
Portée confondue. Un serveur ajouté en portée local n'existe pas dans les autres projets. Lancez claude mcp list dans le dossier où vous l'attendez : la réalité s'affiche.
Dépendance manquante côté serveur local. Un serveur stdio lance une commande ; sans l'environnement d'exécution, il meurt au démarrage. Exécutez la commande à la main une fois et lisez l'erreur réelle.
Connecté mais jamais utilisé. Les premières fois, nommez la source dans votre demande (« cherche dans mon espace AFFiNE… »). Une fois le pli pris, Claude choisit le bon outil sans qu'on le lui dise.
Les réglages de sécurité à garder
Lecture seule tant que l'écriture n'est pas nécessaire. Une connexion à la base de connaissances a rarement besoin d'écrire ; les identifiants AFFiNE naissent en lecture seule, l'écriture étant en déploiement progressif.
Un identifiant par client. Révoquer le portable ne doit pas casser le poste fixe. Avec une date d'expiration, la rotation devient une simple routine.
Approuver les outils en conscience. Claude demande avant d'utiliser un nouvel outil, et les serveurs partagés en portée project sont approuvés par chacun à la première utilisation. Ne désactivez jamais cela pour ce qui peut modifier des données. La liste complète est dans notre guide de sécurité MCP (en anglais).
Questions fréquentes
Quelle commande ajoute un serveur MCP à Claude Code ?
La commande claude mcp add : pour un serveur hébergé, avec --transport http, l'URL et l'en-tête d'authentification ; pour un serveur local, avec la commande de lancement. Vérifiez avec claude mcp list, et /mcp affiche l'état en session.
Claude Desktop prend-il en charge les serveurs MCP ?
Oui. Les serveurs distants s'ajoutent via Paramètres → Connecteurs en connecteur personnalisé ; les locaux vont dans claude_desktop_config.json sous mcpServers, avec redémarrage. Seule subtilité : sa configuration est distincte de celle de Claude Code.
Quelle différence entre les portées local, project et user ?
local vaut pour vous dans un seul projet ; project écrit un .mcp.json partagé dans le dépôt pour toute l'équipe ; user vaut pour vous dans tous les projets de la machine. Les identifiants restent côté personnel — seule la définition du serveur se partage via project.
Où la configuration MCP de Claude Code est-elle stockée ?
Les serveurs en portée local et user s'enregistrent dans ~/.claude.json, dans votre répertoire personnel — la portée local y est rangée sous l'entrée du projet concerné. La portée project écrit le .mcp.json à la racine du dépôt, et Claude Desktop garde son propre claude_desktop_config.json. Éditer ces fichiers à la main fonctionne, mais claude mcp add vous épargne les erreurs de syntaxe.
Claude Code peut-il joindre des serveurs MCP distants ?
Oui. Les serveurs distants en Streamable HTTP sont officiellement pris en charge avec --transport http, l'authentification passant par un en-tête Bearer ou par un flux OAuth lancé depuis /mcp. Les points d'accès hébergés, comme celui d'un espace AFFiNE, se connectent sans aucun processus local à entretenir.
Comment se connecter à un serveur MCP qui demande OAuth ?
Ajoutez le serveur sans en-tête avec claude mcp add --transport http, puis lancez /mcp : Claude Code ouvre le navigateur pour la connexion, stocke le jeton de façon sécurisée et le renouvelle automatiquement. Le même flux existe hors session avec claude mcp login , et claude mcp logout efface les identifiants stockés.
Pourquoi mon serveur n'apparaît-il pas dans la liste ?
Vérifiez l'état avec /mcp, puis les suspects habituels : --transport http oublié sur un serveur distant, en-tête Authorization mal formé, identifiant expiré, ou portée confondue (local n'existe que dans le projet où il a été ajouté). Ces quatre causes expliquent presque tout.
Utiliser MCP avec Claude coûte-t-il quelque chose ?
La prise en charge de MCP est incluse sans surcoût dans Claude Code et Claude Desktop, et le protocole est open source. Les conditions varient selon les serveurs ; celui intégré à AFFiNE, par exemple, est gratuit sur Cloud comme en auto-hébergement avec les fonctions IA activées.
En résumé
Le premier serveur branché, le deuxième suit tout seul — la procédure est identique partout. Commencez là où vous cherchez des réponses toute la journée : votre propre espace de travail.