KI-Clients mit MCP verbinden

VibeKit stellt unter /api/mcp einen MCP-Server bereit. Die Anmeldung nutzt dein bestehendes Better-Auth-Konto. Jede genehmigte Verbindung erhält eine eigene OAuth-Freigabe. Die Werkzeuge können Daten lesen, aber keine Konten, Zahlungen, Feedback-Einträge, Einstellungen oder Zugangsdaten ändern.

Vor dem Start migrieren

Die JWT- und OAuth-Plugins benötigen ihre Tabellen bereits bei der normalen Sitzungsprüfung. Führe die Migrationen aus, bevor du die aktualisierte Anwendung startest:

bun install
bun run db:generate
bun run --cwd packages/database db:migrate
bun run build

Prüfe und genehmige produktive Migrationen vorher. 20260905000000_mcp_oauth ergänzt Signaturschlüssel, OAuth-Daten, Verbindungen und Zugriffsereignisse. Bestehende Benutzer- und Sitzungstabellen bleiben erhalten.

Die Meldung public.jwks does not exist bedeutet, dass der verwendeten Datenbank die Migration fehlt. Prüfe das tatsächliche Datenbankziel. Wurden ältere Tabellen mit Schema-Push erstellt, muss zuerst der Migrationsverlauf abgeglichen werden. Setze keine gefüllte Datenbank zurück und führe vorhandene Tabellenerstellungen nicht blind erneut aus.

Setze NEXT_PUBLIC_SITE_URL auf den endgültigen Ursprung und behalte BETTER_AUTH_SECRET bei. Außerhalb lokaler Loopback-Adressen ist HTTPS erforderlich. OAuth-Metadaten und Token-Zielgruppe werden aus dieser URL abgeleitet.

Optionale Einrichtung mit deinem Agenten

Dein Agent kann während der Website-Einrichtung einen KI-Client verbinden, wenn du MCP nutzen möchtest. Du kannst diesen Schritt ablehnen oder verschieben und die übrige Einrichtung abschließen. Der Agent hält deine Entscheidung fest, prüft Website-URL und Datenbank, registriert den gewählten Client und testet nach deiner Zustimmung einen erlaubten Lesezugriff.

Du meldest dich mit deinem eigenen verifizierten Konto an und erteilst die Zustimmung. Admin-Berechtigungen sind optional und zunächst nicht ausgewählt. Wähle nur die Teams und websiteweiten Daten, die der Client benötigt. Der Agent kann die Verbindung mit autorisierten Einrichtungswerkzeugen konfigurieren. Die MCP-Werkzeuge der Website selbst können keine Einstellungen, Zugangsdaten, Rollen oder Bereitstellungen ändern.

Wenn du diesen Schritt überspringst, wird kein Client verbunden. Dadurch wird weder /api/mcp deaktiviert noch werden OAuth-Tabellen entfernt. Die aktuelle Auth-Konfiguration benötigt diese Tabellen auch bei der normalen Anmeldung.

Fernzugriff deaktivieren

Produkte ohne Remote-Schnittstelle setzen MCP_ENABLED=false. Damit werden Tool-Erkennung und -Ausführung unter /api/mcp, Zustimmungs-Endpunkt und -Seiten, neue MCP-OAuth-Autorisierungen sowie die OAuth-Erkennungsmetadaten gesperrt – nicht nur der Einstellungslink. Passwort-, Social- und OTP-Anmeldung funktionieren weiter, die OAuth-Tabellen bleiben migriert.

Deaktivierung sperrt die Nutzung bestehender Grants, erhält aber deren Datensätze. Ausdrückliche Widerrufe bleiben bestehen, sodass eine erneute Aktivierung keine widerrufene Verbindung reaktiviert. Die Verbindungsverwaltung bleibt zum Prüfen und Widerrufen verfügbar.

Codex einrichten

Nutze die MCP-Einstellungen oder CLI deines installierten Codex-Clients. Prüfe mit codex mcp add --help, welche Optionen deine Version unterstützt. Wähle einen Namen für die Website und ersetze die Beispiel-URL durch ihre tatsächliche Adresse. Prüfe einen vorhandenen Eintrag mit codex mcp get my-site, bevor du einen weiteren anlegst.

codex mcp add my-site \
  --url https://your-domain.example/api/mcp \
  --oauth-resource https://your-domain.example/api/mcp \
  --oauth-client-registration cimd

Verwende lokal für beide URLs http://localhost:3000/api/mcp, passend zu NEXT_PUBLIC_SITE_URL. Codex startet OAuth und öffnet die Autorisierungsseite. Melde dich an, prüfe Berechtigungen und Teams und erlaube anschließend den Zugriff. Ein gespeicherter Servereintrag allein bedeutet noch keine erfolgreiche Anmeldung.

Wenn der Callback abläuft, starte die Anmeldung erneut, statt die alte URL wiederzuverwenden. Dieses Beispiel fordert Lesezugriff auf Profil und ausgewählte Teams sowie die Erneuerung des Zugriffs an:

codex mcp login my-site --oauth-client-registration cimd \
  --scopes profile:read,teams:read,offline_access

Für websiteweite Lesezugriffe auf Konten und Status fordere stattdessen profile:read,admin:users:read,admin:site:read,offline_access an und wähle diese Admin-Berechtigungen auf der Zustimmungsseite ausdrücklich aus. Ergänze admin:feedback:read nur für websiteweiten Feedback-Zugriff. Dein Konto muss bereits die Admin-Rolle besitzen. Jede Zustimmung erstellt eine separate Freigabe. Entferne nicht mehr benötigte Freigaben unter Verbundene Apps.

Aktualisiere nach erfolgreicher Anmeldung bei Bedarf die MCP-Werkzeugliste in Codex. Bitte Codex, vibekit_get_me und vibekit_list_teams aufzurufen, oder vibekit_admin_get_stats, wenn du admin:site:read erlaubt hast. Prüfe, ob jeder Aufruf erfolgreich ist und zur Freigabe passt. Ein Werkzeugergebnis mit isError ist auch bei erfolgreichem HTTP-Aufruf ein Fehler. Anmeldung und Zustimmung benötigen den Browser; normale Werkzeugaufrufe benötigen keine Browser-Automatisierung.

Widerrufe eine vorübergehende Testverbindung unter /auth/mcp/connections und prüfe, dass der Client keine Daten mehr lesen kann. Behalte deine gewünschte Arbeitsverbindung. codex mcp remove my-site entfernt nur den lokalen Codex-Eintrag. Widerrufe die serverseitige Freigabe über die Website.

Eine App verbinden

1. Trage https://deine-domain.example/api/mcp im MCP-Client ein.
2. Melde dich auf der Website an.
3. Prüfe den App-Namen und die angeforderten Rechte. Administratorrechte sind anfangs nicht ausgewählt.
4. Wähle die Teams aus und erlaube den Zugriff.
5. Unter Einstellungen → Verbundene Apps kannst du den Zugriff prüfen und widerrufen.

Konten ohne Team können /auth/mcp/connections öffnen. Administratoren können dort alle Verbindungen der Website anzeigen und widerrufen.

Zugriffstokens gelten fünf Minuten. Verbindungen und Aktualisierungstokens gelten höchstens 30 Tage. Ein Widerruf sperrt vorhandene Zugriffstokens und weitere Aktualisierungen. Kontosperren, geänderte Rollen, entfernte Teammitgliedschaften, beendete Anmeldesitzungen, gelöschte Zustimmungen und deaktivierte OAuth-Clients werden anhand der aktuellen Daten geprüft.

Jede neue Verbindung erhält eine eigene Freigabe. Sie erweitert keine bestehende Verbindung. Widerrufe alte Verbindungen, die du nicht mehr brauchst.

Berechtigungen

Administratorscopes setzen eine aktuelle Administratorrolle voraus. Sie gelten websiteweit für die jeweils genannten Daten. Normale Teamscopes bleiben auch für Administratoren auf ausgewählte Mitgliedschaften beschränkt. Sitzungen zur Benutzer-Imitation dürfen keine Verbindung genehmigen.

Werkzeuge

Alle Namen beginnen mit vibekit_. Der Client sieht nur Werkzeuge, die seine Scopes und die aktivierten Module erlauben.

• Profil: get_me.
• Teams: list_teams, get_team, list_team_members, get_team_dashboard.
• Abrechnung: get_team_subscription, list_plans.
• Feedback: list_my_feedback, get_my_feedback, list_public_feedback, get_public_feedback, get_roadmap.
• Benachrichtigungen: list_notifications, get_unread_count.
• Versionen: list_releases.
• Administration: admin_list_users, admin_get_user, admin_list_feedback, admin_get_feedback, admin_get_stats, admin_get_settings, admin_get_integration_status.

Listen verwenden, soweit vorgesehen, limit und offset. Standardmäßig werden 25 Einträge geliefert, höchstens 100. nextOffset: null bedeutet, dass keine weitere Seite vorhanden ist. Benutzer- und Feedbacklisten unterstützen Suche; Feedback unterstützt auch Statusfilter.

Ergebnisse enthalten strukturiertes JSON und denselben Inhalt als Text. Zugangsdaten und Sitzungsdaten fehlen bewusst. Feedback enthält den Beitrag und die offizielle Antwort; private Anhänge werden nicht heruntergeladen und rohe Anfrage-Metadaten werden nicht ausgegeben. Integrationsstatus gibt keine Schlüssel zurück und startet keinen Verbindungstest.

Beispielanfragen:

• „Zeige die freigegebenen Teams und den aktuellen Tarif des ersten Teams.“
• „Suche mein privates Feedback zum Export und lies die offizielle Antwort.“
• „Finde als Administrator noch nicht verifizierte Konten.“

Unterstützte Clients

Der Server nutzt das offizielle TypeScript-SDK v2 und verarbeitet aktuelle sowie ältere Anfragen ohne MCP-Sitzungsspeicher. OAuth-Client-Erkennung nutzt Client ID Metadata Documents mit dem Profil MCP 2026-07-28. Dynamische Client-Registrierung ist deaktiviert. Clients benötigen Metadatendokumente oder eine vorherige Registrierung.

Bekannte Clients können serverseitig über adminCreateOAuthClient registriert werden. Verwende genaue Callback-URLs, token_endpoint_auth_method: "none" für öffentliche Clients, PKCE und nur benötigte Lesescopes. Loopback-Callbacks benötigen application_type: "native". Auch registrierte Clients benötigen die Zustimmung des Benutzers.

Metadaten liegen unter /.well-known/oauth-protected-resource und /.well-known/oauth-authorization-server/api/auth. Werkzeuge verwenden POST /api/mcp; GET und DELETE für MCP-Sitzungen werden nicht unterstützt. Browseranfragen müssen vom konfigurierten Website-Ursprung kommen. Native und serverseitige Clients dürfen Origin weglassen.

Grenzen und Protokollierung

Anfragen sind auf 64 KiB, Antworten auf 100.000 Zeichen begrenzt. Ratenlimits gelten pro Benutzer, Client-Benutzer-Paar und bestehender Netzwerkidentitätsregel. Antworten bei Überschreitung enthalten Retry-After. Ohne vertrauenswürdig konfigurierte Proxy-Header teilen unbekannte Netzwerkclients ein Ratenlimit.

McpAccessEvent speichert Freigabe, Benutzer, Client, Werkzeug, Ergebnisstatus, Zeitpunkt und Anfrage-ID. Tokens und Antwortinhalte werden nicht gespeichert. Bewahre sie mit bun run maintenance:prune-mcp auf (Zugriffsereignisse älter als 90 Tage, seit über 7 Tagen abgelaufene Tokens, abgelaufene Client-Assertions; Grants und Consents bleiben für den Konto-/Team-Löschzyklus erhalten). Unterstützt --dry-run und --events-days; ein zusätzlicher Zeitplaner wird nicht installiert.

Getestete Clients

An einem lokalen Build verifiziert: Codex hat sich per OAuth verbunden, 15 Werkzeuge erkannt und fünf authentifizierte Lesezugriffe abgeschlossen (get_me, list_teams, list_plans, list_notifications, get_unread_count) und nach dem Widerruf den Zugriff verloren. Das belegt den dokumentierten Ablauf nur für diesen Client-Build – teste jede beworbene Client-Version, bevor du allgemeine Kompatibilität behauptest.

Prüfung

bun run lint
bun x turbo type-check
bun run test
bun run test:i18n-parity
bun run build

Der Integrationstest benötigt eine wegwerfbare lokale PostgreSQL-Datenbank, deren Name mit vibekit_mcp_ beginnt. Wende dort alle Migrationen an. Setze DATABASE_URL auf diese Datenbank und NEXT_PUBLIC_SITE_URL auf einen freien lokalen Port. Führe danach aus:

MCP_TEST_DATABASE=true bun test \
  packages/api/mcp/mcp.integration.test.mjs \
  packages/auth/lib/mcp-initialization.integration.test.mjs

Der Test startet einen HTTP-Server und prüft Anmeldung, Zustimmung, PKCE, Token-Austausch, Lesewerkzeuge, Rollen- und Mitgliedschaftsänderungen sowie Widerruf.

Prüfe den Server zusätzlich mit dem MCP Inspector und den Clients, die du tatsächlich unterstützen möchtest. Lokale Tests beweisen keine produktive Bereitstellung und keine Verbindung in jedem Client.

Ein Bun-Patch für @better-auth/cimd deaktiviert Nodes automatische Adressauswahl, nachdem der Transport DNS aufgelöst und geprüft hat. Die Verbindung bleibt an die geprüfte Adresse gebunden. node packages/auth/lib/mcp-metadata.check.mjs prüft den Abruf der öffentlichen Codex-Metadaten und die Sperre privater Adressen. Behalte den Patch, bis eine neue Paketversion diesen Test ohne Patch besteht.

Benachrichtigungen enthalten ID, Typ, Link, Erstellungszeit und Lesestatus. Rohe Benachrichtigungsdaten werden nicht ausgegeben.

Erweiterung

Werkzeugregistrierung und Datenprojektionen liegen in packages/api/mcp/server.ts. Verwende vorhandene tRPC-Prozeduren, wo ihr Vertrag passt. Zusätzliche Abfragen müssen begrenzt und ausdrücklich autorisiert sein. Die gemeinsame tRPC-Middleware sperrt Änderungen durch MCP-Identitäten.

Erzeuge OAuth-Plugins für jede Auth-Instanz mit createMcpAuthPlugins(). Better Auth verändert den Erweiterungszustand beim Initialisieren. Wiederverwendete Plugin-Instanzen können cimd beim Neuladen in der Entwicklung doppelt registrieren. Der Initialisierungstest prüft diesen Fall.

OAuth und Freigabeprüfungen liegen in packages/auth/lib/mcp*.ts. Der Zustimmungshandler bindet die Auswahl an die einzelne Anfrage, damit parallele Dialoge keine Teams teilen. Werkzeughinweise ersetzen keine serverseitigen Rechteprüfungen.

Der Repository-Skill add-auth-flow-or-better-auth-plugin enthält den MCP-Einrichtungsablauf für Administratoren. vibekit-deploy verweist bei optionaler Einrichtung darauf. Ergänze einen weiteren aufgabenspezifischen Skill nur, wenn wiederkehrende Arbeit mehr Anleitung als die Werkzeugbeschreibungen braucht. Er muss denselben autorisierten Endpunkt nutzen und darf keine Zugangsdaten enthalten.