OpenCode-MCP-Server-Konfiguration

MCP (Model Context Protocol) ist ein offenes Protokoll, mit dem Sie externe Tools und Datenquellen mit OpenCode verbinden können. Nach dem Hinzufügen eines MCP-Servers werden die von ihm bereitgestellten Tools automatisch neben den integrierten Tools von OpenCode aufgeführt, und das LLM kann sie während Gesprächen direkt aufrufen.

OpenCode unterstützt zwei Arten von MCP-Servern:

  • Lokal: Ein MCP-Prozess, der über die Befehlszeile auf Ihrem Rechner gestartet wird, geeignet für lokale Tools und Skripte.
  • Remote: Ein Remote-MCP-Dienst, der über HTTPS verbunden wird, geeignet für Cloud-Dienste und Drittanbieter-Plattformen.

Hinweis zum Kontextverbrauch:Jeder MCP-Server belegt Kontextplatz in der Unterhaltung. Je mehr Tools aktiviert sind, desto mehr Tokens werden pro Unterhaltung verbraucht und desto leichter wird das Kontextlimit des Modells erreicht. Es wird empfohlen, nur die MCP-Server zu aktivieren, die für die aktuelle Aufgabe tatsächlich benötigt werden, und sie nach Erledigung wieder zu deaktivieren. Einige Server (wie GitHub MCP) haben eine große Anzahl von Tools und verbrauchen besonders viele Tokens; bitte achten Sie bei ihrer Verwendung besonders darauf.

Grundlegende Konfigurationsstruktur

Alle MCP-Server-Konfigurationen werden unter demopencode.jsonvonmcpFeld geschrieben. Jeder Server benötigt eineneindeutigen Namenals Schlüsselnamen, der auch im Prompt verwendet werden kann, um anzugeben, welcher MCP aufgerufen werden soll:

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

wirdenabledSetzen auffalsekann einen Server vorübergehend deaktivieren, ohne ihn aus der Konfigurationsdatei zu entfernen, was das Umschalten bei Bedarf erleichtert:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": false          // Vorübergehend deaktiviert, Konfiguration beibehalten; einfach wieder auf true setzen, wenn benötigt
    }
  }
}

Lokaler MCP-Server

Ein lokaler MCP-Server stellt Tools bereit, indem er einen Befehlsprozess auf Ihrem Rechner ausführt. Legen Sietypeauf"local", und geben Sie den Startbefehl übercommand:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",                                   // Verbindungstyp: lokal
      "command": ["npx", "-y", "my-mcp-command"],        // Startbefehl-Array:
                                                         // Das erste Element ist die ausführbare Datei,
                                                         // Nachfolgende Elemente sind Argumente
                                                         // Kann auch als ["bun", "x", "my-mcp-command"] geschrieben werden
      "enabled": true,
      "environment": {                                   // Umgebungsvariablen, die zur Laufzeit injiziert werden (optional)
        "MY_ENV_VAR": "my_env_var_value"
      }
    }
  }
}

Konfigurationsoptionen für lokale Server

Konfigurationselement Type Erforderlich Beschreibung
type String Ja Verbindungstyp; muss für lokale Server ausgefüllt werden"local"
command Array Ja Der Befehl und die Argumente zum Starten des MCP-Servers, in Array-Form, z. B.["npx", "-y", "my-mcp"]
environment Objekt nein Umgebungsvariablen, die beim Ausführen des Servers injiziert werden, in Schlüssel-Wert-Paar-Form
enabled Boolean nein Ob der Server beim Start aktiviert werden soll; Standardwert isttrue
timeout Number nein Timeout (in Millisekunden) für das Abrufen der Tool-Liste vom MCP-Server; Standardwert ist5000(5 Sekunden)

Beispiel: Hinzufügen eines Test-MCP-Servers

Nachfolgend ein Beispiel für das Hinzufügen des offiziellen Test-MCP-Servers@modelcontextprotocol/server-everything, mit dem überprüft werden kann, ob die MCP-Funktionalität korrekt funktioniert:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
      // npx -y bedeutet, die Installation automatisch zu bestätigen; npm install muss nicht manuell ausgeführt werden
    }
  }
}

Nach Abschluss der Konfiguration fügen Sie den Servernamen zum Prompt hinzu, damit das LLM die Tools dieses MCP aufrufen kann:

use the mcp_everything tool to add the number 3 and 4

Remote-MCP-Server

Ein Remote-MCP-Server verbindet sich über HTTPS mit Cloud-Diensten. Setzetypeauf"remote", und gib die Serveradresse an überurl:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",                               // Verbindungstyp: remote
      "url": "https://my-mcp-server.com",             // Remote-Server-Adresse (erforderlich)
      "enabled": true,
      "headers": {                                    // HTTP-Header, die mit Anfragen gesendet werden (optional)
        "Authorization": "Bearer MY_API_KEY"          // Wird häufig für die API-Schlüssel-Authentifizierung verwendet
      }
    }
  }
}

Konfigurationsoptionen für Remote-Server

Konfigurationselement Type Erforderlich Beschreibung
type String Ja Verbindungstyp; muss für Remote-Server ausgefüllt werden"remote"
url String Ja Die vollständige HTTPS-Adresse des Remote-MCP-Servers
enabled Boolean nein Ob der Server beim Start aktiviert werden soll; Standardwert isttrue
headers Objekt nein HTTP-Header, die mit jeder Anfrage gesendet werden, häufig für die API-Schlüssel-Authentifizierung verwendet
oauth Object /false nein OAuth-Authentifizierungskonfiguration oder auf ... setzenfalseum die automatische OAuth-Erkennung zu deaktivieren
timeout Number nein Timeout (in Millisekunden) für das Abrufen der Tool-Liste vom MCP-Server; Standardwert ist5000(5 Sekunden)

Referenzieren von Umgebungsvariablen

In der Konfigurationsdatei solltensensible Informationen wie API-Schlüssel nicht direkt im Klartext geschrieben werden. OpenCode unterstützt das Lesen von Systemumgebungsvariablen zur Laufzeit über die{env:变量名}Syntax:

Beispiel

{
  "$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}"    // Liest automatisch den Wert der Umgebungsvariable MY_API_KEY zur Laufzeit
                                                      // Die Umgebungsvariable muss vorab im System gesetzt werden:
                                                      // export MY_API_KEY=your_actual_key
      }
    }
  }
}

OAuth-Authentifizierung

OpenCode bietet integrierte OAuth-Authentifizierungsunterstützung für entfernte MCP-Server. Der gesamte Prozess ist nahezu vollautomatisch, ohne dass Tokens manuell behandelt werden müssen.

Automatischer Authentifizierungsablauf

Wenn der Server eine OAuth-Authentifizierung erfordert, führt OpenCode automatisch die folgenden Schritte aus:

  1. Erkennt eine 401-Antwort (Unauthorized) vom Server
  2. Startet automatisch den OAuth-Autorisierungsablauf und öffnet einen Browser, um Sie durch die Anmeldung zu führen
  3. Registriert die Anwendung automatisch mithilfe der dynamischen Client-Registrierung (RFC 7591), wenn der Server dies unterstützt
  4. Speichert das erhaltene Token sicher in~/.local/share/opencode/mcp-auth.jsonMittel
  5. Nachfolgende Anfragen enthalten das Token automatisch; kein wiederholtes Anmelden erforderlich

1. Automatisches OAuth (keine zusätzliche Konfiguration erforderlich)

Für die meisten MCP-Server, die OAuth unterstützen, konfigurieren Sie einfachurlund OpenCode führt Sie bei der ersten Verwendung automatisch durch die Authentifizierung:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
      // Keine zusätzliche Konfiguration erforderlich; OpenCode übernimmt den OAuth-Ablauf automatisch
    }
  }
}

Sie können den Authentifizierungsablauf auch manuell auslösen (z. B. um sich nach Ablauf eines Tokens erneut anzumelden):

opencode mcp auth my-oauth-server

2. Vorab registrierte Client-Anmeldeinformationen

Wenn Sie bereits eine feste Client-ID und ein Secret vom Dienstanbieter erhalten haben, können Sie sie direkt in der Konfiguration angeben und den Schritt der dynamischen Registrierung überspringen:

Beispiel

{
  "$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}",          // Aus Umgebungsvariablen lesen, um eine Offenlegung im Klartext zu vermeiden
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"             // Die angeforderten Berechtigungsbereiche; die konkreten Werte werden vom Dienstanbieter festgelegt
      }
    }
  }
}

3. Deaktivieren von OAuth (Verwendung der API-Schlüssel-Authentifizierung)

Wenn der Server anstelle einer OAuth-Authentifizierung einen API-Schlüssel verwendet, können Sie festlegenoauthauffalseum die automatische OAuth-Erkennung zu deaktivieren und zu verwendenheaderszum Übergeben des Schlüssels:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,                                   // Automatische OAuth-Erkennung deaktivieren
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"     // API-Schlüssel-Authentifizierung direkt verwenden
      }
    }
  }
}

OAuth-Konfigurationsoptionen

Konfigurationselement Type Beschreibung
oauth Object /false OAuth-Konfigurationsobjekt; auf ... setzenfalseum die automatische OAuth-Erkennung vollständig zu deaktivieren
clientId String OAuth-Client-ID. Wenn nicht angegeben, versucht OpenCode, eine dynamische Client-Registrierung durchzuführen
clientSecret String OAuth-Client-Secret (falls vom Autorisierungsserver erforderlich)
scope String Berechtigungs-Scopes, die während der Autorisierung angefordert werden. Mehrere Scopes werden durch Leerzeichen getrennt; konkrete Werte werden vom Dienstanbieter definiert

Befehle zur Verwaltung der Authentifizierung

OpenCode bietet eine Reihe von Kommandozeilenwerkzeugen zur Verwaltung des MCP-Authentifizierungsstatus:

# 对指定 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

Überschreiben der Remote-Standardkonfiguration

Organisationen können.well-known/opencodevoreingestellte MCP-Server-Konfigurationen für Mitglieder über Endpunkte bereitstellen. Diese Server können standardmäßig deaktiviert sein. Wenn Sie einen davon aktivieren müssen, fügen Sie einen Eintrag mit demselben Namen in Ihrer lokalen Konfiguration hinzu und setzen Sieenabled: true, um ihn zu aktivieren.Lokale Konfiguration überschreibt Remote-Standardwerte：

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {                                         // Entspricht dem Servernamen in der Remote-Konfiguration der Organisation
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true                                 // Lokal auf true setzen, um den standardmäßig deaktivierten Remote-Zustand zu überschreiben
    }
  }
}

Tool-Verwaltung

Nachdem ein MCP-Server registriert wurde, erscheinen seine Tools in服务器名称_工具名称in Form von in der Tool-Liste von OpenCode und können verwaltet werdentoolsüber das Feld für die einheitliche Verwaltung.

1. Tools eines bestimmten MCP global deaktivieren

Beispiel

{
  "$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    // Alle Tools des Servers my-mcp-foo deaktivieren (der Server startet weiterhin, aber seine Tools sind nicht verfügbar)
  }
}

2. Stapelweises Deaktivieren mit Glob-Mustern

Mit Glob-Wildcards können Tools von mehreren MCP-Servern gleichzeitig abgeglichen und deaktiviert werden:

Beispiel

{
  "$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    // Glob-Muster: Tools von allen Servern deaktivieren, deren Namen mit my-mcp beginnen
  }
}

3. Bestimmte MCP-Tools pro Agent aktivieren

Wenn Sie viele MCP-Server konfiguriert haben, aber jeder Agent nur eine Teilmenge benötigt, können Sie zuerst alle MCP-Tools global deaktivieren und sie dann nach Bedarf in bestimmten Agent-Konfigurationen aktivieren. Dadurch können Sie genau steuern, auf welche Tools jeder Agent zugreifen kann, und Kontextverschwendung vermeiden:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true         // Der Server selbst bleibt in Betrieb (andernfalls kann der Agent ihn ebenfalls nicht verwenden)
    }
  },
  "tools": {
    "my-mcp*": false          // Schritt 1: Alle Tools dieses MCP global deaktivieren, damit sie in Standardkonversationen nicht verfügbar sind
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true       // Schritt 2: Nur im my-agent-Agenten aktivieren; andere Agenten sind nicht betroffen
      }
    }
  }
}

Glob-Muster-Regeln

Platzhalter Bedeutung Beispiel
* Entspricht null oder mehr beliebigen Zeichen my-mcp*matchesmy-mcp_search、my-mcp_listwarten
? Entspricht genau einem beliebigen Zeichen my-mcp?matchesmy-mcpA, entspricht aber nichtmy-mcpAB
anderen Zeichen Entspricht wörtlich und exakt my-mcp-fooEntspricht nur Servern mit exakt identischen Namen

MCP-Server-Tools werden bei der Registrierung mit dem Servernamen als Präfix versehen. Beispielsweise werden Tools vom Servermyserverwerden registriert alsmyserver_toolname. Um alle Tools eines Servers zu deaktivieren, verwenden Sie daher"myserver_*": falsefür eine exakte Übereinstimmung.

Konfigurationsbeispiele

Sentry

Fügen Sie den Sentry-MCP-Server hinzu, um Fehler, Issues und Ereignisdaten von Sentry-Projekten direkt in Unterhaltungen abzufragen:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}      // Ein leeres Objekt aktiviert die automatische OAuth-Authentifizierung; OpenCode übernimmt den gesamten OAuth-Ablauf automatisch
    }
  }
}

Führen Sie nach dem Hinzufügen der Konfiguration den folgenden Befehl aus, um die Kontenautorisierung abzuschließen (ein Browser wird für die OAuth-Anmeldung geöffnet):

opencode mcp auth sentry

Nachdem die Authentifizierung abgeschlossen ist, fügen Sieuse sentryzu Ihrem Prompt hinzu, um die Sentry-Tools aufzurufen:

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

Context7

Füge den Context7 MCP-Server hinzu, um in Gesprächen verschiedene technische Dokumente zu durchsuchen und LLMs dabei zu helfen, aktuellste und genaue API-Referenzen zu erhalten:

Beispiel

// Basisversion (ohne Rate-Limit-Optimierung)
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Beispiel

// Nach der Registrierung eines kostenlosen Kontos bietet die Verwendung eines API-Schlüssels höhere Rate-Limits
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"    // API-Schlüssel aus einer Umgebungsvariable lesen
                                                        // Muss vorab gesetzt werden: export CONTEXT7_API_KEY=your_key
      }
    }
  }
}

Adduse context7zu deinem Prompt, um die Dokumentsuchfunktion aufzurufen:

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

Du kannst auch globale Regeln in den Projekteinstellungen hinzufügen,AGENTS.mddamit das LLM Context7 automatisch verwendet, wenn es Dokumentation nachschlagen muss, ohne dass es jedes Mal manuell angegeben werden muss:

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

Grep by Vercel

Füge den Grep by Vercel MCP-Server hinzu, um echte Codeausschnitte auf GitHub direkt in Unterhaltungen zu durchsuchen, damit LLMs die korrekte API-Nutzung und Implementierungsreferenzen finden:

Beispiel

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {           // Server namens gh_grep, in Prompts unter diesem Namen referenziert
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

Adduse the gh_grep toolzu deinem Prompt hinzu, um nach Codebeispielen auf GitHub zu suchen:

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

Ähnlich kannst du globale Regeln festlegen inAGENTS.mddamit das LLM bei Unsicherheit über die Verwendung automatisch nach Codebeispielen sucht:

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