Ajoutez des serveurs Model Context Protocol à Gemini CLI avec la commande gemini mcp add ou une entrée settings.json écrite à la main. Découvrez des configurations stdio, SSE et HTTP streamable qui fonctionnent, ainsi que l’OAuth, le filtrage des outils, les paramètres de confiance et les vérifications qui dépannent un serveur bloqué sur Disconnected.
Gemini CLI est utile dès son installation. Il le devient bien davantage lorsqu’il peut accéder à votre outil de suivi des tickets, à votre base de données ou à un dossier de fichiers de design, sans que vous ayez à rien coller dans le prompt. Le pont est le Model Context Protocol, et chaque pont est un serveur MCP. Gemini CLI peut communiquer avec des serveurs qui tournent sous forme de processus locaux, avec des serveurs derrière un simple point de terminaison HTTP, et avec d’anciens points de terminaison de streaming SSE. Il vous offre deux façons de les enregistrer : une commande gemini mcp add, ou quelques lignes dans settings.json.
Cet article parcourt les deux méthodes avec de vraies commandes, puis aborde les points qui posent généralement problème : portées, secrets, filtrage des outils, OAuth et le redouté statut Disconnected. Chaque option et chaque champ ci-dessous proviennent de la documentation officielle de Gemini CLI sur MCP, et lorsque le comportement diffère selon les versions, je le signale.
💡 Réponse rapide : exécutez
gemini mcp add -s user <name> <command-or-url>, puis tapez/mcpdans la CLI. Le serveur doit apparaître comme connecté et lister ses outils.
Au démarrage, Gemini CLI lit vos serveurs configurés, se connecte à chacun d’eux et leur demande ce qu’ils proposent. Le serveur répond par une liste d’outils, et chaque outil possède un nom, une description et un schéma JSON pour ses entrées. Le modèle voit ces outils à côté des outils intégrés (lecture de fichiers, commandes shell, recherche web) et les appelle lorsqu’un prompt en a besoin.
Un serveur peut exposer trois types d’éléments :
La plupart des serveurs ne proposent que des outils, et ce sont eux qui justifient vos efforts de configuration. Tout ce qui suit vise à connecter ces outils en toute sécurité.
Chaque entrée de serveur utilise exactement l’un des trois transports. Le champ que vous renseignez détermine celui qu’utilise la CLI.
| Transport | Champ de configuration | Option CLI | Idéal pour |
|---|---|---|---|
| Stdio | command (avec args) | par défaut, ou --transport stdio | Serveurs locaux que la CLI lance avec npx, node ou python3 |
| SSE | url | --transport sse | Anciens serveurs distants qui exposent encore un point de terminaison /sse |
| HTTP streamable | httpUrl | --transport http | Serveurs distants actuels et services hébergés |
Avec stdio, la CLI démarre le processus et communique avec lui via l’entrée et la sortie standard. Cela signifie qu’un serveur ne doit jamais afficher de texte parasite sur stdout. Les journaux doivent aller sur stderr, sinon le flux du protocole se brise et le serveur se déconnecte.
Le choix est généralement fait à votre place. Si un serveur est un paquet ou un script sur votre machine, utilisez stdio. S’il se trouve à une URL et que le fournisseur propose à la fois HTTP et SSE, choisissez HTTP, car SSE est le transport le plus ancien et ne subsiste surtout pour les serveurs qui n’ont pas encore migré.
Si gemini n’est pas encore dans votre PATH, installez-le avec npm install -g @google/gemini-cli. Ensuite, la commande d’ajout est la voie la plus rapide.
gemini mcp add [options] <name> <commandOrUrl> [args...]
Le nom vient en premier, puis l’exécutable ou l’URL, puis les arguments dont le serveur a besoin. Les options que vous utiliserez le plus :
| Option | Ce qu’elle fait |
|---|---|
-s, --scope | user ou project. La valeur par défaut est project. |
-t, --transport | stdio (par défaut), sse ou http |
-e, --env | Définit une variable d’environnement sous la forme NAME=value. Répétable. |
-H, --header | Définit un en-tête HTTP tel que "Authorization: Bearer abc123". Répétable. |
--timeout | Délai d’attente de la requête, en millisecondes |
--trust | Ignore les demandes de confirmation des outils pour ce serveur |
--description | Une courte note affichée dans les listes |
--include-tools, --exclude-tools | Listes d’autorisation et de blocage séparées par des virgules |
Un script local, enregistré pour votre utilisateur afin de fonctionner dans tous les dossiers :
gemini mcp add -s user -e ISSUES_TOKEN='$ISSUES_TOKEN' issues node /home/me/mcp/issues-server.js
Un serveur hébergé en HTTP streamable, avec un en-tête bearer :
gemini mcp add --transport http --header "Authorization: Bearer abc123" docs-search https://mcp.example.com/mcp
Un ancien point de terminaison SSE :
gemini mcp add --transport sse legacy-events http://localhost:8080/sse
La gestion au quotidien utilise la même famille de commandes :
gemini mcp list
gemini mcp disable issues --session
gemini mcp enable issues
gemini mcp remove issues -s user
L’option --session de enable et disable ne modifie l’état que pour la session en cours. Sans elle, le choix est enregistré dans ~/.gemini/mcp-server-enablement.json.
💡 Attention aux guillemets. Dans le premier exemple, les guillemets simples conservent
$ISSUES_TOKENcomme simple espace réservé. Avec des guillemets doubles, votre shell le développe d’abord et le vrai token se retrouve danssettings.json. Ouvrez le fichier après l’ajout d’un serveur et vérifiez.
💡 Les arguments qui commencent par un tiret, comme
npx -y, peuvent être pris pour des options de la CLI par l’analyseur. Pour les serveurs lancés de cette façon, rédigez plutôt l’entrée danssettings.json.
La commande d’ajout écrit le JSON à votre place. Modifier ce JSON directement vous donne accès à chaque champ, permet de relire votre configuration dans une pull request et facilite la copie d’un bloc fonctionnel vers un collègue.
~/.gemini/settings.json. Elle vous suit dans tous les dossiers..gemini/settings.json à l’intérieur du dépôt. Validez-le dans Git et toute l’équipe reçoit les mêmes serveurs.Le fichier de projet est lu après le fichier utilisateur, il l’emporte donc lorsque les deux définissent le même nom de serveur. Rappelez-vous que gemini mcp add écrit dans la portée projet, sauf si vous passez -s user.
Ce fichier enregistre un serveur par transport :
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"],
"timeout": 30000
},
"issues": {
"command": "node",
"args": ["./mcp/issues-server.js"],
"cwd": "/home/me/work/tracker",
"env": { "ISSUES_TOKEN": "$ISSUES_TOKEN" },
"includeTools": ["search_issues", "get_issue"]
},
"docs-search": {
"httpUrl": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer abc123" },
"timeout": 15000
},
"legacy-events": {
"url": "http://localhost:8080/sse"
}
}
}
Voici ce que fait chaque champ :
| Champ | Type | Remarques |
|---|---|---|
command, args, cwd | chaîne, tableau de chaînes, chaîne | Paramètres de lancement pour les serveurs stdio |
url | chaîne | Point de terminaison SSE |
httpUrl | chaîne | Point de terminaison HTTP streamable |
headers | objet | En-têtes personnalisés pour url ou httpUrl |
env | objet | Variables d’environnement transmises au serveur |
timeout | nombre | Délai d’attente de la requête, en millisecondes. La valeur par défaut est 600000, soit dix minutes. |
trust | booléen | Par défaut false. Lorsqu’il vaut true, les confirmations d’outils sont ignorées. |
includeTools | tableau de chaînes | Seuls ces outils sont activés |
excludeTools | tableau de chaînes | Ces outils sont désactivés. Cette liste l’emporte sur includeTools. |
oauth, authProviderType | objet, chaîne | Paramètres d’authentification, expliqués ci-dessous |
Dans le bloc env, Gemini CLI substitue $NAME et ${NAME} sur toutes les plateformes, et %NAME% sous Windows. Une variable non définie devient une chaîne vide, sans aucun avertissement. Le résultat est un serveur qui démarre, puis échoue à l’authentification, ce qui ressemble à un bug du serveur alors qu’il s’agit en réalité d’une faute de frappe dans le nom d’une variable.
Un fichier de projet est généralement validé dans Git, donc référencez les variables et ne collez jamais un secret dedans. La substitution des variables est documentée pour le bloc env, donc si vous voulez un token dans headers, vérifiez que votre version de la CLI le développe, ou gardez cette entrée en portée utilisateur, où elle n’atteint jamais le contrôle de version.
Connecter un serveur donne au modèle un nouvel ensemble de capacités. Décidez avant le premier prompt quelle part de ces capacités vous voulez lui accorder.
Supposons qu’un serveur expose search_issues, get_issue et delete_issue. Vous voulez les deux premiers et jamais le troisième :
"issues": {
"command": "node",
"args": ["./mcp/issues-server.js"],
"includeTools": ["search_issues", "get_issue"],
"excludeTools": ["delete_issue"]
}
excludeTools est prioritaire, donc un outil présent dans les deux listes est désactivé. Vous pouvez aussi filtrer des serveurs entiers depuis le niveau supérieur de settings.json :
"mcp": {
"allowed": ["issues", "filesystem"],
"excluded": ["experimental-server"]
}
Lorsque mcp.allowed est défini, seuls les serveurs qui y sont nommés se connectent. mcp.excluded bloque ceux que vous listez.
Par défaut, Gemini CLI demande avant d’exécuter un outil. Définir "trust": true, ou passer --trust lors de l’ajout d’un serveur, désactive toutes les confirmations pour ce serveur. C’est raisonnable pour un serveur en lecture seule que vous avez écrit vous-même. C’est une mauvaise idée pour tout ce qui peut écrire des fichiers, envoyer des messages ou exécuter des commandes, car un mauvais prompt pourrait le déclencher sans que vous l’ayez vu au préalable.
Beaucoup de serveurs hébergés exigent une connexion. Dans la CLI, lancez /mcp auth pour lister les serveurs compatibles OAuth, puis authentifiez-en un par son nom :
/mcp auth docs-search
La CLI ouvre votre navigateur, termine le parcours et stocke le token dans ~/.gemini/mcp-oauth-tokens.json. Les tokens expirés sont renouvelés automatiquement. Lorsqu’un serveur ne publie pas ses détails OAuth, ajoutez vous-même un bloc oauth :
"oauth": {
"enabled": true,
"clientId": "gemini-cli-client",
"authorizationUrl": "https://auth.example.com/oauth/authorize",
"tokenUrl": "https://auth.example.com/oauth/token",
"scopes": ["mcp:read"]
}
Tous les serveurs ne passent pas par OAuth. Un token bearer fixe va dans headers, comme indiqué plus haut. Pour les services sur Google Cloud, le champ authProviderType accepte google_credentials, ainsi que service_account_impersonation avec targetServiceAccount. Pour les serveurs protégés par Identity-Aware Proxy, ajoutez targetAudience avec l’identifiant client OAuth. Le fournisseur par défaut fonctionne pour la plupart des autres serveurs, donc laissez ce champ tranquille sauf si vous avez besoin de l’un de ces cas.
Modifiez le fichier, puis exécutez /mcp reload. Si la CLI affiche encore les anciens paramètres, redémarrez la session.
| Commande | Résultat |
|---|---|
/mcp ou /mcp list | Serveurs, état de connexion et outils |
/mcp desc | La même liste avec les descriptions des outils |
/mcp schema | Descriptions et schéma d’entrée de chaque outil |
/mcp auth <server> | Lance OAuth pour un serveur |
/mcp reload | Reconnecte tous les serveurs et actualise leurs outils |
/mcp enable, /mcp disable | Active ou désactive un serveur pour la session |
Hors session, gemini mcp list affiche la même vue d’ensemble des connexions depuis le shell.
Les versions récentes affichent les outils MCP avec un nom entièrement qualifié de la forme mcp_<server>_<tool>. Un outil search_issues sur un serveur nommé issues devient mcp_issues_search_issues. Les articles plus anciens décrivent un préfixe server__tool, utilisé lorsque deux serveurs exposent un outil de même nom. Si vous voyez un style dans un tutoriel et l’autre sur votre écran, vous utilisez probablement une version différente.
Deux conséquences pratiques en découlent. D’abord, nommez vos serveurs avec des tirets, non des tirets bas. Le nom est découpé au premier tiret bas après mcp_, et un tiret bas dans le nom d’un serveur peut perturber les règles de politique. Ensuite, vous avez rarement besoin du nom complet dans un prompt. Demandez en langage courant, par exemple :
Use the issues server to list open bugs labelled regression, newest first.
La CLI indique l’outil qu’elle prévoit d’appeler et demande une confirmation, sauf si vous définissez trust.
Commencez par les vérifications basiques, car elles règlent la plupart des cas :
command et args dans un terminal ordinaire. Si cela échoue là, cela échouera dans la CLI.cwd existe et que node, npx ou python3 est dans votre PATH.--debug et lisez les erreurs de connexion./mcp reload après chaque modification, et redémarrez la CLI si les anciens paramètres semblent persister.C’est un piège qui attrape les gens constamment. Dans un dossier que vous n’avez pas approuvé, Gemini CLI ne se connecte à aucun serveur MCP, et ignore entièrement le .gemini/settings.json du projet. Votre fichier de portée utilisateur est lu, mais les serveurs du projet n’apparaissent tout simplement pas.
Exécutez /permissions dans la CLI pour approuver le dossier, ou répondez à la boîte de dialogue de confiance lors de votre première ouverture. Le choix est enregistré dans ~/.gemini/trustedFolders.json. Pour les exécutions sans interface, la documentation mentionne l’option --skip-trust et la variable GEMINI_CLI_TRUST_WORKSPACE=true.
Certaines pannes ne donnent aucune erreur :
/mcp schema.timeout pour les serveurs distants instables, ou augmentez-le pour les tâches lentes comme les grosses requêtes.env. Elle a été remplacée par une chaîne vide.includeTools et excludeTools, ainsi que la liste mcp.allowed au niveau supérieur.💡 Un test de contrôle rapide : ajoutez d’abord un petit serveur stdio, faites-le se connecter, et seulement ensuite ajoutez les serveurs distants. Chaque nouveau serveur est un point de défaillance de plus, donc ajoutez-les un par un.
Vous pouvez utiliser un grand modèle de langage pour rédiger les parties fastidieuses d’une configuration, et Picasso IA héberge plusieurs modèles Gemini que vous pouvez ouvrir dans le navigateur. Voici un flux de travail qui fonctionne bien :
settings.json et la commande gemini mcp add équivalente. Indiquez au modèle d’utiliser des références $VARIABLE plutôt que des secrets en clair.command, url ou httpUrl doit être présent, et chaque nom dans includeTools doit correspondre à ce qu’affiche /mcp desc./mcp reload.💡 Considérez le brouillon comme une première version. Un modèle peut inventer un champ qui semble juste. Les tableaux de cet article et la documentation officielle font foi.
Une bonne configuration MCP ne représente que la moitié d’un flux de travail de développeur bien propre. L’autre moitié est constituée des contenus qui l’entourent : bannières de README, illustrations de tutoriels, cartes pour les réseaux sociaux et photos pour l’article de blog qui explique votre configuration.
Picasso IA vous permet de générer ces images en quelques minutes. Essayez Seedream 4.5 pour des scènes photoréalistes détaillées, GPT Image 2 lorsque vous avez besoin de texte net dans une image, ou Nano Banana 2 Lite pour des brouillons rapides. Rédigez un prompt court, générez quelques variations et gardez celle qui convient à votre page.
Choisissez un projet que vous avez ouvert aujourd’hui, rédigez un prompt décrivant sa bannière et voyez ce qui en sort. Parcourez tous les modèles disponibles sur picassoia.com/en/all-models, et commencez par celui qui correspond au style que vous avez en tête.
Choisissez votre langue
