- Comment fonctionne la configuration MCP de Claude
- Ajouter des serveurs MCP dans Claude Code
- Configuration des serveurs MCP de Claude Desktop
- Types de transport MCP : stdio vs SSE
- Comment Claude raisonne sur les outils MCP
- Exécution d'outils dans un bac à sable
- Utilisation de l'API LLM Novita pour le raisonnement sur l'utilisation des outils MCP
- Problèmes courants et solutions
- FAQ
- Articles recommandés
La configuration MCP de Claude connecte Claude Code ou Claude Desktop à des outils externes tels que des bases de données, des exécuteurs de code, des API et des serveurs personnalisés. Utilisez claude mcp add pour Claude Code ou modifiez la configuration JSON de Claude Desktop, puis vérifiez le transport, la portée et la liste des outils. Ce guide couvre les deux chemins de configuration, les échecs courants, le raisonnement sur l’utilisation des outils et l’exécution en bac à sable.
Comment fonctionne la configuration MCP de Claude
MCP est une norme ouverte d’Anthropic qui offre aux modèles de langage un moyen uniforme d’appeler des outils externes. Avant MCP, chaque application d’IA nécessitait un code d’adaptation spécifique pour chaque outil qu’elle souhaitait utiliser. Avec MCP, tout serveur conforme expose ses capacités via un protocole standard de découverte et d’invocation, et tout hôte conforme — y compris Claude — peut les utiliser sans travail d’intégration par outil.
En termes pratiques : lorsque vous ajoutez un serveur MCP à Claude, vous indiquez à l’hôte Claude où trouver un ensemble d’outils. Claude peut alors lister ces outils pendant une session et les appeler par leur nom lorsque la tâche le justifie. Le serveur gère l’exécution ; Claude gère le raisonnement sur quand et comment appeler.
Trois concepts clés sous-tendent MCP :
| Concept | Ce que c’est | Exemple |
|---|---|---|
| Outil | Une fonction appelable exposée par le serveur | run_python, query_db, list_models |
| Ressource | Données en lecture seule que le serveur met à disposition comme contexte | Un fichier, une ligne de base de données, un jeu de données |
| Invite | Modèles d’instructions préconstruits fournis avec le serveur | Une description de tâche au niveau système |
Pour la plupart des développeurs, les outils sont ce qui compte le plus. Les ressources et les invites deviennent pertinentes lorsque vous construisez un pipeline d’agent plus structuré.
Ajouter des serveurs MCP dans Claude Code
Claude Code expose la gestion MCP via le groupe de sous-commandes claude mcp. Vous pouvez ajouter, supprimer et lister des serveurs sans toucher manuellement à aucun fichier de configuration.
claude mcp add — la forme de base
claude mcp add <nom> <commande> [args...]
Par exemple, pour ajouter un serveur MCP Python local :
claude mcp add my-tools python /path/to/mcp_server.py
Cela enregistre un serveur nommé my-tools qui exécute python /path/to/mcp_server.py en utilisant le transport stdio. Claude Code lance le processus lorsque vous démarrez une session et le maintient en vie pour la durée de celle-ci.
Transmettre des variables d’environnement
De nombreux serveurs MCP ont besoin de clés API ou d’URL de point de terminaison. Utilisez --env pour les transmettre lors de l’enregistrement :
claude mcp add my-tools python /path/to/mcp_server.py \
--env API_KEY=votre_cle_ici \
--env BASE_URL=https://api.exemple.com
Les valeurs sont stockées dans la configuration de Claude Code et injectées dans le processus du serveur au démarrage. Ne codez pas en dur les secrets dans la commande du serveur elle-même.
claude mcp add json — enregistrement à partir d’une spécification JSON
Si vous avez déjà une spécification de serveur écrite en JSON (courant lors du partage de configurations au sein d’une équipe), vous pouvez la rediriger directement :
echo '{
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "votre_cle"
}
}' | claude mcp add my-tools --json
Ou passez un fichier :
claude mcp add my-tools --json < server-spec.json
C’est équivalent à la forme positionnelle mais vous donne un artefact de configuration unique que vous pouvez versionner et partager.
Lister et supprimer des serveurs
# Voir tous les serveurs enregistrés
claude mcp list
# Supprimer un serveur
claude mcp remove my-tools
Portée : projet vs utilisateur
Par défaut, claude mcp add enregistre le serveur dans votre configuration au niveau utilisateur, le rendant disponible dans chaque session de Claude Code. Pour l’enregistrer uniquement pour le projet actuel (stocké dans .claude/settings.json), ajoutez --scope project :
claude mcp add my-tools python /path/to/mcp_server.py --scope project
Les serveurs avec portée projet sont utiles lorsque différents projets nécessitent différents outils et que vous souhaitez garder les configurations isolées.
claude mcp serve — exposition de Claude Code comme serveur MCP
La direction fonctionne également en sens inverse. claude mcp serve démarre Claude Code lui-même comme serveur MCP, permettant à un autre hôte MCP de s’y connecter et d’utiliser ses outils :
claude mcp serve
Ceci est utile si vous souhaitez composer les capacités de Claude Code dans un pipeline d’agent plus vaste où un hôte différent orchestre les appels d’outils.
Configuration des serveurs MCP de Claude Desktop
Claude Desktop stocke la configuration des serveurs MCP dans un fichier JSON. Son emplacement dépend de votre système d’exploitation :
- macOS :
~/Library/Application Support/Claude/claude_desktop_config.json - Windows :
%APPDATA%\Claude\claude_desktop_config.json
Si le fichier n’existe pas, créez-le. La structure ressemble à ceci :
{
"mcpServers": {
"my-tools": {
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "votre_cle_ici"
}
}
}
}
Chaque clé sous mcpServers est le nom du serveur que Claude utilisera pour l’identifier. Vous pouvez enregistrer autant de serveurs que nécessaire — Claude Desktop les charge tous au démarrage.
Après avoir modifié le fichier, redémarrez Claude Desktop pour que les changements prennent effet. Vous verrez une icône de marteau dans la zone de saisie du chat lorsque les outils MCP sont chargés avec succès.
Ajout d’un serveur MCP distant via SSE
Pour les serveurs distants qui utilisent le transport Server-Sent Events (SSE) au lieu de stdio, la forme de la configuration est légèrement différente :
{
"mcpServers": {
"remote-tools": {
"url": "https://votre-serveur-mcp.exemple.com/sse"
}
}
}
Certains serveurs distants nécessitent une authentification. Passez un jeton d’accès dans le champ des en-têtes si le serveur l’attend :
{
"mcpServers": {
"remote-tools": {
"url": "https://votre-serveur-mcp.exemple.com/sse",
"headers": {
"Authorization": "Bearer votre_jeton_ici"
}
}
}
}
Types de transport MCP : stdio vs SSE
Les serveurs MCP communiquent avec l’hôte Claude via l’un des deux mécanismes de transport :
stdio — Le serveur s’exécute comme un sous-processus sur la même machine. L’hôte lance le processus et lit/écrit les messages JSON-RPC via l’entrée/sortie standard. C’est la valeur par défaut pour les serveurs locaux et la plus simple à configurer.
SSE (Server-Sent Events) — Le serveur s’exécute à distance et expose un point de terminaison HTTP. L’hôte se connecte à une URL et reçoit les réponses des outils sous forme de flux. Cela fonctionne entre machines et est le bon choix pour une infrastructure d’équipe partagée ou des services d’outils hébergés.
Pour la plupart des développeurs individuels qui débutent, stdio est plus simple — pas de réseau nécessaire, et le processus du serveur est géré pour vous. SSE devient précieux lorsque vous souhaitez qu’une équipe partage un seul serveur MCP, ou lorsque l’outil lui-même doit s’exécuter dans un environnement réseau spécifique.
Comment Claude raisonne sur les outils MCP
Lorsqu’une session démarre et que des serveurs MCP sont enregistrés, Claude interroge chaque serveur pour connaître ses outils disponibles. Cela produit une liste de noms d’outils et de descriptions au format JSON Schema. Claude n’appelle pas les outils par spéculation — il n’invoque un outil que lorsque la conversation ou la tâche l’exige, en fonction de ce que la description de l’outil indique qu’il fait.
Le flux d’appel d’outil fonctionne comme suit :
- L’utilisateur envoie un message ou une tâche.
- Claude évalue si un outil enregistré peut aider.
- Si oui, Claude construit un appel d’outil avec les arguments appropriés.
- L’hôte MCP envoie l’appel au serveur correct.
- Le serveur exécute et retourne un résultat.
- Claude intègre le résultat dans son raisonnement et continue.
Cette boucle peut se produire plusieurs fois en un seul tour — Claude peut enchaîner les appels d’outils, utiliser les résultats d’un outil pour éclairer les arguments d’un autre, et agréger plusieurs serveurs dans la même session.
La qualité des descriptions des outils compte beaucoup ici. Des descriptions vagues entraînent des invocations manquées ou incorrectes. Des descriptions précises qui incluent ce que fait l’outil, ce que signifient ses arguments et ce qu’il retourne permettent à Claude d’acheminer les appels avec précision sans deviner.
Exécution d’outils dans un bac à sable
Lorsque les outils MCP exécutent du code — scripts Python, commandes shell, opérations sur fichiers — les exécuter sur votre machine locale soulève des questions d’isolation. Un outil avec accès au système de fichiers, création de processus ou appels réseau a une portée étendue s’il se comporte mal ou est amené sur un chemin imprévu.
Novita AI Agent Sandbox répond à ce problème en fournissant des environnements cloud isolés pour l’exécution des outils. Au lieu d’exécuter votre serveur MCP localement, vous le déployez à l’intérieur d’une instance de bac à sable. Le bac à sable possède son propre système de fichiers, périmètre réseau et limites de ressources. L’agent peut écrire des fichiers, exécuter du code et appeler des API internes à l’intérieur de cette limite sans toucher à la machine hôte.
Le serveur MCP s’exécutant à l’intérieur du bac à sable expose ses outils via le transport SSE, et Claude s’y connecte à distance — du point de vue de Claude, l’intégration est donc identique. La différence réside entièrement dans ce sur quoi l’outil s’exécute réellement.
Caractéristiques clés du Novita Sandbox pour les déploiements MCP :
- Démarrage rapide : les instances se lancent en moins de ~200 ms, ce qui maintient une faible latence d’aller-retour des outils
- Facturation à la seconde : vous ne payez que pour le temps d’exécution actif, pas pour la réservation inactive
- Système de fichiers isolé : chaque instance de bac à sable dispose d’un espace de travail séparé, empêchant les fuites de données entre sessions
- Politique réseau configurable : contrôlez les services externes auxquels l’outil peut accéder
Pour un guide étape par étape sur la construction d’un serveur MCP basé sur un bac à sable Novita, voir Build a Remote Code Execution MCP Server with Novita Sandbox and mcp-use Library.
Utilisation de l’API LLM Novita pour le raisonnement sur l’utilisation des outils MCP
Bien que les propres modèles de Claude gèrent l’utilisation des outils de manière native, vous souhaiterez peut-être acheminer une partie du raisonnement sur l’utilisation des outils MCP via un modèle différent — pour des raisons de coût, de latence ou de spécialisation. L’API LLM Novita fournit un point de terminaison compatible OpenAI avec accès à des modèles prenant en charge l’appel de fonctions et l’invocation structurée d’outils.
Cela s’intègre dans les architectures MCP de deux manières :
1. Comme modèle de raisonnement derrière un hôte MCP personnalisé : Si vous construisez votre propre hôte MCP (plutôt que d’utiliser Claude Code ou Claude Desktop), vous pouvez utiliser l’API LLM Novita pour alimenter la couche modèle. L’hôte appelle l’API Novita avec la liste des outils et la conversation ; le modèle retourne des instructions d’appel d’outil ; l’hôte les envoie au serveur MCP.
import openai
client = openai.OpenAI(
base_url="https://api.novita.ai/v3/openai",
api_key="votre_cle_api_novita",
)
response = client.chat.completions.create(
model="meta-llama/llama-3.3-70b-instruct",
messages=[{"role": "user", "content": "Liste les outils disponibles et exécute un test rapide"}],
tools=[
{
"type": "function",
"function": {
"name": "list_models",
"description": "Liste tous les modèles disponibles depuis l'API.",
"parameters": {"type": "object", "properties": {}},
}
}
],
tool_choice="auto",
)
2. Comme LLM à l’intérieur d’un outil MCP lui-même : Un outil MCP peut utiliser l’API LLM Novita en interne — par exemple, un outil de résumé, un outil de classification ou un outil qui génère du code. L’outil accepte les entrées de l’agent, appelle l’API Novita et retourne le résultat. Cela sépare les coûts d’inférence du modèle des coûts du modèle d’agent principal et vous permet de choisir le bon modèle pour chaque sous-tâche.
Pour un exemple pratique de construction d’un serveur MCP qui appelle l’API Novita, voir How to Build Your First MCP Server with Novita AI.
Problèmes courants et solutions
Le serveur n’apparaît pas dans Claude Desktop
La cause la plus fréquente est une erreur de syntaxe JSON dans claude_desktop_config.json. Utilisez un validateur JSON avant d’enregistrer. Même une virgule finale empêchera le chargement du fichier. Redémarrez Claude Desktop après chaque modification.
Commande claude mcp add introuvable
Cela signifie que Claude Code n’est pas installé ou n’est pas dans votre PATH. Installez Claude Code via npm install -g @anthropic-ai/claude-code et vérifiez avec claude --version.
Outils listés mais jamais appelés
Claude n’appelle un outil que lorsqu’il croit que l’outil est pertinent pour la tâche en cours. Si vos descriptions d’outils sont trop vagues, Claude ne les sélectionnera pas. Ajoutez des détails : ce que fait l’outil, quand l’utiliser, à quoi ressemblent ses entrées et sorties.
Le serveur se ferme immédiatement après le lancement
Vérifiez que la commande du serveur est correcte et que toutes les variables d’environnement requises sont définies. Exécutez la commande directement dans un terminal pour voir la sortie d’erreur réelle — Claude Code peut supprimer stderr du sous-processus dans certaines configurations.
Connexion SSE refusée
Vérifiez que l’URL du serveur est accessible depuis la machine exécutant Claude, que le serveur écoute réellement sur le port attendu et que les en-têtes d’authentification requis sont correctement configurés.
Les appels d’outils échouent avec des erreurs de validation
Les arguments que Claude passe doivent correspondre au JSON Schema que l’outil déclare. Revoyez la définition inputSchema de votre outil — si des champs obligatoires sont manquants ou que les types ne correspondent pas, le serveur rejettera l’appel. Claude construit les arguments en fonction du schéma, donc un schéma incomplet conduit à des appels incomplets.
FAQ
Claude Code prend-il en charge MCP ?
Oui. Claude Code offre une prise en charge native de MCP via la sous-commande claude mcp. Utilisez claude mcp add pour enregistrer des serveurs, claude mcp list pour voir ce qui est enregistré, et claude mcp remove pour désenregistrer. Exécutez claude mcp --help pour la référence complète des commandes.
Comment ajouter un serveur MCP à Claude Code ?
Exécutez claude mcp add <nom> <commande> [args...] pour un serveur stdio, ou utilisez --json pour passer une spécification JSON. Pour un enregistrement avec portée projet, ajoutez --scope project. Après l’ajout, démarrez une nouvelle session Claude Code — les outils seront disponibles immédiatement.
Qu’est-ce que claude mcp serve ?
claude mcp serve exécute Claude Code comme un serveur MCP lui-même, exposant ses capacités via le protocole MCP. Un autre hôte MCP peut alors se connecter à Claude Code et l’utiliser comme source d’outils. Ceci est utile lors de la construction de systèmes multi-agents où Claude est un composant parmi plusieurs.
Puis-je utiliser le même serveur MCP à la fois dans Claude Code et Claude Desktop ?
Oui. Le serveur lui-même ne se soucie pas de l’hôte qui s’y connecte. Pour les serveurs stdio, Claude Code (via claude mcp add) et Claude Desktop (via claude_desktop_config.json) peuvent lancer la même commande. Pour les serveurs SSE, tout hôte pouvant atteindre l’URL peut se connecter.
Comment Claude sait-il quel outil MCP appeler ?
Au début de la session, Claude interroge tous les serveurs enregistrés pour leurs listes d’outils. Chaque outil a un nom et une description. Lors du traitement d’une tâche, Claude sélectionne les outils en fonction de la correspondance entre leurs descriptions et ce qui est nécessaire. Des descriptions bien rédigées avec des cas d’usage clairs conduisent à une sélection précise des outils ; des descriptions vagues entraînent des appels manqués ou incorrects.
Y a-t-il une limite au nombre de serveurs MCP que je peux enregistrer ?
La spécification MCP n’impose pas de limite stricte, et ni Claude Code ni Claude Desktop n’en imposent une. En pratique, avoir des dizaines de serveurs avec des centaines d’outils peut ralentir le démarrage de la session (la découverte des outils s’exécute au lancement) et peut ajouter du bruit à la sélection des outils par Claude. Gardez l’ensemble d’outils concentré sur ce dont un projet ou une session donnée a réellement besoin.
Quelle est la différence entre les transports stdio et SSE ?
Stdio exécute le serveur comme un sous-processus local ; l’hôte communique via stdin/stdout. SSE se connecte à un point de terminaison HTTP distant et reçoit les réponses sous forme de flux. Stdio est plus simple pour le développement local ; SSE est meilleur pour les déploiements distants, partagés ou de production.
