- Ce que MCP apporte à Claude
- Ajouter des serveurs MCP dans Claude Code
- Configuration des serveurs MCP dans Claude Desktop
- Types de transport MCP : stdio vs SSE
- Comment Claude raisonne sur les outils MCP
- Exécution des outils dans un sandbox
- Utiliser l'API LLM de Novita pour le raisonnement par appel d'outil MCP
- Problèmes courants et solutions
- FAQ
- Articles recommandés
Claude prend en charge le Model Context Protocol (MCP) de manière native, vous permettant de connecter des outils externes — bases de données, exécuteurs de code, API et serveurs personnalisés — directement dans votre flux de travail. Que vous utilisiez Claude Code dans le terminal ou Claude Desktop sur votre machine, la configuration MCP fonctionne de la même manière au niveau du protocole, avec quelques différences dans la façon d’enregistrer les serveurs. Ce guide couvre les deux voies : les commandes CLI claude mcp add pour Claude Code, et le fichier de configuration JSON pour Claude Desktop, ainsi que la manière dont le raisonnement par l’utilisation d’outils et l’exécution en sandbox s’intègrent dans le tableau.
Ce que MCP apporte à Claude
MCP est un standard ouvert 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 du 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 pratique : 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 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 fondamentaux sous-tendent MCP :
| Concept | Ce que c’est | Exemple |
|---|---|---|
| Outil | Une fonction invocable exposée par le serveur | run_python, query_db, list_models |
| Ressource | Des données en lecture seule mises à disposition par le serveur comme contexte | Un fichier, une ligne de base de données, un jeu de données |
| Invite | Des 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 importe le plus. Les ressources et les invites deviennent pertinentes lorsque vous construisez un pipeline 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 les serveurs sans toucher manuellement à aucun fichier de configuration.
claude mcp add — la forme de base
claude mcp add <nom> <commande> [arguments...]
Par exemple, pour ajouter un serveur MCP Python local :
claude mcp add my-tools python /chemin/vers/mcp_server.py
Ceci enregistre un serveur nommé my-tools qui exécute python /chemin/vers/mcp_server.py en utilisant le transport stdio. Claude Code lance le processus au début de votre session et le maintient actif pendant toute sa durée.
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 passer lors de l’enregistrement :
claude mcp add my-tools python /chemin/vers/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 serveur au démarrage. Ne codez pas en dur les secrets dans la commande serveur elle-même.
claude mcp add json — enregistrer à 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 passer directement par pipe :
echo '{
"command": "python",
"args": ["/chemin/vers/mcp_server.py"],
"env": {
"API_KEY": "votre_cle"
}
}' | claude mcp add my-tools --json
Ou passer un fichier :
claude mcp add my-tools --json < server-spec.json
Cela équivaut à 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 utilisateur, le rendant disponible dans chaque session Claude Code. Pour l’enregistrer uniquement pour le projet courant (stocké dans .claude/settings.json), ajoutez --scope project :
claude mcp add my-tools python /chemin/vers/mcp_server.py --scope project
Les serveurs à 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 — exposer Claude Code en tant que serveur MCP
La direction fonctionne également en sens inverse. claude mcp serve démarre Claude Code lui-même en tant que serveur MCP, permettant à un autre hôte MCP de s’y connecter et d’utiliser ses outils :
claude mcp serve
C’est utile si vous souhaitez composer les capacités de Claude Code dans un pipeline agent plus vaste où un hôte différent orchestre les appels d’outils.
Configuration des serveurs MCP dans 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": ["/chemin/vers/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 en forme de marteau dans la zone de saisie du chat lorsque les outils MCP sont chargés avec succès.
Ajouter 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 headers 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 en tant que sous-processus sur la même machine. L’hôte lance le processus et lit/écrit des messages JSON-RPC via l’entrée/sortie standard. C’est le transport par défaut pour les serveurs locaux et le 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 à travers les machines et constitue 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 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 en JSON Schema. Claude n’appelle pas les outils de manière spéculative — 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 chaîner des appels d’outils, utiliser les résultats d’un outil pour informer les arguments d’un autre, et agréger les résultats de plusieurs serveurs dans la même session.
La qualité des descriptions des outils est très importante 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 avoir à deviner.
Exécution des outils dans un sandbox
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, lancement de processus ou appels réseau a une portée large s’il se comporte mal ou est poussé vers un chemin inattendu.
Novita AI Agent Sandbox répond à ce besoin 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 sandbox. Le sandbox dispose de son propre système de fichiers, de sa propre portée réseau et de ses propres 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 sandbox expose ses outils via le transport SSE, et Claude s’y connecte à distance — donc du point de vue de Claude, l’intégration est 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, maintenant une faible latence de va-et-vient des outils
- Facturation à la seconde : vous payez uniquement pour le temps d’exécution actif, pas pour la réservation inactive
- Système de fichiers isolé : chaque instance sandbox 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 Novita Sandbox, voir Construire un serveur MCP d’exécution de code à distance avec Novita Sandbox et la bibliothèque mcp-use.
Utiliser l’API LLM de Novita pour le raisonnement par appel d’outil MCP
Bien que les propres modèles de Claude gèrent l’utilisation des outils de manière native, vous pouvez souhaiter router une partie du raisonnement par appel d’outil 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 fonction 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 (au lieu 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 d’outils et la conversation ; le modèle retourne les instructions d’appel d’outil ; l’hôte les dispatche 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 reçoit les entrées de l’agent, appelle l’API Novita et retourne le résultat. Cela maintient les coûts d’inférence du modèle séparés des coûts du modèle agent principal et vous permet de choisir le modèle approprié pour chaque sous-tâche.
Pour un exemple pratique de construction d’un serveur MCP qui appelle l’API Novita, voir Comment construire votre premier serveur MCP avec 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 en trop 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 estime 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 précisions : 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 déclaré par l’outil. Examinez la définition inputSchema de votre outil — si des champs requis sont manquants ou que les types ne correspondent pas, le serveur rejettera l’appel. Claude construit les arguments à partir du schéma, donc un schéma incomplet conduit à des appels incomplets.
FAQ
Claude Code prend-il en charge MCP ?
Oui. Claude Code dispose d’un support MCP natif 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> [arguments...] pour un serveur stdio, ou utilisez --json pour passer une spécification JSON. Pour un enregistrement au niveau du 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 en tant que 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. Cela 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 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’utilisation 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 non plus. 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 d’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 en tant que 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.
