MCP OAuth (Claude Connect)
Claude Team kann cockpitOS-MCP per Connect verbinden: Login im Dashboard, Zustimmung, Rückkehr zu Claude — ohne manuelles sk_mcp_…-Token in der Connector-URL.
Architektur
| Komponente | Rolle |
|---|---|
| Dashboard | OAuth Authorization Server (RFC 8414, PKCE S256, Refresh) |
Remote MCP (@mall-os/mcp-cockpit-remote) | Protected Resource — 401 + WWW-Authenticate, Token-Introspection |
| AgencyOS API v1 | Akzeptiert mcp_oat_… Bearer wie sk_mcp_… (gleiche User-Attribution) |
Endpunkte (Dashboard)
| Pfad | Methode | Beschreibung |
|---|---|---|
/.well-known/oauth-authorization-server | GET | Server-Metadaten (CIMD, PKCE S256, logo_uri, authorization_response_iss_parameter_supported) |
/.well-known/openid-configuration | GET | OpenID-Discovery-Fallback (gleiche Metadaten wie oben — MCP-Pflicht) |
/mcp-icon-512.png | GET | Connector-Icon (OAuth logo_uri, Claude-Kachel) |
/mcp-favicon.ico | GET | Favicon für OAuth-Consent |
/oauth/authorize | GET, POST | Login-Redirect, Consent, Authorization Code (POST-Antwort: 303 → GET am redirect_uri mit code, state, iss — nicht 307) |
/oauth/consent | GET | Zustimmungsseite (DE) |
/oauth/token | POST | authorization_code, refresh_token — Antwort RFC 6749 §5.1 (access_token, token_type, expires_in, optional refresh_token, scope) |
/oauth/introspect | POST | Token-Introspection (Bearer: Introspection-Secret) |
Endpunkte (Remote MCP)
| Pfad | Beschreibung |
|---|---|
/mcp | MCP Streamable HTTP (OAuth Bearer oder Legacy) |
/.well-known/oauth-protected-resource/mcp | Protected Resource Metadata (RFC 9728, inkl. logo_uri) |
/favicon.ico | Favicon (statisch aus public/) |
/mcp-icon-512.png | Connector-Icon (512×512) |
Env — Dashboard (mallos-dashboard)
MCP_OAUTH_ENABLED=1
MCP_OAUTH_ISSUER=https://dashboard.cockpit-os.de
MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS=3600
MCP_OAUTH_REFRESH_TOKEN_TTL_DAYS=90
MCP_OAUTH_SCOPES=mcp:read,mcp:write
MCP_OAUTH_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,http://127.0.0.1/callback,http://localhost/callback
MCP_OAUTH_INTROSPECT_SECRET=… # openssl rand -hex 32
# Optional Fallback für Introspection-Auth:
# COCKPIT_MCP_HTTP_BEARER=…
Env — Remote MCP (mallos-mcp-cockpit)
MCP_OAUTH_RESOURCE_URL=https://mallos-mcp-cockpit.onrender.com/mcp
MCP_OAUTH_INTROSPECTION_URL=https://dashboard.cockpit-os.de/oauth/introspect
MCP_OAUTH_INTROSPECT_SECRET=… # gleich wie Dashboard
MCP_OAUTH_LEGACY_BEARER_FALLBACK=1 # Default während Rollout — ?token= + org-Bearer
COCKPIT_MCP_HTTP_BEARER=… # Legacy org-weit + Introspection-Fallback
COCKPIT_DASHBOARD_BASE_URL=https://dashboard.cockpit-os.de
Legacy (weiter unterstützt)
- Stdio MCP +
COCKPIT_MCP_USER_TOKEN(sk_mcp_…) - Manuell: Dashboard → Mein Konto → MCP verbinden
- AgencyOS-Key
sk_agencyos_… - Remote
?token=und org-weiterCOCKPIT_MCP_HTTP_BEARER(wennMCP_OAUTH_LEGACY_BEARER_FALLBACK=1)
Migration
Prisma: 20260925100000_add_mcp_oauth_tables_SAFE — Tabellen mcp_oauth_authorization_codes, mcp_oauth_access_tokens, mcp_oauth_refresh_tokens.
Phase 3 (geplant)
Rollenbasierte Tool-Filterung pro OAuth-Scope/User-Rolle — heute gelten dieselben Rechte wie beim persönlichen MCP-Token (accessScope: user bzw. global für Super-Admin).
Logging (Render)
OAuth-Routen schreiben keine Business-Logs in die DB — nur strukturierte stdout-Zeilen (Render → Logs → Filter [mcp-oauth]):
| Service | Was prüfen |
|---|---|
| mallos-dashboard | Request-Logs: /oauth/authorize, /oauth/consent, /oauth/token (Token-Tausch von Claude-Servern). App-Logs: [mcp-oauth] JSON (authorize_post, token_exchange, token_error). |
| mallos-mcp-cockpit | Request-Logs: POST /mcp (401 = OAuth noch ohne Token; 200 mit ?token= = Legacy). App-Logs: [mcp-oauth-remote]. |
Hinweis: Fehlgeschlagener Connect nach Consent, aber ohne /oauth/token-Treffer → prüfen: Redirect-URL enthält code, state und iss (RFC 9207)? Browser-DevTools → Network → POST /oauth/authorize → Response 303 → Location https://claude.ai/api/mcp/auth_callback?.... Fehlt iss oder Status ≠ 303, bricht Claude den Token-Tausch ab, bevor unser Server getroffen wird.
Hinweis: Render zeigt token_exchange: ok, Claude meldet trotzdem mcp_token_exchange_failed_missing_token → Token-JSON prüfen: muss access_token (snake_case) enthalten, nicht accessToken.
So testen
MCP_OAUTH_ENABLED=1lokal, Migration anwenden.GET /.well-known/oauth-authorization-server—code_challenge_methods_supported: ["S256"].- Browser:
/oauth/authorize?response_type=code&client_id=https://claude.ai/oauth/mcp-oauth-client-metadata&redirect_uri=…&code_challenge=…&code_challenge_method=S256 - Remote: Request ohne Auth → 401 +
resource_metadata; mit gültigemmcp_oat_…→ MCP antwortet.
Nutzer-Anleitung: Claude & Cockpit verbinden.
Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/mcp-oauth