What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	12377
title	[Epic] Cloud-deployment client auth — GitLab-PAT Bearer login + MCP Inspector v0.21.2 compatibility (GitLab-first)
state	Closed
labels	epicai
assignees	[]
createdAt	Jun 2, 2026, 2:01 PM
updatedAt	Jun 7, 2026, 7:18 PM
githubUrl	https://github.com/neomjs/neo/issues/12377
author	neo-opus-ada
commentsCount	2
parentIssue	null
subIssues	12378 [neo] GitLab-PAT Bearer auth mode in AuthService — no `aud`, naked 401 (Sub of #12377) 12379 [neo] MCP Inspector v0.21.2 compatibility — repro-first; verify manual-Bearer before any DCR shim (Sub of #12377) 12380 [neo] Canonical cloud-deployment client-auth docs — GitLab-PAT Bearer login recipes (Sub of #12377)
subIssuesCompleted	3
subIssuesTotal	3
blockedBy	[]
blocking	[]
closedAt	Jun 2, 2026, 10:13 PM

[Epic] Cloud-deployment client auth — GitLab-PAT Bearer login + MCP Inspector v0.21.2 compatibility (GitLab-first)

Closed v13.0.0/archive-v13-0-0-chunk-15 epicai

neo-opus-ada commented on Jun 2, 2026, 2:01 PM

Goal

Enable real users AND headless agents to authenticate to the cloud-deployed MCP servers (Knowledge Base + Memory Core) using a GitLab Personal Access Token as a Bearer token — sourced from an env var (GitLab user settings → token), no browser-OAuth dance, no session cookie (cookies are brittle for users/agents). AND make MCP Inspector v0.21.2 connect (currently blocked). GitLab-first — the first real client uses GitLab; design for GitLab now, generalize later.

Why (V-B-A)

neo AuthService already does Bearer-token auth (RFC 7662 introspection + requireBearerAuth) BUT (a) enforces the aud claim == MCP-server URL → a raw GitLab PAT is rejected, and (b) advertises OAuth Protected-Resource-Metadata via mcpAuthMetadataRouter.
That PRM advertisement triggers MCP Inspector v0.21+'s mandatory OAuth Dynamic Client Registration — which GitLab does not support → connection fails. Inspector v0.14 worked only because it predates OAuth auto-discovery.
Inspector issue #369 (manual Bearer header dropped) is fixed by PR #370; #879 remains open. So the simpler "paste a Bearer token" path may work in v0.21.2 — must be verified before any heavier OAuth/DCR work.
GitLab supports Bearer-token REST auth; a PAT with read_user scope can hit GET /api/v4/user to resolve the username.

Sub-structure (foundation-first DAG)

GitLab-PAT Bearer auth mode in neo AuthService (FOUNDATION) — validate Authorization: Bearer <PAT> against GitLab /api/v4/user, no aud requirement, naked 401 (no PRM advertisement → Inspector-friendly), config-gated. Blocks subs 2 & 3. — @neo-opus-ada
MCP Inspector v0.21.2 compatibility — repro/investigation-first: reproduce v0.21.2 against the gated server, verify whether the manual-Bearer path works (given #369→#370); only if it fails, evaluate options (DCR shim + GitLab OAuth, documented fallback). Do NOT bake a DCR/OAuth shim into the ACs before the repro falsifies manual-Bearer. Starts once sub 1's auth-mode contract is visible. — @neo-gpt
Canonical cloud-deployment client-auth docs (learn/agentos/cloud-deployment) — how users/agents log in (PAT Bearer), client recipes (mcp-remote / Claude Code / Inspector), the naked-401 model. Depends on subs 1 & 2; folds into the Track-1 docs hardening. — @neo-opus-ada

Downstream deployment wiring is out of scope for this Neo epic.

Split (converged with @neo-gpt)

@neo-opus-ada: files this epic, takes sub 1 (foundation) + sub 3 + the downstream deployment deployment ticket.
@neo-gpt: takes sub 2 (Inspector compat investigation) after sub 1's auth-mode contract is visible.

Acceptance (epic-level)

A user/agent with a GitLab PAT in an env var connects to KB + MC via Authorization: Bearer <PAT> (mcp-remote / Claude Code) with no cookie/OAuth-dance.
MCP Inspector v0.21.2's behavior against the server is reproduced and either made to connect or documented with a clear recommendation.
The login path is documented (canonical + downstream deployment deployment).

GitLab-first; generalization to other OIDC providers is out of scope for this epic.