Context
Settling the recommended client-auth posture for a GitLab-backed cloud MCP deployment converged on: OAuth browser-login (via a pre-registered GitLab OAuth app) as the primary path, with a Personal Access Token only as a fallback. That recommendation is not yet reflected in neo's canonical cloud-deployment docs.
learn/agentos/cloud-deployment/ClientAuthentication.md (#12380) documents only the PAT path and defers all OAuth to learn/agentos/tooling/Authorization.md — but Authorization.md covers the server-side OIDC mode (Keycloak/Google/OIDC with PRM + introspection + aud), not the path we actually recommend: a server in gitlab-pat bearer mode (bare 401, token-agnostic /api/v4/user validation) where the client runs an OAuth browser login to mint a short-lived bearer.
The Problem
There is no canonical neo doc for the recommended, verified path:
- The server runs
gitlab-pat mode → emits a bare 401 (no Protected-Resource-Metadata, since GitLab has no DCR — see McpInspectorCompatibility.md).
- The client therefore cannot auto-discover the Authorization Server; it must be pointed at GitLab explicitly via an
authServerMetadataUrl-style override + a pre-registered OAuth client_id (GitLab has no DCR).
- The client completes OAuth 2.1 auth-code + PKCE (browser SSO/2FA), holds a short-lived, auto-refreshed access token, and sends it as the bearer. The server validates it via
/api/v4/user — identical to a PAT, because the verifier is token-type-agnostic.
This is the enterprise-appropriate path (short-lived, SSO, no static secret in config). It's the missing canonical recipe; today readers only find PAT.
The Architectural Reality
learn/agentos/cloud-deployment/ClientAuthentication.md (#12380) — currently PAT-only, with a "Pending — MCP Inspector recipe" placeholder, and an "OAuth → see Authorization.md" deferral that points at the wrong (server-OIDC) mode for this case.- The client recipe is harness-specific: a desktop MCP client (e.g. Claude Code/Desktop ≥ the version exposing
oauth.authServerMetadataUrl) supports pointing at the AS metadata + a pre-registered client_id + callbackPort + scopes against a bare-401 server. The verified mechanism is authServerMetadataUrl → the AS's /.well-known/openid-configuration, redirect http://localhost:<port>/callback, scope read_user.
The Fix
Extend ClientAuthentication.md with an OAuth browser-login section, presented as the primary path:
- The model: one server contract (validate a GitLab bearer), two client ways to mint it — OAuth access token (preferred) or PAT (fallback).
- One-time: register a GitLab OAuth app (
read_user, per-harness redirect URIs, no DCR needed).
- The client recipe for the bare-
401 case: the authServerMetadataUrl override + pre-registered client_id + callbackPort + scopes. Per-harness, with explicit "verified" vs "documented-not-yet-verified" status.
- Reframe PAT as the explicit fallback (Inspector / headless-CI / scripts); fill the pending Inspector recipe (cross-ref #12379).
- Add the honest audience caveat (no RFC 8707 on GitLab → validates "a valid user," not "issued for this server") and point at the verifier-hardening ticket #12390 for the enterprise-grade closure.
Acceptance Criteria
Out of Scope
- The server-side OIDC/Keycloak mode (owned by
Authorization.md).
- Any specific deployment's hostnames/secrets (those live in the deployment repo, not neo docs).
- Implementing the verifier hardening itself (that is #12390).
Decision Record impact
none — documentation of an existing, shipped capability path.
Related
Origin Session ID: c279991f-11eb-4e89-9e38-2c9c4a78421e
Handoff Retrieval Hints: query_raw_memories("OAuth browser-login authServerMetadataUrl gitlab-pat bare 401 pre-registered client_id read_user"); anchor learn/agentos/cloud-deployment/ClientAuthentication.md.
Authored by @neo-opus-ada (claude-opus-4.8-1m)
Context
Settling the recommended client-auth posture for a GitLab-backed cloud MCP deployment converged on: OAuth browser-login (via a pre-registered GitLab OAuth app) as the primary path, with a Personal Access Token only as a fallback. That recommendation is not yet reflected in neo's canonical cloud-deployment docs.
learn/agentos/cloud-deployment/ClientAuthentication.md(#12380) documents only the PAT path and defers all OAuth tolearn/agentos/tooling/Authorization.md— butAuthorization.mdcovers the server-side OIDC mode (Keycloak/Google/OIDC with PRM + introspection +aud), not the path we actually recommend: a server ingitlab-patbearer mode (bare401, token-agnostic/api/v4/uservalidation) where the client runs an OAuth browser login to mint a short-lived bearer.The Problem
There is no canonical neo doc for the recommended, verified path:
gitlab-patmode → emits a bare401(no Protected-Resource-Metadata, since GitLab has no DCR — seeMcpInspectorCompatibility.md).authServerMetadataUrl-style override + a pre-registered OAuthclient_id(GitLab has no DCR)./api/v4/user— identical to a PAT, because the verifier is token-type-agnostic.This is the enterprise-appropriate path (short-lived, SSO, no static secret in config). It's the missing canonical recipe; today readers only find PAT.
The Architectural Reality
learn/agentos/cloud-deployment/ClientAuthentication.md(#12380) — currently PAT-only, with a "Pending — MCP Inspector recipe" placeholder, and an "OAuth → see Authorization.md" deferral that points at the wrong (server-OIDC) mode for this case.oauth.authServerMetadataUrl) supports pointing at the AS metadata + a pre-registeredclient_id+callbackPort+scopesagainst a bare-401server. The verified mechanism isauthServerMetadataUrl→ the AS's/.well-known/openid-configuration, redirecthttp://localhost:<port>/callback, scoperead_user.The Fix
Extend
ClientAuthentication.mdwith an OAuth browser-login section, presented as the primary path:read_user, per-harness redirect URIs, no DCR needed).401case: theauthServerMetadataUrloverride + pre-registeredclient_id+callbackPort+scopes. Per-harness, with explicit "verified" vs "documented-not-yet-verified" status.Acceptance Criteria
ClientAuthentication.mdpresents OAuth-browser-login as the primary path + PAT as the documented fallback.401+ pre-registered-client OAuth recipe (authServerMetadataUrl, redirect URI,read_user) is documented with per-harness status.learn/tree.jsonnav unaffected or updated to mirror (no orphan group).Out of Scope
Authorization.md).Decision Record impact
none— documentation of an existing, shipped capability path.Related
ClientAuthentication.mdorigin #12380 · Inspector compat #12379 · verifier hardening #12390 · epic #12377.Origin Session ID: c279991f-11eb-4e89-9e38-2c9c4a78421e
Handoff Retrieval Hints:
query_raw_memories("OAuth browser-login authServerMetadataUrl gitlab-pat bare 401 pre-registered client_id read_user"); anchorlearn/agentos/cloud-deployment/ClientAuthentication.md.Authored by @neo-opus-ada (claude-opus-4.8-1m)