OpenCode MCP einrichten: opencode.json für v1 und v2

Bitte OpenCode um einen Bestätigungsdialog, und es schreibt ihn aus dem Gedächtnis: ein fixiertes Overlay, mit Glück eine selbstgebaute Fokusfalle, kein Layout fürs Smartphone. Ein OpenCode MCP Eintrag behebt das. Der Agent bekommt eine Komponenten-Registry, die er durchsuchen, aus der er Props lesen und aus der er installieren kann. Der Haken ist die Config. Die Doku zu OpenCode 1 zeigt mcp.<name> mit enabled, die Doku zu OpenCode 2 zeigt mcp.servers.<name> mit disabled, und jede hat für ihre eigene Hauptversion recht. Wer OpenCode MCP einrichten will, findet hier beide Versionen: die Form der Config, lokale und Remote-Einträge, API-Key-Header oder OAuth und die Prompts, aus denen echte Komponenten werden.

Was wir am 6. November 2026 geprüft haben: die MCP-Doku zu OpenCode 1 (opens in a new tab), die MCP-Doku zu OpenCode 2 (opens in a new tab) samt Migrationsguide (opens in a new tab), das JSON-Schema unter https://opencode.ai/config.json, die npm-Einträge beider Versionen, den Quellcode von shadcn und unseren eigenen Server per curl. OpenCode selbst haben wir für diesen Artikel nicht installiert. Wo Doku und Schema sich widersprechen, sagen wir das, statt zu raten. Warum ein Agent überhaupt einen Server für Komponenten braucht, steht in unserem Guide zu MCP für Komponentenbibliotheken.

Welche OpenCode-Version habe ich, und warum ist das wichtig?

Führ opencode --version aus. Die beiden Hauptversionen kommen als verschiedene npm-Pakete:

Laut der CLI-Doku zu v1 (opens in a new tab) bringt dich opencode upgrade --major auf OpenCode 2 und entfernt OpenCode 1. Der Migrationsguide ist der Teil, der dir Arbeit spart: OpenCode 2 liest dieselben System-, globalen und Projektdateien wie OpenCode 1 und normalisiert die v1-Felder im Speicher, ohne sie umzuschreiben. Eine v1-Datei funktioniert nach dem Upgrade also weiter. Die Regel, die dazukommt: Jeder Server-Eintrag bleibt komplett in einer Form. Ein v1-Eintrag mit enabled, aber ohne type wird mit einer Warnung ignoriert.

Das Schema unter opencode.ai/config.json bildet beides ab: mcp.servers ist die aktuelle Form, Servernamen direkt unter mcp werden weiter akzeptiert und sind als veraltet markiert.

Wo liegt die MCP-Config von OpenCode?

Die OpenCode MCP Config steht in opencode.json oder opencode.jsonc, an einem dieser Orte:

• Global: ~/.config/opencode/opencode.json, für Server, die du in jedem Projekt willst.
• Projekt: opencode.json im Projektordner oder .opencode/opencode.json. Diese Datei gewinnt gegen die globale, und hier landet ein Server, den das ganze Team bekommen soll.
• Eigener Pfad: ein Pfad in der Umgebungsvariable OPENCODE_CONFIG.

Eine Komponenten-Registry gehört in die Projektdatei: Jeder, der das Repository klont, bekommt denselben Server, und der Agent sieht ihn nur dort, wo er nützt. Setz "$schema": "https://opencode.ai/config.json" an den Anfang, dann markiert dein Editor einen falschen Key, bevor OpenCode es tut.

Wie lege ich einen lokalen MCP-Server in OpenCode an?

Ein lokaler Eintrag hat "type": "local" und ein command-Array: das Programm und seine Argumente als einzelne Strings. So sieht der opencode.json MCP Block für unseren Server in der Form von OpenCode 2 aus:

// opencode.json (OpenCode 2)
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "wingo-ui": {
        "type": "local",
        "command": ["npx", "-y", "wingo-ui@latest", "mcp"]
      }
    }
  }
}

Derselbe Server für OpenCode 1:

// opencode.json (OpenCode 1)
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "wingo-ui": {
      "type": "local",
      "command": ["npx", "-y", "wingo-ui@latest", "mcp"],
      "enabled": true
    }
  }
}

Das -y ist wichtig. Ohne es kann npx anhalten und fragen, bevor es ein Paket herunterlädt, und auf einen Server, den OpenCode im Hintergrund gestartet hat, antwortet niemand. Genau das ist uns bei unserem Gemini-CLI-Setup mit shadcn passiert.

npx wingo-ui@latest mcp ist ein kleiner stdio-Proxy. Er leitet an https://wingo-ui.com/mcp weiter und schickt WINGO_UI_API_KEY mit, wenn die Variable gesetzt ist, sonst den Key, den npx wingo-ui@latest login auf deinem Rechner gespeichert hat. Ohne beides verbindet er sich als anonymer Client. Lokale Einträge akzeptieren außerdem environment (ein Objekt mit Variablen), cwd und timeout.

Kann die CLI den Eintrag für mich schreiben?

Ja. In OpenCode 1 führt dich opencode mcp add durch einen lokalen oder Remote-Server. Die Doku zu OpenCode 2 zeigt Flags, und alles nach -- ist der Befehl:

opencode mcp add wingo-ui -- npx -y wingo-ui@latest mcp
opencode mcp add wingo-ui --global -- npx -y wingo-ui@latest mcp

Die zweite Zeile schreibt die globale Datei statt der Projektdatei.

Wie lege ich einen Remote-Server mit API-Key an?

Ein Remote-Eintrag hat "type": "remote" und eine url. Unser Server spricht Streamable HTTP unter https://wingo-ui.com/mcp und nimmt den Key als Bearer-Header:

// opencode.json (OpenCode 2)
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "wingo-ui": {
        "type": "remote",
        "url": "https://wingo-ui.com/mcp",
        "oauth": false,
        "headers": {
          "Authorization": "Bearer {env:WINGO_UI_API_KEY}"
        }
      }
    }
  }
}

Für OpenCode 1 lässt du die Ebene servers weg und ergänzt "enabled": true; die anderen Keys bleiben gleich.

{env:WINGO_UI_API_KEY} ist die Variablenersetzung von OpenCode, dokumentiert in beiden Versionen. Sie hält den Key aus der Datei heraus, die Datei darf also ins Repository. Eine Falle: Eine nicht gesetzte Variable wird zu einem leeren String. Wir haben mit curl Authorization: Bearer (leer) an unseren Server geschickt, und er antwortete mit 200 als anonymer Client. Eine fehlende Variable zeigt sich also als „verbunden, aber kein Quellcode“ statt als Fehler. Lass den Agenten nach dem Setup einmal get_account_status aufrufen, dann siehst du, mit welchem Konto er arbeitet.

Warum oauth auf false setzen?

Weil OpenCode OAuth von sich aus versucht. Laut der Doku zu OpenCode 1 startet ein Remote-Server, der mit 401 antwortet, einen OAuth-Flow, mit dynamischer Client-Registrierung, wenn der Server sie unterstützt. Die Doku zu OpenCode 2 sieht oauth: false für Server vor, die nur einen API-Key oder einen anderen Header als Zugangsdaten nehmen. Unser Server hat kein OAuth: /.well-known/oauth-protected-resource liefert 404, und ein falscher Key bekommt ein 401 mit invalid_token. Mit "oauth": false scheitert ein falscher Key als falscher Key, statt einen Browser-Flow zu öffnen, der nie fertig wird. Das ist die allgemeine Regel: Server mit API-Key bekommen oauth: false und einen Header, OAuth-Server keins von beiden.

Wann nehme ich stattdessen OAuth?

Wenn der Server es unterstützt, ist OAuth die angenehmere Wahl, weil kein Secret in deinem Shell-Profil liegt. Konfigurier nur type und url (für OpenCode 1 ist "oauth": {} die ausdrückliche Form aus der Doku) und authentifizier dich dann:

opencode mcp auth sentry      # öffnet den Browser, speichert das Token
opencode mcp auth list        # OpenCode 1: Auth-Status jedes OAuth-fähigen Servers
opencode mcp debug sentry     # OpenCode 1: Verbindung und OAuth-Discovery
opencode mcp logout sentry    # entfernt das gespeicherte Token

Die Doku zu OpenCode 2 nennt auth und logout, aber weder auth list noch debug; dort lässt dich opencode mcp auth ohne Namen einen OAuth-fähigen Server auswählen. OpenCode 1 speichert die Tokens in ~/.local/share/opencode/mcp-auth.json. Server, die einen vorab registrierten Client brauchen, bekommen client_id, client_secret und scope unter oauth (in OpenCode 1 in camelCase).

Wie prüfe ich, ob der Server verbunden ist?

opencode mcp list

Das listet jeden konfigurierten Server mit seinem Verbindungsstatus (und bei OAuth-Servern mit dem Auth-Status). Starte dann eine Session und frag: „Ruf get_account_status auf dem Server wingo-ui auf.“ Ohne Key meldet er einen anonymen Client. Auch anonyme Clients bekommen 10 read-only Tools: search_components, list_categories, get_component, get_block, get_design_rules, get_theme_tokens, get_install_instructions, check_updates, get_changelog und get_account_status. Ein kostenloses Konto bringt den Quellcode jedes kostenlosen Items dazu. Alle Tools und Optionen stehen in der Doku zum MCP-Server.

Drei Einstellungen lohnen sich, sobald es läuft:

• Timeouts. Die Doku zu OpenCode 1 nennt 30 Sekunden als Default, die Feldbeschreibung für v1 im JSON-Schema dagegen 5 Sekunden. Die Doku zu OpenCode 2 nennt 30 Sekunden für startup und catalog und 12 Stunden für execution. Wenn ein langsamer erster npx-Download in den Timeout läuft, setz timeout ausdrücklich (in OpenCode 2 timeout.startup).
• Tool-Namen. Tools tragen den Servernamen als Präfix, wingo-ui_* trifft also alle unsere Tools. OpenCode 1 kann sie mit "tools": { "wingo-ui_*": false } abschalten und pro Agent unter agent.<name>.tools wieder einschalten. OpenCode 2 nutzt Berechtigungsregeln auf denselben Namen nach dem Muster <server>_<tool>.
• Code Mode. OpenCode 2 führt MCP-Server standardmäßig im Code Mode aus; "codemode": false auf einem Server stellt seine Tools direkt bereit.

Wie lege ich einen shadcn-MCP-Eintrag in OpenCode an?

Einen OpenCode shadcn MCP Eintrag schreibt shadcn für dich:

npx shadcn@latest mcp init --client opencode

Im Quellcode von shadcn (4.23.0, 6. November 2026) schreibt das eine opencode.json ins Projekt, mit diesem Eintrag:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "shadcn": {
      "type": "local",
      "command": ["npx", "shadcn@latest", "mcp"],
      "enabled": true
    }
  }
}

Derselbe Befehl installiert shadcn als Dev-Dependency. npx findet es also lokal, und das fehlende -y schadet in diesem Projekt nicht. Ergänz -y, wenn du den Eintrag in ein Projekt ohne diese Dependency kopierst. Es ist die Form von OpenCode 1, die auch OpenCode 2 liest. Wenn deine anderen Server schon unter mcp.servers stehen, schreib diesen passend um, mit "disabled": false statt enabled. Der shadcn-Server durchsucht die Registrys aus deiner components.json und gibt Befehle mit npx shadcn@latest add zurück. Mit beiden Servern in einem Projekt installieren beide Bibliotheken eine button.tsx mit unterschiedlichen Props. Schreib also in deine Regeln, welche Registry welchen Ordner besitzt.

Was gehört in die AGENTS.md?

Wann der Agent sucht, wie er installiert und welche Tokens er nutzt. Laut der Doku zu Regeln in OpenCode (opens in a new tab) liest OpenCode die AGENTS.md vom aktuellen Ordner aufwärts und weicht auf CLAUDE.md aus, dazu kommt eine globale ~/.config/opencode/AGENTS.md. agents install in unserer CLI hat kein Ziel für OpenCode, also hol dir den Block, den sie für Codex schreibt:

curl -s https://wingo-ui.com/agents/AGENTS.md >> AGENTS.md

Der Block steht zwischen den Markierungen <!-- wingo-ui:start v=3 --> und <!-- wingo-ui:end -->. Seine Kernzeile:

- Before writing UI, use the `wingo-ui` MCP tools: `search_components` to find what exists (blocks for whole screens), `get_component` / `get_block` for props and usage, `get_design_rules` for tokens, sizes, motion and mobile rules. Never recreate a component the library has.

Ein ausführlicheres Template steht in unserem Vergleich von AGENTS.md und CLAUDE.md.

Mit welchen Prompts installiert OpenCode echte Komponenten?

Nenn den Screen, die Daten und was der Agent dir zurückmelden soll. Die Regeln schicken ihn schon zu search_components, dann zu get_component, dann zu npx wingo-ui@latest add. Der Prompt liefert, was eine Regeldatei nicht kann.

Prompt 1: eine Löschbestätigung

Füg in app/settings eine Bestätigung für "Projekt löschen" mit dem Wingo-UI-Dialog ein. Lies vorher
die Props von Dialog und Button mit get_component, installier beide mit der CLI, nutz den Tone danger,
zeig beim Löschen einen Spinner und prüf den Dialog bei 390px.

Dialog und Button sind beide kostenlos, und der Kern eines guten Ergebnisses ist kurz:

// app/settings/delete-project-dialog.tsx
"use client";

import { Trash2 } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Dialog, DialogClose } from "@/components/ui/dialog";

type Props = { name: string; deleting: boolean; onDelete: () => void };

export function DeleteProjectDialog({ name, deleting, onDelete }: Props) {
  return (
    <Dialog
      trigger={
        <Button variant="soft" tone="danger" leftIcon={<Trash2 />}>
          Projekt löschen
        </Button>
      }
      title={`${name} löschen?`}
      description="Das entfernt das Projekt und seine Deployments. Du kannst es nicht rückgängig machen."
      icon={<Trash2 />}
      tone="danger"
      footer={
        <>
          <DialogClose asChild>
            <Button variant="soft">Abbrechen</Button>
          </DialogClose>
          <Button tone="danger" loading={deleting} loadingText="Wird gelöscht" onClick={onDelete}>
            Löschen
          </Button>
        </>
      }
    />
  );
}

Unter 768px öffnet dieselbe Komponente als Bottom Sheet mit 48px hohen Aktionen über die volle Breite. Genau diesen Teil lässt ein Modell aus dem Gedächtnis weg.

Prompt 2: ein Login-Screen

Bau /login aus dem Wingo-UI-Block login-page, Card-Layout, Passwort und 6-stelliger E-Mail-Code,
keine Social-Buttons. Schick alles an unsere /api/auth-Routen und geh bei Erfolg zu /dashboard.
Ersetze jeden Northwind-String in den Labels durch Harbor und liste jeden Handler auf, der noch auf seinem Beispiel-Default steht.

Die Login Page bringt Beispiel-Handler mit, damit ihre Demo läuft, und ihre Default-Labels nennen Northwind CRM. Deshalb verlangt der Prompt einen Bericht: Ohne onVerifyCode akzeptiert die Code-Ansicht bei jeder Person den Code 123456. Ein gutes Ergebnis übergibt layout="card", methods={["password", "otp"]}, showProviders={false}, labels mit deinem App-Namen sowie echte Handler für onSignIn, onSendCode, onVerifyCode und onSuccess.

Prompt 3: selbstgebaute Spinner ersetzen

Finde jeden Button in app/account, der beim Speichern seinen eigenen Spinner rendert, und ersetze ihn
durch den Wingo-UI-Button. Lies vorher seine Props mit get_component und zeig mir den Diff.

Die Props loading und loadingText des Buttons ersetzen das Spinner-Markup und das Jonglieren mit disabled, und solange er lädt, wird onClick nicht aufgerufen.

Was geht schief, und wie behebe ich es?

• Der Server taucht nie auf. Ein v1-Eintrag ohne type oder ein Eintrag, der enabled und disabled mischt. Entscheide dich pro Eintrag für eine Form und führ opencode mcp list erneut aus.
• Ein lokaler Server startet nicht. Meist wartet npx auf eine Antwort zur Installation: Ergänz -y in command. Auch ein langsamer erster Download kann in den Timeout laufen.
• Für einen Server mit API-Key öffnet sich ein Browserfenster. oauth fehlt. Setz "oauth": false und schick den Key in headers.
• Verbunden, aber kein Quellcode. Die Key-Variable ist nicht gesetzt, der Header ging also leer raus. Exportier sie in der Shell, die OpenCode startet, oder nimm nach npx wingo-ui@latest login den lokalen Eintrag (ein kostenloses Konto braucht nur eine E-Mail-Adresse).
• Pro-Blocks mit einem kostenlosen Key. get_block liefert für login-page trotzdem Props und Nutzung, aber npx wingo-ui@latest add login-page bricht ab, weil der Block zu Pro gehört. Button und Dialog sind kostenlos; die Login Page gehört zu Pro ($8 im Monat, $80 im Jahr oder einmalig $150, auf der Preisseite).

Wo fange ich an?

Leg ein kostenloses Konto an, führ npx wingo-ui@latest login aus, ergänz den lokalen Eintrag in der opencode.json deines Projekts, häng den Block an die AGENTS.md an und probier Prompt 1 mit dem kostenlosen Dialog und Button aus. Dasselbe Setup für andere Agenten findest du in unserem Antigravity-MCP-Setup, im Codex-MCP-Setup und im Claude-Code-Setup mit shadcn, und den Rest der Serie findest du unter UI mit KI-Agenten bauen.

Häufige Fragen

Wo sucht OpenCode nach MCP-Servern?

Im Key mcp der opencode.json oder opencode.jsonc: global in ~/.config/opencode/, pro Projekt im Projektordner oder in .opencode/. Die Projekt-Config gewinnt gegen die globale Datei, und OpenCode 1 und 2 lesen dieselben Orte.

Was hat sich an der MCP-Config in OpenCode 2 geändert?

Server sind von mcp. nach mcp.servers. umgezogen, aus enabled wurde das umgekehrte disabled, timeout ist jetzt ein Objekt mit startup, catalog und execution, und die OAuth-Felder sind in snake_case (client_id statt clientId). OpenCode 2 normalisiert die alte Form im Speicher, eine v1-Datei funktioniert also weiter.

Sollte ein Remote-MCP-Server in OpenCode OAuth oder einen API-Key-Header nutzen?

Nimm OAuth, wenn der Server es unterstützt, denn OpenCode speichert das Token nach opencode mcp auth für dich. Wenn der Server einen API-Key erwartet, setz ihn mit {env:VAR} in headers und oauth auf false. So startet ein abgelehnter Key keinen OAuth-Flow, den der Server nicht abschließen kann.

Funktioniert der shadcn-MCP-Server mit OpenCode?

Ja. npx shadcn@latest mcp init --client opencode schreibt eine opencode.json ins Projekt, mit einem lokalen shadcn-Eintrag in der Form von OpenCode 1 (enabled: true), die auch OpenCode 2 liest. Dem command-Array fehlt in shadcn 4.23.0 das -y. Das ist kein Problem, weil mcp init shadcn auch als Dev-Dependency installiert; ergänz -y, wenn du den Eintrag in ein anderes Projekt kopierst.

Wie prüfe ich, ob ein MCP-Server in OpenCode verbunden ist?

Führ opencode mcp list aus. Das listet jeden konfigurierten Server mit seinem Verbindungsstatus; in OpenCode 1 testet opencode mcp debug zusätzlich OAuth. Stell dann eine Frage, die nur der Server beantworten kann, etwa einen Aufruf von get_account_status auf dem Server wingo-ui.