Configuration du serveur MCP OpenCode

MCP (Model Context Protocol) est un protocole ouvert qui vous permet de connecter des outils externes et des sources de données à OpenCode. Après avoir ajouté un serveur MCP, les outils qu'il fournit sont automatiquement répertoriés aux côtés des outils intégrés d'OpenCode, et le LLM peut les appeler directement pendant les conversations.

OpenCode prend en charge deux types de serveurs MCP :

  • Local: Un processus MCP démarré via la ligne de commande sur votre machine, adapté aux outils et scripts locaux.
  • Distant: Un service MCP distant connecté via HTTPS, adapté aux services cloud et aux plateformes tierces.

Rappel sur la consommation de contexte :Chaque serveur MCP consomme de l'espace de contexte dans la conversation. Plus il y a d'outils activés, plus de tokens sont consommés par conversation, et plus il est facile d'atteindre la limite de contexte du modèle. Il est recommandé de n'activer que les serveurs MCP réellement nécessaires pour la tâche en cours et de les désactiver une fois terminé. Certains serveurs (comme GitHub MCP) ont un grand nombre d'outils et consomment particulièrement beaucoup de tokens, alors faites-y particulièrement attention lorsque vous les utilisez.

Structure de configuration de base

Toutes les configurations de serveur MCP sont écrites sous leopencode.jsondemcpchamp. Chaque serveur nécessite unnom uniquecomme nom de clé, qui peut également être utilisé dans le prompt pour spécifier quel MCP appeler :

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {         // 服务器名称（自定义，全局唯一）
      "type": "local",         // 连接类型：local ou  remote
      // ...其他配置项
      "enabled": true          // 是否启用，默认为 true
    },
    "another-mcp-server": {    // 可同时配置多个 MCP 服务器
      "type": "remote",
      // ...
    }
  }
}

vaenabledDéfini àfalsepeut désactiver temporairement un serveur sans le retirer du fichier de configuration, ce qui permet de l'activer ou de le désactiver facilement à la demande :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": false          // Temporairement désactivé, configuration conservée ; il suffit de remettre sur true lorsque nécessaire
    }
  }
}

Serveur MCP local

Un serveur MCP local fournit des outils en exécutant un processus de commande sur votre machine. Définisseztypeà"local", et spécifiez la commande de démarrage viacommand:

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",                                   // Type de connexion : local
      "command": ["npx", "-y", "my-mcp-command"],        // Tableau de la commande de démarrage :
                                                         // Le premier élément est l'exécutable,
                                                         // Les éléments suivants sont des arguments
                                                         // Peut aussi être écrit sous la forme ["bun", "x", "my-mcp-command"]
      "enabled": true,
      "environment": {                                   // Variables d'environnement injectées au moment de l'exécution (facultatif)
        "MY_ENV_VAR": "my_env_var_value"
      }
    }
  }
}

Options de configuration du serveur local

Élément de configuration Type Requis Description
type String Oui Type de connexion ; doit être renseigné pour les serveurs locaux"local"
command Tableau Oui La commande et les arguments pour démarrer le serveur MCP, sous forme de tableau, par ex.["npx", "-y", "my-mcp"]
environment Object non Variables d'environnement injectées lors de l'exécution du serveur, sous forme de paires clé-valeur
enabled Boolean non Indique si le serveur doit être activé au démarrage ; la valeur par défaut esttrue
timeout Number non Délai d'attente (en millisecondes) pour récupérer la liste des outils depuis le serveur MCP ; la valeur par défaut est5000(5 secondes)

Exemple : ajout d'un serveur MCP de test

Ci-dessous se trouve un exemple d'ajout du serveur MCP de test officiel@modelcontextprotocol/server-everything, qui peut être utilisé pour vérifier si la fonctionnalité MCP fonctionne correctement :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
      // npx -y signifie confirmer automatiquement l'installation ; pas besoin d'exécuter manuellement npm install
    }
  }
}

Une fois la configuration terminée, ajoutez le nom du serveur au prompt pour permettre au LLM d'appeler les outils de ce MCP :

use the mcp_everything tool to add the number 3 and 4

Serveur MCP distant

Un serveur MCP distant se connecte aux services cloud via HTTPS. Définisseztypeà"remote", et spécifiez l'adresse du serveur viaurl:

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",                               // Type de connexion : distant
      "url": "https://my-mcp-server.com",             // Adresse du serveur distant (obligatoire)
      "enabled": true,
      "headers": {                                    // En-têtes HTTP envoyés avec les requêtes (facultatif)
        "Authorization": "Bearer MY_API_KEY"          // Couramment utilisé pour l'authentification par clé API
      }
    }
  }
}

Options de configuration du serveur distant

Élément de configuration Type Requis Description
type String Oui Type de connexion ; doit être renseigné pour les serveurs distants"remote"
url String Oui L'adresse HTTPS complète du serveur MCP distant
enabled Boolean non Indique si le serveur doit être activé au démarrage ; la valeur par défaut esttrue
headers Object non En-têtes HTTP envoyés avec chaque requête, couramment utilisés pour l'authentification par clé API
oauth Objet /false non Configuration de l'authentification OAuth, ou défini surfalsepour désactiver la détection automatique d'OAuth
timeout Number non Délai d'attente (en millisecondes) pour récupérer la liste des outils depuis le serveur MCP ; la valeur par défaut est5000(5 secondes)

Référencement des variables d'environnement

Dans le fichier de configuration,les informations sensibles telles que les clés API ne doivent pas être écrites directement en clair. OpenCode prend en charge la lecture des variables d'environnement système à l'exécution via la{env:变量名}syntaxe :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"    // Lit automatiquement la valeur de la variable d'environnement MY_API_KEY à l'exécution
                                                      // La variable d'environnement doit être définie au préalable dans le système :
                                                      // export MY_API_KEY=your_actual_key
      }
    }
  }
}

Authentification OAuth

OpenCode dispose d'une prise en charge intégrée de l'authentification OAuth pour les serveurs MCP distants. L'ensemble du processus est presque entièrement automatique, sans avoir à gérer les jetons manuellement.

Flux d'authentification automatique

Lorsque le serveur exige une authentification OAuth, OpenCode exécute automatiquement les étapes suivantes :

  1. Détecte une réponse 401 (Non autorisé) du serveur
  2. Démarre automatiquement le flux d'autorisation OAuth et ouvre un navigateur pour vous guider tout au long de la connexion
  3. Lorsque le serveur le prend en charge, enregistre automatiquement l'application à l'aide de l'enregistrement dynamique du client (RFC 7591)
  4. Stocke de manière sécurisée le jeton obtenu dans~/.local/share/opencode/mcp-auth.jsonMoyenne
  5. Les requêtes suivantes transportent automatiquement le jeton ; plus besoin de se connecter à plusieurs reprises

1. OAuth automatique (aucune configuration supplémentaire requise)

Pour la plupart des serveurs MCP qui prennent en charge OAuth, il suffit de configurerurlet OpenCode vous guidera automatiquement tout au long de l'authentification lors de la première utilisation :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
      // Aucune configuration supplémentaire n'est nécessaire ; OpenCode gère automatiquement le flux OAuth
    }
  }
}

Vous pouvez également déclencher manuellement le flux d'authentification (par ex., pour vous reconnecter après l'expiration d'un jeton) :

opencode mcp auth my-oauth-server

2. Identifiants client pré-enregistrés

Si vous avez déjà obtenu un ID client et un secret fixes auprès du fournisseur de services, vous pouvez les spécifier directement dans la configuration et ignorer l'étape d'enregistrement dynamique :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",          // Lire depuis les variables d'environnement pour éviter une exposition en clair
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"             // Les portées d'autorisation demandées ; les valeurs spécifiques sont définies par le fournisseur de services
      }
    }
  }
}

3. Désactivation d'OAuth (utilisation de l'authentification par clé API)

Si le serveur utilise une clé API au lieu de l'authentification OAuth, vous pouvez définiroauthàfalsepour désactiver la détection automatique d'OAuth et utiliserheaderspour passer la clé :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,                                   // Désactiver la détection automatique d'OAuth
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"     // Utiliser directement l'authentification par clé API
      }
    }
  }
}

Options de configuration OAuth

Élément de configuration Type Description
oauth Objet /false Objet de configuration OAuth ; défini surfalsepour désactiver complètement la détection automatique d'OAuth
clientId String ID client OAuth. Si non fourni, OpenCode tentera un enregistrement dynamique du client
clientSecret String Secret client OAuth (si requis par le serveur d'autorisation)
scope String Portées de permission demandées lors de l'autorisation. Les portées multiples sont séparées par des espaces ; les valeurs spécifiques sont définies par le fournisseur de service

Commandes de gestion de l'authentification

OpenCode fournit un ensemble d'outils en ligne de commande pour gérer l'état d'authentification MCP :

# 对指定 MCP 服务器进行身份验证（会打开浏览器完成 OAuth 授权）
opencode mcp auth my-oauth-server

# 列出所有已配置的 MCP 服务器及其当前认证状态
opencode mcp list

# 删除指定服务器已存储的凭据（下次使用时需要重新登录）
opencode mcp logout my-oauth-server

# 调试指定服务器的连接和 OAuth 流程（显示认证状态、测试连接、执行 OAuth 发现流程）
opencode mcp debug my-oauth-server

# 查看所有支持 OAuth 的服务器的认证状态
opencode mcp auth list

Surcharge de la configuration par défaut distante

Les organisations peuvent fournir.well-known/opencodedes configurations de serveur MCP prédéfinies aux membres via des points de terminaison. Ces serveurs peuvent être désactivés par défaut. Si vous devez en activer un, ajoutez une entrée portant le même nom dans votre configuration locale et définissezenabled: truepour l'activer.La configuration locale surchargera les valeurs par défaut distantes：

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {                                         // Correspond au nom du serveur dans la configuration distante de l'organisation
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true                                 // Définir sur true localement pour surcharger l'état désactivé par défaut distant
    }
  }
}

Gestion des outils

Une fois qu'un serveur MCP est enregistré, ses outils apparaissent sous服务器名称_工具名称la forme de dans la liste d'outils d'OpenCode, et peuvent être géréstoolsvia le champ pour une gestion unifiée.

1. Désactivation globale des outils d'un MCP spécifique

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp-foo": false    // Désactiver tous les outils du serveur my-mcp-foo (le serveur démarre toujours, mais ses outils sont indisponibles)
  }
}

2. Désactivation par lots avec des motifs Glob

L'utilisation de jokers Glob permet de faire correspondre et de désactiver les outils de plusieurs serveurs MCP à la fois :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp*": false    // Motif Glob : désactiver les outils de tous les serveurs dont les noms commencent par my-mcp
  }
}

3. Activation d'outils MCP spécifiques par agent

Si vous avez configuré de nombreux serveurs MCP mais que chaque agent n'a besoin que d'un sous-ensemble, vous pouvez d'abord désactiver globalement tous les outils MCP, puis les activer selon les besoins dans des configurations d'agent spécifiques. Cela permet de contrôler précisément les outils auxquels chaque agent peut accéder, en évitant de gaspiller du contexte :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "en: true         // Le serveur lui-même reste en cours d'exécution (sinon l'agent ne peut pas non plus être utilisé)
    }
  },
  "tools": {
    "my-mcp*": false          // Étape 1 : désactiver tous les outils de ce MCP afin qu'ils soient indisponibles dans les conversations
  },
  "agent": {
    "my-mcp": {
      "tools": {
        "my-mcp": true       // Étape 2 : l'activer dans l'agent my-mcp ; les autres agents ne sont pas affectés
      }
    }
  }
}

Règles des motifs Glob

Joker Signification Exemple
* Correspond à zéro ou plusieurs caractères arbitraires my-mcp*matchesmy-mcp_search、my-mcp_listwait
? Correspond exactement à un caractère arbitraire my-mcp?matchesmy-mcpA, mais ne correspond pas àmy-mcpAB
autres caractères Correspond littéralement et exactement my-mcp-fooNe correspond qu'aux serveurs dont les noms sont exactement identiques

Les outils du serveur MCP sont préfixés par le nom du serveur lors de l’enregistrement. Par exemple, les outils du serveurmyserversont enregistrés commemyserver_toolname. Par conséquent, pour désactiver tous les outils d’un serveur, utilisez"myserver_*": falsepour une correspondance exacte.

Exemples de configuration

Sentry

Ajoutez le serveur MCP Sentry pour interroger les erreurs, les problèmes et les données d’événements des projets Sentry directement dans les conversations :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}      // Un objet vide active l’authentification automatique OAuth ; OpenCode gérera automatiquement l’intégralité du flux OAuth
    }
  }
}

Après avoir ajouté la configuration, exécutez la commande suivante pour terminer l’autorisation du compte (un navigateur s’ouvrira pour la connexion OAuth) :

opencode mcp auth sentry

Une fois l’authentification terminée, ajoutezuse sentryà votre prompt pour invoquer les outils Sentry :

Show me the latest unresolved issues in my project. use sentry

Context7

Ajoutez le serveur MCP Context7 pour rechercher divers documents techniques dans les conversations, aidant les LLM à obtenir les références d'API les plus récentes et précises :

Exemple

// Version de base (sans optimisation de la limitation de débit)
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Exemple

// Après avoir créé un compte gratuit, l'utilisation d'une clé API offre des limites de débit plus élevées
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"    // Lire la clé API depuis une variable d'environnement
                                                        // Doit être défini à l'avance : export CONTEXT7_API_KEY=your_key
      }
    }
  }
}

Adduse context7à votre prompt pour invoquer la fonctionnalité de recherche de documents :

Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7

Vous pouvez également ajouter des règles globales dans le projetAGENTS.mdpour permettre au LLM d'utiliser automatiquement Context7 lorsqu'il doit consulter la documentation, sans avoir à le préciser manuellement à chaque fois :

When you need to search docs, use `context7` tools.

Grep par Vercel

Ajoutez le serveur MCP Grep by Vercel pour rechercher de véritables extraits de code sur GitHub directement dans les conversations, aidant les LLM à trouver la bonne utilisation des API et des références d'implémentation :

Exemple

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {           // Serveur nommé gh_grep, référencé par ce nom dans les prompts
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

Adduse the gh_grep toolà votre prompt pour rechercher des exemples de code sur GitHub :

What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool

De même, vous pouvez définir des règles globales dansAGENTS.mdpour permettre au LLM de rechercher automatiquement des exemples de code en cas de doute sur l'utilisation :

If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
Autres extensions