Comment ajouter un serveur MCP à Claude Code

Ajouter un serveur distant via HTTP

Un serveur distant est une URL. Claude Code lui parle en HTTP en flux continu, donc l'inscription tient en une seule ligne :

claude mcp add --transport http hosttracker https://mcp.host-tracker.com/mcp

Le premier argument après le transport est le nom que vous verrez dans /mcp et dans les noms d'outils ; le second est le point de terminaison. Les serveurs qui s'authentifient par OAuth n'ont besoin de rien de plus en ligne de commande : la première fois que vous ouvrez /mcp, sélectionnez le serveur et Claude Code ouvre le navigateur pour l'étape de connexion et de consentement, puis stocke le jeton obtenu et le renouvelle de lui-même. Depuis Claude Code 2.1.186, vous pouvez aussi lancer la connexion sans la session interactive, avec claude mcp login hosttracker, et ajouter --no-browser sur une machine sans navigateur pour obtenir une URL à coller ailleurs.

Les serveurs qui attendent un jeton statique le prennent plutôt en en-tête :

claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer YOUR_TOKEN"

Quelques serveurs plus anciens parlent encore le transport SSE. Il est déprécié au profit de HTTP, et depuis Claude Code 2.1.265 --transport http essaie d'abord HTTP et revient à SSE si le serveur refuse, donc vous avez rarement encore besoin de --transport sse.

Ajouter un serveur local

Un serveur local est un programme que Claude Code démarre pour vous et avec lequel il parle via l'entrée et la sortie standard. Placez sa commande et ses arguments après un double tiret pour que les propres options de Claude Code ne soient pas confondues avec celles du serveur :

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects

Les variables d'environnement dont le serveur a besoin passent par --env (forme courte -e), répété une fois par variable. Un piège documenté : l'analyseur d'options lit ce qui suit --env KEY=value comme une autre paire, ne placez donc pas le nom du serveur directement après ; mettez une autre option entre les deux ou placez --env avant --transport :

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

Si vous avez déjà la configuration du serveur en JSON, par exemple depuis son README, claude mcp add-json <name> '<json>' la prend telle quelle, y compris type, command, args et env.

Choisir une portée : ce projet, l'équipe, ou partout

Par défaut, un serveur est ajouté dans la portée locale, ce qui signifie ce projet uniquement, stocké dans votre propre ~/.claude.json. Deux autres portées existent :

• --scope project écrit l'entrée dans un fichier .mcp.json à la racine du dépôt. Commitez-le et chaque collaborateur obtient le même serveur ; Claude Code demande à chaque personne de l'approuver la première fois.
• --scope user rend le serveur disponible dans tous les projets de votre machine, toujours privé à vous.

Quand le même nom existe dans plus d'une portée, local l'emporte sur project, et project l'emporte sur user. L'entrée entière est prise depuis la portée gagnante ; les champs ne sont jamais fusionnés entre portées. Une répartition sensée est --scope user pour les services liés à votre propre compte, comme un serveur de surveillance ou de tickets, et --scope project pour les outils que toute l'équipe devrait partager.

Vérifier que ça fonctionne

Lancez claude mcp list en dehors d'une session. Chaque serveur affiche l'un de quelques statuts : connecté, authentification nécessaire, échec de connexion (avec le statut HTTP ou l'erreur ajoutée depuis 2.1.219), approbation en attente pour un serveur de projet non approuvé, ou désactivé pour ce projet. À l'intérieur d'une session, /mcp montre les mêmes serveurs avec leur nombre d'outils, vous permet de lancer la connexion pour celui qui en a besoin, d'effacer son authentification, ou de le désactiver pour le projet en cours sans le supprimer.

Un test fonctionnel rapide est une requête à laquelle seul le serveur peut répondre. Avec le serveur HostTracker connecté, demandez « lesquels de mes moniteurs sont en panne en ce moment ? » ou « lance une vérification HTTP sur example.com depuis trois emplacements » ; l'assistant devrait appeler un outil nommé d'après le serveur et citer un résultat qu'il ne pouvait pas connaître d'avance. Si rien ne se passe, la liste des outils en est en général la raison : /mcp montre zéro outil pour un serveur qui s'est connecté mais dont l'autorisation a échoué.

Supprimer, inspecter et importer

claude mcp get <name> affiche la configuration et la portée complètes d'un serveur. claude mcp remove <name> le supprime avec tous les jetons OAuth stockés. Si vous avez configuré des serveurs dans Claude Desktop en premier, claude mcp add-from-claude-desktop les importe de façon interactive ; cela fonctionne sur macOS et sur Windows Subsystem for Linux, pas sur Windows ni Linux natifs, et ignore un serveur Desktop dont le nom contient des caractères que Claude Code n'autorise pas (seulement les lettres, chiffres, tirets et tirets bas).

Un serveur de surveillance comme premier test

Un service de surveillance est un bon premier serveur à brancher car le résultat d'un appel d'outil est immédiatement vérifiable : l'assistant dit qu'un site est actif, et vous pouvez l'ouvrir. Le serveur de HostTracker n'a besoin d'aucune installation locale, s'authentifie par OAuth dans le navigateur, et expose des vérifications instantanées depuis 300 emplacements ou plus, ainsi que les moniteurs, les incidents, les fenêtres de maintenance et les pages de statut de votre compte, si bien que « la production est-elle en ligne ? » obtient une réponse depuis de vrais points de contrôle plutôt que depuis des données d'entraînement. Le guide associé sur la configuration et le dépannage de .mcp.json couvre le format du fichier, les variables d'environnement et les échecs qui apparaissent en pratique.