Cette page couvre la configuration de MCP pour l’Agent SDK. Pour ajouter des serveurs MCP à l’interface de ligne de commande Claude Code afin qu’ils se chargent dans chaque projet, consultez Portées d’installation MCP.
Démarrage rapide
Cet exemple se connecte au serveur MCP de documentation Claude Code en utilisant le transport HTTP et utiliseallowedTools avec un caractère générique pour autoriser tous les outils du serveur.
Ajouter un serveur MCP
Vous pouvez configurer les serveurs MCP dans le code lors de l’appel dequery(), ou dans un fichier .mcp.json chargé via settingSources.
Dans le code
Transmettez les serveurs MCP directement dans l’optionmcpServers :
À partir d’un fichier de configuration
Créez un fichier.mcp.json à la racine de votre projet. Le fichier est récupéré lorsque la source de paramètre project est activée, ce qui est le cas pour les options query() par défaut. Si vous définissez settingSources explicitement, incluez "project" pour que ce fichier se charge :
Autoriser les outils MCP
Les outils MCP nécessitent une autorisation explicite avant que Claude puisse les utiliser. Sans autorisation, Claude verra que les outils sont disponibles mais ne pourra pas les appeler.Convention de nommage des outils
Les outils MCP suivent le modèle de nommagemcp__<server-name>__<tool-name>. Par exemple, un serveur GitHub nommé "github" avec un outil list_issues devient mcp__github__list_issues.
Approbation automatique avec allowedTools
UtilisezallowedTools pour approuver automatiquement des outils MCP spécifiques afin que Claude puisse les utiliser sans invite de permission :
*) vous permettent d’autoriser tous les outils d’un serveur sans lister chacun individuellement.
Préférez
allowedTools aux modes de permission pour l’accès MCP. permissionMode: "acceptEdits" n’approuve pas automatiquement les outils MCP (uniquement les modifications de fichiers et les commandes Bash du système de fichiers). permissionMode: "bypassPermissions" approuve automatiquement les outils MCP mais désactive également tous les autres messages de sécurité, ce qui est plus large que nécessaire. Un caractère générique dans allowedTools accorde exactement le serveur MCP que vous souhaitez et rien de plus. Consultez Modes de permission pour une comparaison complète.Découvrir les outils disponibles
Pour voir quels outils un serveur MCP fournit, consultez la documentation du serveur ou connectez-vous au serveur et inspectez le message d’initialisationsystem :
Types de transport
Les serveurs MCP communiquent avec votre agent en utilisant différents protocoles de transport. Consultez la documentation du serveur pour voir quel transport il supporte :- Si la documentation vous donne une commande à exécuter (comme
npx @modelcontextprotocol/server-github), utilisez stdio - Si la documentation vous donne une URL, utilisez HTTP ou SSE
- Si vous construisez vos propres outils dans le code, utilisez un serveur MCP SDK
Serveurs stdio
Les processus locaux qui communiquent via stdin/stdout. Utilisez ceci pour les serveurs MCP que vous exécutez sur la même machine :- Dans le code
- .mcp.json
Serveurs HTTP/SSE
Utilisez HTTP ou SSE pour les serveurs MCP hébergés dans le cloud et les API distantes :- Dans le code
- .mcp.json
"type": "http" à la place. Dans .mcp.json et autres fichiers de configuration JSON, "streamable-http" est accepté comme alias pour "http". L’option programmatique mcpServers accepte uniquement "http".
Serveurs MCP SDK
Définissez des outils personnalisés directement dans le code de votre application au lieu d’exécuter un processus serveur séparé. Consultez le guide des outils personnalisés pour les détails d’implémentation.Recherche d’outils MCP
Lorsque vous avez de nombreux outils MCP configurés, les définitions d’outils peuvent consommer une partie importante de votre fenêtre de contexte. La recherche d’outils résout ce problème en retenant les définitions d’outils du contexte et en chargeant uniquement ceux dont Claude a besoin pour chaque tour. La recherche d’outils est activée par défaut. Consultez Recherche d’outils pour les options de configuration et les détails. Pour plus de détails, y compris les meilleures pratiques et l’utilisation de la recherche d’outils avec les outils SDK personnalisés, consultez le guide de recherche d’outils.Authentification
La plupart des serveurs MCP nécessitent une authentification pour accéder aux services externes. Transmettez les identifiants via des variables d’environnement dans la configuration du serveur.Transmettre les identifiants via des variables d’environnement
Utilisez le champenv pour transmettre les clés API, les jetons et autres identifiants au serveur MCP :
- Dans le code
- .mcp.json
En-têtes HTTP pour les serveurs distants
Pour les serveurs HTTP et SSE, transmettez les en-têtes d’authentification directement dans la configuration du serveur :- Dans le code
- .mcp.json
Authentification OAuth2
La spécification MCP supporte OAuth 2.1 pour l’autorisation. Le SDK ne gère pas les flux OAuth automatiquement, mais vous pouvez transmettre les jetons d’accès via les en-têtes après avoir complété le flux OAuth dans votre application :Exemples
Lister les problèmes d’un référentiel
Cet exemple se connecte au serveur GitHub MCP pour lister les problèmes récents. L’exemple inclut la journalisation de débogage pour vérifier la connexion MCP et les appels d’outils. Avant d’exécuter, créez un jeton d’accès personnel GitHub avec la portéerepo et définissez-le comme variable d’environnement :
Interroger une base de données
Cet exemple utilise le serveur Postgres MCP pour interroger une base de données. La chaîne de connexion est transmise comme argument au serveur. L’agent découvre automatiquement le schéma de la base de données, écrit la requête SQL et retourne les résultats :Gestion des erreurs
Les serveurs MCP peuvent échouer à se connecter pour diverses raisons : le processus serveur peut ne pas être installé, les identifiants peuvent être invalides, ou un serveur distant peut être inaccessible. Le SDK émet un messagesystem avec le sous-type init au début de chaque requête. Ce message inclut l’état de la connexion pour chaque serveur MCP. Vérifiez le champ status pour détecter les défaillances de connexion avant que l’agent ne commence à travailler :
Dépannage
Le serveur affiche le statut « failed »
Vérifiez le messageinit pour voir quels serveurs n’ont pas pu se connecter :
- Variables d’environnement manquantes : Assurez-vous que les jetons et identifiants requis sont définis. Pour les serveurs stdio, vérifiez que le champ
envcorrespond à ce que le serveur attend. - Serveur non installé : Pour les commandes
npx, vérifiez que le package existe et que Node.js est dans votre PATH. - Chaîne de connexion invalide : Pour les serveurs de base de données, vérifiez le format de la chaîne de connexion et que la base de données est accessible.
- Problèmes réseau : Pour les serveurs HTTP/SSE distants, vérifiez que l’URL est accessible et que les pare-feu autorisent la connexion.
Les outils ne sont pas appelés
Si Claude voit les outils mais ne les utilise pas, vérifiez que vous avez accordé la permission avecallowedTools :
Délais d’expiration de la connexion
Le SDK MCP a un délai d’expiration par défaut de 60 secondes pour les connexions serveur. Si votre serveur prend plus de temps pour démarrer, la connexion échouera. Pour les serveurs qui ont besoin de plus de temps de démarrage, envisagez :- Utiliser un serveur plus léger si disponible
- Préchauffer le serveur avant de démarrer votre agent
- Vérifier les journaux du serveur pour les causes de lenteur d’initialisation
Ressources connexes
- Guide des outils personnalisés : Créez votre propre serveur MCP qui s’exécute en processus avec votre application SDK
- Permissions : Contrôlez quels outils MCP votre agent peut utiliser avec
allowedToolsetdisallowedTools - Référence SDK TypeScript : Référence API complète incluant les options de configuration MCP
- Référence SDK Python : Référence API complète incluant les options de configuration MCP
- Répertoire des serveurs MCP : Parcourez les serveurs MCP disponibles pour les bases de données, les API et bien d’autres