Clients verbinden

Jeder Client verbindet sich mit derselben Adresse, https://<dein-ai-os>/mcp, und meldet sich mit deinem Firmenkonto an. Die Konsole zeigt die Schritte mit der Adresse und den Client-IDs deiner Installation: Klick oben rechts auf Deinen KI-Assistenten verbinden (auf einem schmalen Bildschirm KI verbinden). Die Beispiele hier verwenden ai-os als Namen der Verbindung und https://ai.example.com/mcp als Adresse.

Der Dialog fragt Welchen Assistenten nutzt du? Er bietet zuerst Claude (claude.ai und die Claude-Apps) und Copilot oder eine andere App an, die Werkzeuge für Entwickler unter Für Entwickler. Welche davon deine Installation aufführt, legen ihre Betreiber fest (keycloak.agentClients); standardmäßig Claude Code, Codex, Cursor, claude.ai, Hermes und AI OS Workbench.

Claude Code

Bietet deine Installation das Claude-Code-Plugin an, zeigt der Dialog es zuerst. Es bringt die Verbindung, die eigenen Skills von AI OS und die Befehle share, new-server und new-skill in einem Schritt:

claude plugin marketplace add https://ai.example.com/api/claude/marketplace.json
claude plugin install <name>@<name>

Ohne das Plugin fügst du die Verbindung einmal hinzu:

claude mcp add --transport http --scope user --client-id claude-code ai-os https://ai.example.com/mcp

Dann meldest du dich an: Tippe /mcp in Claude Code, wähle die Verbindung und dann Sign in, oder führe aus:

claude mcp login ai-os

Codex

codex mcp add ai-os --url https://ai.example.com/mcp --oauth-client-id codex
codex mcp login ai-os

Cursor

Trag die Adresse in ~/.cursor/mcp.json ein (oder in .cursor/mcp.json für ein Projekt):

{ "mcpServers": { "ai-os": { "url": "https://ai.example.com/mcp" } } }

Cursor registriert sich selbst und braucht keine Client-ID. Öffne dann in Cursor Settings → MCP und klick auf Needs login.

Claude (claude.ai und die Claude-Apps)

Öffne in Claude Einstellungen, dann Konnektoren, und klick auf Benutzerdefinierten Konnektor hinzufügen.
Gib einen Namen und die Adresse ein.
Füge unter Erweiterte Einstellungen die Client-ID aus dem Dialog in OAuth Client ID ein und lass OAuth Client Secret leer.
Klick auf Hinzufügen, dann auf Verbinden.

AI OS Workbench

AI OS Workbench ist die eigene Kommandozeile von AI OS (ADR 0074). Sie braucht Node.js 22.19 oder neuer:

npm config set @labtagon:registry https://npm.labtagon.cloud/
npm install -g @labtagon/workbench
wb setup --url https://ai.example.com
wb

Eine andere App

Copilot oder eine andere App zeigt die Adresse, die du an dein IT-Team schickst: Es verbindet sie für dich. Jeder andere MCP-Client funktioniert mit der Adresse und der Client-ID, die der Dialog zeigt (Client-ID kopieren), das Secret bleibt leer. Clients, die nicht aufgeführt sind, melden sich unter https://<dein-ai-os>/mcp/direct an.

Details für dein IT-Team im Dialog sagt, was das Gateway spricht: MCP über Streamable HTTP, OAuth mit PKCE und die Protected-Resource-Metadaten nach RFC 9728.

Das Profil wählen

Wenn der Client sich anmeldet und du mehr als ein Profil hast, fragt AI OS, welches er nutzt. Er bekommt nur, was in diesem Profil steht. Siehe Profile.

Wie lange eine Anmeldung hält

Wenn AI OS die Tokens der Clients selbst ausgibt (ADR 0059):

Das Access Token hält 10 Minuten; der Client erneuert es selbst.
Das Refresh Token hält 30 Tage und wird bei jeder Nutzung ersetzt. Nach 30 Tagen ohne Nutzung meldest du dich neu an.
Eine Anmeldung hält höchstens 90 Tage.

Unter Verbindungen in Studio siehst du jeden verbundenen Client und kannst seine Anmeldung beenden.

Clients, die sich selbst registrieren

Neben den aufgeführten Clients kann sich ein Client über ein Client-ID-Metadatendokument ausweisen oder sich selbst registrieren (Dynamic Client Registration). So ein Client wartet, bis eine Person oder ein Administrator ihn freigibt; Administratoren finden sie unter Verwaltung → Clients.

Wenn etwas nicht funktioniert

Funktioniert etwas nicht? Häufige Lösungen ansehen im Dialog listet, was meistens hilft. Tools heißen <server>__<tool>, zum Beispiel files__upload (Wie Tools benannt sind).