Config MCP OpenCode : ajouter des serveurs, OAuth et corriger les timeouts

Vous ajoutez un serveur MCP à opencode.json, redémarrez le terminal, et les outils n’apparaissent jamais. Ou bien ils apparaissent, la connexion par navigateur s’ouvre, et le callback n’arrive jamais. Ou tout fonctionne jusqu’à ce que le premier appel lent expire avec un timeout. Ces trois échecs expliquent la plupart des problèmes de config MCP OpenCode, et chacun a une solution courte et banale.

Cet article détaille les champs exacts que lit OpenCode, les commandes qui indiquent ce qui ne va pas, et les réglages qui mettent fin aux tâtonnements. Les extraits suivent la documentation officielle de MCP pour OpenCode telle que vérifiée en octobre 2026. Collez-les donc tels quels et ne changez que les noms, chemins et URL.

Où OpenCode lit sa configuration

OpenCode ne choisit pas un seul fichier de configuration en ignorant les autres. Il fusionne toutes les sources qu’il trouve, et lorsque deux sources définissent le même champ, la dernière dans l’ordre ci-dessous l’emporte. C’est pourquoi un serveur que vous avez « supprimé » du fichier du projet continue de réapparaître : il est toujours défini dans votre fichier global.

Emplacements des configurations et ordre de fusion

Le JSON comme le JSONC (JSON avec commentaires) fonctionnent. Ajouter "$schema": "https://opencode.ai/config.json" en haut donne à votre éditeur l’autocomplétion et les soulignements rouges sur les fautes de frappe. Les fautes de frappe sont la raison la plus fréquente pour laquelle un serveur est ignoré sans bruit, donc cette ligne de schéma se rentabilise en quelques minutes.

💡 Astuce : Quand un serveur se comporte étrangement, vérifiez d’abord le fichier global. Une entrée obsolète peut y écraser une entrée de projet parfaitement correcte.

Utiliser des variables, pas des secrets collés

OpenCode remplace deux marqueurs partout dans la configuration. {env:NAME} lit une variable d’environnement, et {file:path} insère le contenu d’un fichier. Utilisez-les pour chaque token, afin que la configuration reste sûre à versionner.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tracker": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:TRACKER_TOKEN}"
      }
    }
  }
}

Copier le prompt

Les chemins de fichiers relatifs se résolvent depuis le répertoire de configuration, tandis que les chemins commençant par / ou ~ sont absolus. Si la variable est absente du shell qui a lancé OpenCode, le serveur ne reçoit jamais un token valide et répond 401, ce qui ressemble exactement à un mauvais token. Exportez la variable dans le même shell, puis lancez OpenCode depuis celui-ci.

Ajouter des serveurs locaux et distants

Tout se trouve sous un champ de premier niveau nommé mcp. Chaque enfant est un serveur avec un nom que vous choisissez, et ce nom devient le préfixe de ses outils. Choisissez donc des noms courts, en minuscules et sans espaces.

Un serveur local minimal

Un serveur local est un processus que OpenCode démarre pour vous et avec lequel il communique via l’entrée et la sortie standard.

{
  "mcp": {
    "files": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home/dev/projects"],
      "enabled": true,
      "timeout": 15000
    }
  }
}

Copier le prompt

Deux champs sont obligatoires : "type": "local" et command. Le point qui piège les gens est que command est un tableau de chaînes, une entrée par argument, et non une seule chaîne de shell. Écrire "command": "npx -y some-server" est le moyen le plus rapide d’obtenir un serveur qui ne démarre jamais.

Variables d’environnement et répertoire de travail

Les serveurs locaux ont souvent besoin d’identifiants ou d’un dossier précis. environment transmet des variables au processus enfant, et cwd définit son répertoire de travail. Les chemins relatifs dans cwd se résolvent depuis l’espace de travail.

{
  "mcp": {
    "reports": {
      "type": "local",
      "command": ["node", "./tools/reports-server.js"],
      "cwd": "./mcp",
      "environment": {
        "API_TOKEN": "{env:REPORTS_API_TOKEN}",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Copier le prompt

Un serveur distant avec des en-têtes

Un serveur distant tourne déjà ailleurs, donc OpenCode n’a besoin que d’une adresse et, généralement, d’un identifiant.

{
  "mcp": {
    "docs": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:DOCS_MCP_TOKEN}"
      },
      "oauth": false,
      "timeout": 20000
    }
  }
}

Copier le prompt

Définir "oauth": false est le bon réflexe pour tout serveur qui s’authentifie avec un token statique. Sans cela, OpenCode traite un 401 comme un signal pour lancer une connexion OAuth, ce qui prête à confusion quand le vrai problème est un mauvais token.

Vérifier le résultat avec mcp list

Exécutez opencode mcp list après chaque modification. Elle affiche chaque serveur configuré et son statut, ce qui vous indique en deux secondes si un serveur est connecté, demande une authentification ou a échoué. Faites-le avant d’ouvrir une session et de vous demander pourquoi les outils manquent.

Voici la référence complète des champs en un seul endroit :

💡 Astuce : Définissez "enabled": false sur les serveurs dont vous n’avez besoin que de temps en temps. L’entrée reste dans le fichier, et rien ne se charge dans votre session tant que vous ne la réactivez pas.

Corriger les problèmes de connexion OAuth

Les serveurs distants qui suivent le flux d’autorisation MCP demandent presque aucune configuration. Lorsque OpenCode reçoit un 401, il lance OAuth tout seul, s’enregistre comme client via Dynamic Client Registration (RFC 7591), ouvre votre navigateur et attend la redirection. Les tokens obtenus sont stockés dans ~/.local/share/opencode/mcp-auth.json.

Fonctionnement de l’OAuth automatique

Pour un serveur qui le prend en charge, toute la configuration tient en deux champs et une commande.

1. Ajoutez le serveur avec uniquement type et url.
2. Exécutez opencode mcp auth tracker en remplaçant tracker par le nom de votre serveur.
3. Approuvez la demande dans l’onglet du navigateur qui s’ouvre.
4. Exécutez opencode mcp list et vérifiez que le serveur s’affiche comme connecté.

Quatre commandes couvrent tout le cycle de vie :

Quand une connexion qui fonctionnait la semaine dernière échoue soudainement, la cause est généralement un token périmé ou révoqué. Exécutez opencode mcp logout <name>, puis opencode mcp auth <name> à nouveau, et vous repartez de zéro.

Clients préenregistrés et scopes

Certains fournisseurs refusent l’enregistrement dynamique et exigent que vous enregistriez une application à la main. Dans ce cas, donnez à OpenCode les détails du client qu’il aurait sinon créés lui-même.

{
  "mcp": {
    "tracker": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:TRACKER_CLIENT_ID}",
        "clientSecret": "{env:TRACKER_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

Copier le prompt

La valeur scope est une chaîne unique dont les scopes sont séparés par des espaces, exactement comme le fournisseur les documente. Demandez le plus petit ensemble qui fonctionne. Un scope trop large que le fournisseur rejette produit une erreur sur la page de connexion qui n’indique rien d’utile sur le scope en cause.

La connexion échoue sur une machine distante

C’est celui qui fait perdre un après-midi. OpenCode écoute sur un port de callback local pendant que vous vous connectez, et les retours d’utilisateurs placent le port par défaut à 19876. Si OpenCode tourne sur un hôte distant via SSH, votre navigateur sur l’ordinateur portable redirige vers 127.0.0.1:19876 sur l’ordinateur portable, où personne n’écoute. L’approbation réussit, le callback n’arrive jamais, et la commande finit par expirer.

La solution est une redirection de port de votre ordinateur portable vers l’hôte distant :

ssh -o ExitOnForwardFailure=yes -L 127.0.0.1:19876:127.0.0.1:19876 user@remote-host

Copier le prompt

Exécutez opencode mcp auth <name> dans cette session SSH, ouvrez l’URL affichée dans votre navigateur local, et le callback passe désormais par le tunnel.

Les versions récentes acceptent aussi callbackPort et redirectUri dans l’objet oauth, pour les fournisseurs qui exigent un callback fixe et préenregistré. L’URI de redirection doit utiliser http:// avec localhost, 127.0.0.1 ou [::1] et un port explicite. Si vous changez de port, redirigez ce même port. Vérifiez le schéma dans votre éditeur avant de vous fier à l’un de ces champs, car les anciennes versions ne les connaissent pas.

Solutions aux délais d’attente qui fonctionnent

Il existe deux délais différents, et les confondre fait perdre des heures. Le premier détermine combien de temps OpenCode attend qu’un serveur démarre et liste ses outils. L’autre détermine combien de temps un appel d’outil unique peut durer une fois le serveur lancé.

La valeur de démarrage par défaut

Le champ timeout est exprimé en millisecondes et vaut 5000 par défaut, pour les serveurs locaux comme distants. Cinq secondes suffisent pour un petit script. Ce n’est pas assez pour npx -y avec un cache froid, car le paquet doit se télécharger avant même que le serveur démarre. Le serveur apparaît alors en échec et ses outils ne se chargent jamais.

Corrigez dans cet ordre :

1. Augmentez le champ pour ce serveur uniquement. Définissez "timeout": 15000 ou 30000 sur l’entrée lente et laissez les autres tranquilles.
2. Supprimez le téléchargement. Installez le paquet globalement avec npm install -g, puis pointez command vers le binaire installé. Le démarrage tombe à une fraction de seconde.
3. Testez le point d’accès des serveurs distants. Exécutez un simple curl sur l’URL. Si curl est lent aussi, le problème vient du réseau ou du serveur, pas de votre configuration.

Quand les appels d’outils échouent à 60 secondes

Une autre erreur apparaît plus tard, au milieu d’une session : MCP error -32001: Request timed out. C’est le délai de requête de la bibliothèque cliente MCP, et de nombreux clients construits sur le SDK TypeScript utilisent 60 secondes par défaut. Augmenter le timeout de démarrage ne le change pas pour un appel d’outil en cours.

Cherchez d’abord un réglage par requête dans le schéma de votre version. S’il n’y en a pas, changez l’outil plutôt que le client. Faites en sorte que le premier outil renvoie immédiatement un identifiant de tâche, et ajoutez un second outil qui indique le statut de la tâche. Le modèle soumet, reçoit un identifiant et revient vérifier, ce qui correspond au schéma soumettre-puis-interroger qu’utilisent les API de génération d’images et de vidéos pour la même raison.

💡 Astuce : Envoyez les journaux du serveur vers stderr, jamais vers stdout. Un serveur local partage stdout avec le protocole, donc un seul console.log égaré peut corrompre la poignée de main et ressembler à un délai d’attente.

Déboguer un serveur qui ne se connecte pas

Quand la solution n’est pas évidente, arrêtez de modifier la configuration et testez chaque couche séparément.

Lancer le serveur à la main

Copiez le tableau command dans un terminal et exécutez-le sur une seule ligne. Un serveur stdio en bonne santé démarre et attend silencieusement une entrée. S’il affiche une erreur, un module manquant ou un mauvais chemin, vous avez trouvé le problème sans qu’OpenCode intervienne. Exécutez ensuite opencode mcp debug <name>, qui diagnostique les problèmes de connexion et d’OAuth pour ce seul serveur.

Pour un serveur distant, curl -i l’URL avec les mêmes en-têtes. Un 401 signifie des identifiants, un 404 signifie un mauvais chemin, et un blocage signifie un problème réseau.

Erreurs courantes et solutions

Limiter le contexte par agent

Chaque serveur connecté ajoute ses descriptions d’outils au contexte envoyé à chaque requête. Quelques serveurs peuvent consommer une large part de la fenêtre avant même que vous ayez tapé un mot, et le modèle choisit moins bien le bon outil quand il doit en choisir parmi cinquante. La documentation d’OpenCode le dit d’ailleurs : utilisez les serveurs MCP avec parcimonie.

Désactiver globalement, activer par agent

Les noms d’outils portent le nom du serveur en préfixe, donc un motif glob permet de basculer un serveur entier d’un coup. * correspond à zéro caractère ou plus, et ? correspond à exactement un caractère.

{
  "tools": {
    "files_*": false,
    "tracker_*": false
  },
  "agent": {
    "builder": {
      "tools": { "files_*": true }
    },
    "planner": {
      "tools": { "tracker_*": true }
    }
  }
}

Copier le prompt

Avec cette configuration, l’agent builder ne voit que les outils de système de fichiers et l’agent planner ne voit que le suivi. Aucun des deux ne paie le coût en tokens de la liste d’outils de l’autre serveur.

Comment utiliser Claude Sonnet 5

Les bugs de configuration sont un travail de reconnaissance de motifs fastidieux : une chaîne là où il faut un tableau, une variable non exportée, un port que personne n’a redirigé. C’est là qu’un modèle de code gagne son temps. Claude Sonnet 5 sur PicassoIA lit du texte de configuration, des erreurs de terminal et même des captures d’écran, donc vous pouvez coller ce que vous voyez et demander ce qui ne va pas.

1. Ouvrez la page du modèle. Rendez-vous sur Claude Sonnet 5 sur PicassoIA et trouvez la zone de prompt.
2. Collez votre bloc mcp. Remplacez d’abord chaque token et chaque secret par un marqueur, puis ajoutez la sortie de opencode mcp debug <name>.
3. Réglez l’effort. Le réglage low par défaut saute la réflexion et répond le plus vite. Utilisez medium ou high quand plusieurs fichiers interagissent, par exemple une configuration globale surchargée par une configuration de projet.
4. Ajoutez un prompt système une fois. Quelque chose comme : « You review opencode.json MCP configs. Check type, command, timeout and oauth. Reply with corrected JSON only. »
5. Joignez une capture d’écran si vous en avez une. L’entrée image lit les erreurs du terminal. Augmentez la résolution maximale de l’image quand le texte de la capture est petit.
6. Gardez max_tokens à 8192. C’est la valeur par défaut, et elle suffit largement pour quelques blocs de configuration.
7. Vérifiez avant de coller. Contrôlez chaque champ suggéré par rapport au tableau ci-dessus et à la documentation officielle.

💡 Astuce : Ne collez jamais un vrai token dans une zone de chat. Des marqueurs comme TRACKER_TOKEN suffisent au modèle.

Créez vos propres images dès aujourd’hui

La configuration ne représente qu’une partie de ce que MCP permet. Une fois qu’un agent de code peut appeler des outils, il peut aussi appeler des générateurs d’images. PicassoIA expose ses générateurs via MCP, et l’adresse du serveur se trouve sur la page des connexions MCP de votre compte. Tout serveur qui parle HTTP suit le même modèle distant que dans cet article : type, url, un en-tête ou OAuth, et un timeout raisonnable.

Si vous préférez vous passer de la configuration et simplement créer des images, ouvrez PicassoIA et essayez ces modèles de texte vers image :

• PicassoIA Image pour des résultats rapides et polyvalents
• Seedream 5 Pro pour des scènes détaillées et photographiques
• GPT Image 2 pour les prompts aux mises en page précises
• FLUX 2 Pro pour des textures nettes et une lumière naturelle

Choisissez-en un, écrivez un prompt sur ce que vous venez de configurer, et comparez la façon dont chaque modèle le lit. Dix minutes d’essais vous apprennent davantage sur la formulation des prompts qu’une heure de lecture, et chaque image générée est une répétition gratuite pour la suivante.