Zum Hauptinhalt springen

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​

KomponenteRolle
DashboardOAuth Authorization Server (RFC 8414, PKCE S256, Refresh)
Remote MCP (@mall-os/mcp-cockpit-remote)Protected Resource — 401 + WWW-Authenticate, Token-Introspection
AgencyOS API v1Akzeptiert mcp_oat_… Bearer wie sk_mcp_… (gleiche User-Attribution)

Endpunkte (Dashboard)​

PfadMethodeBeschreibung
/.well-known/oauth-authorization-serverGETServer-Metadaten (CIMD, PKCE S256, logo_uri, authorization_response_iss_parameter_supported)
/.well-known/openid-configurationGETOpenID-Discovery-Fallback (gleiche Metadaten wie oben — MCP-Pflicht)
/mcp-icon-512.pngGETConnector-Icon (OAuth logo_uri, Claude-Kachel)
/mcp-favicon.icoGETFavicon für OAuth-Consent
/oauth/authorizeGET, POSTLogin-Redirect, Consent, Authorization Code (POST-Antwort: 303 → GET am redirect_uri mit code, state, iss — nicht 307)
/oauth/consentGETZustimmungsseite (DE)
/oauth/tokenPOSTauthorization_code, refresh_token — Antwort RFC 6749 §5.1 (access_token, token_type, expires_in, optional refresh_token, scope)
/oauth/introspectPOSTToken-Introspection (Bearer: Introspection-Secret)

Endpunkte (Remote MCP)​

PfadBeschreibung
/mcpMCP Streamable HTTP (OAuth Bearer oder Legacy)
/.well-known/oauth-protected-resource/mcpProtected Resource Metadata (RFC 9728, inkl. logo_uri)
/favicon.icoFavicon (statisch aus public/)
/mcp-icon-512.pngConnector-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-weiter COCKPIT_MCP_HTTP_BEARER (wenn MCP_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]):

ServiceWas prüfen
mallos-dashboardRequest-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-cockpitRequest-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​

  1. MCP_OAUTH_ENABLED=1 lokal, Migration anwenden.
  2. GET /.well-known/oauth-authorization-server — code_challenge_methods_supported: ["S256"].
  3. Browser: /oauth/authorize?response_type=code&client_id=https://claude.ai/oauth/mcp-oauth-client-metadata&redirect_uri=…&code_challenge=…&code_challenge_method=S256
  4. Remote: Request ohne Auth → 401 + resource_metadata; mit gültigem mcp_oat_… → MCP antwortet.

Nutzer-Anleitung: Claude & Cockpit verbinden.

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /developer-guide/mcp-oauth