fix(mcp-oauth): let external OAuth clients use aggregate/virtual MCP endpoints

[AriOliv]

Problem

External MCP clients (Claude Desktop / Claude Code, or any RFC 9728 / MCP OAuth client) can't connect to an org's aggregate (/api/:org/mcp) or virtual-MCP endpoints and call tools. Three independent causes:

1. No usable OAuth authorization server advertised.

   • The aggregate endpoint exposes no oauth-protected-resource metadata → 404.
   • Virtual-MCP endpoints try to proxy the downstream connection's OAuth metadata, but a virtual MCP's connection_url is virtual://<id> — nothing to fetch → 502 (protocol must be http/https/s3).
   • Neither advertises Studio's own Better Auth MCP authorization server (which supports Dynamic Client Registration). The connection oauth-proxy only accepts Studio's own redirect_uri, so it can't serve an external client that brings its own callback → invalid_request: redirect_uri is not allowed.

2. WWW-Authenticate advertises an http:// resource_metadata URL when Studio runs behind a TLS-terminating reverse proxy (Caddy/nginx forward over http). https-only clients (e.g. Claude) reject the non-https metadata URL.

3. MCP OAuth sessions resolve the member role from the wrong org. External clients don't send x-org-id / x-org-slug; the org is in the URL path (/api/:org/...). A multi-org member falls through to the "single membership only" guard, resolves to no role, loses the owner/admin bypass, and every connection tool call 403s Access denied to: <tool>.

Fix

File	Change
api/app.ts (mcpAuth)	Honor X-Forwarded-Proto when building the resource_metadata origin so it advertises https:// behind a proxy.
api/routes/org-scoped.ts	Serve Better Auth protected-resource metadata at the aggregate /api/:org/mcp/.well-known/oauth-protected-resource (mounted before the proxy catch-all).
api/routes/oauth-proxy.ts	For virtual:// connections, return Better Auth metadata instead of proxying a nonexistent downstream AS.
core/context-factory.ts	Derive an org-slug hint from the request path for MCP OAuth membership/role resolution.

Net effect: an external client discovers Studio's own Better Auth AS, registers via DCR (its own redirect_uri accepted), logs in against Studio, and the token resolves to the caller's real role in the path org. Downstream per-user OAuth still happens lazily when a per_user connection's tool is first invoked. RBAC is unchanged — owner/admin bypass; non-admins still need an explicit connection grant.

Testing

Validated end-to-end against a deployed Studio (behind Caddy TLS) with Claude Code:

• POST /api/:org/mcp/<virtual-mcp-id> → 401 + WWW-Authenticate with an https resource_metadata.
• Well-known → 200 advertising Studio's Better Auth AS (authorization_servers: [<studio>]).
• DCR with a claude.ai redirect_uri → accepted; /authorize → 302 (no redirect_uri is not allowed).
• After connect, a multi-org admin member's tool calls succeed (previously 403 Access denied).

🤖 Generated with Claude Code

---

Summary by cubic

Enable external MCP OAuth clients (e.g. Claude) to connect to org aggregate /api/:org/mcp and virtual MCP endpoints. Also shorten aggregated tool name prefixes so names fit the 64-char limit.

• Bug Fixes
  • Serve Studio better-auth protected-resource metadata for aggregate and virtual:// MCP endpoints, enabling DCR and external redirect_uris.
  • Use X-Forwarded-Proto when building resource_metadata so https is advertised behind proxies.
  • Resolve org from /api/:org/... path when headers are absent to fix RBAC for multi-org members.
  • Allow per-connection RFC 8707 resource via connection.metadata.oauthResource; default to connection.connection_url.
  • Per-user OAuth: don’t force offline_access; return the 401 challenge without recording failures in both lazy-client and proxy paths.
  • Aggregate tooling: replace long slug prefixes with a short, stable namespace code in tool/prompt names to stay under 64 chars.

^{Written for commit e51ad76. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 4 files

_{Re-trigger cubic}

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/src/mcp-clients/lazy-client.ts">

<violation number="1" location="apps/mesh/src/mcp-clients/lazy-client.ts:128">
P1: The added suppression prevents per-user auth errors from tripping the circuit breaker, which is good, but it doesn't help when the circuit is already open. Because `assertCircuitClosed(connection.id)` runs before `clientFromConnection`, any caller whose connection already has an open circuit gets a 503 and never reaches the per-user auth prompt—even though their caller merely needs to authorize. Since the breaker is keyed by `connection.id` and shared across all users, a prior unrelated downstream failure can hide the "Connect your account" flow from every subsequent caller. Consider elevating the per-user-auth bypass so it also skips an already-open circuit, or segment the breaker state so expected auth prompts aren't blocked by unrelated outages.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: The added suppression prevents per-user auth errors from tripping the circuit breaker, which is good, but it doesn't help when the circuit is already open. Because assertCircuitClosed(connection.id) runs before clientFromConnection, any caller whose connection already has an open circuit gets a 503 and never reaches the per-user auth prompt—even though their caller merely needs to authorize. Since the breaker is keyed by connection.id and shared across all users, a prior unrelated downstream failure can hide the "Connect your account" flow from every subsequent caller. Consider elevating the per-user-auth bypass so it also skips an already-open circuit, or segment the breaker state so expected auth prompts aren't blocked by unrelated outages.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/mcp-clients/lazy-client.ts, line 128:

<comment>The added suppression prevents per-user auth errors from tripping the circuit breaker, which is good, but it doesn't help when the circuit is already open. Because `assertCircuitClosed(connection.id)` runs before `clientFromConnection`, any caller whose connection already has an open circuit gets a 503 and never reaches the per-user auth prompt—even though their caller merely needs to authorize. Since the breaker is keyed by `connection.id` and shared across all users, a prior unrelated downstream failure can hide the "Connect your account" flow from every subsequent caller. Consider elevating the per-user-auth bypass so it also skips an already-open circuit, or segment the breaker state so expected auth prompts aren't blocked by unrelated outages.</comment>

<file context>
@@ -119,7 +120,14 @@ export function createLazyClient(
+          // NOT a downstream outage. Counting it as a failure trips the circuit
+          // breaker, which then 503s the connection — hiding the "Connect your
+          // account" UI and blocking the very OAuth the error is asking for.
+          if (!isPerUserAuthorizationRequiredError(err)) {
+            recordFailure(connection.id);
+          }
</file context>

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/src/api/routes/proxy.ts">

<violation number="1" location="apps/mesh/src/api/routes/proxy.ts:421">
P1: The `isPerUserAuthorizationRequiredError(error)` early return gates the circuit-breaker failure accounting and auto-disable logic. If that cross-file classifier is overly broad (e.g., message-substring or regex based), non-auth downstream failures could be misclassified as expected per-user auth states. That would suppress `recordFailure(...)` and `shouldDisable`, hiding real outages behind repeated 401 responses and silently disabling circuit protection. Given the project convention [ID: 9aca6f72-ab03-43f2-bc16-ef06243974f8] to use exact message equality for internally-controlled errors, verify the classifier uses strict equality rather than substring/regex matching to prevent misclassification.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: The isPerUserAuthorizationRequiredError(error) early return gates the circuit-breaker failure accounting and auto-disable logic. If that cross-file classifier is overly broad (e.g., message-substring or regex based), non-auth downstream failures could be misclassified as expected per-user auth states. That would suppress recordFailure(...) and shouldDisable, hiding real outages behind repeated 401 responses and silently disabling circuit protection. Given the project convention [ID: 9aca6f72-ab03-43f2-bc16-ef06243974f8] to use exact message equality for internally-controlled errors, verify the classifier uses strict equality rather than substring/regex matching to prevent misclassification.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/api/routes/proxy.ts, line 421:

<comment>The `isPerUserAuthorizationRequiredError(error)` early return gates the circuit-breaker failure accounting and auto-disable logic. If that cross-file classifier is overly broad (e.g., message-substring or regex based), non-auth downstream failures could be misclassified as expected per-user auth states. That would suppress `recordFailure(...)` and `shouldDisable`, hiding real outages behind repeated 401 responses and silently disabling circuit protection. Given the project convention [ID: 9aca6f72-ab03-43f2-bc16-ef06243974f8] to use exact message equality for internally-controlled errors, verify the classifier uses strict equality rather than substring/regex matching to prevent misclassification.</comment>

<file context>
@@ -412,6 +412,15 @@ export const createProxyRoutes = () => {
+        // URL) WITHOUT tripping the breaker or auto-disabling the connection.
+        // Handled before recordFailure below, which would otherwise open the
+        // circuit and 503 the connection (hiding the OAuth the error asks for).
+        if (isPerUserAuthorizationRequiredError(error)) {
+          return renderPerUserAuthorizationRequired(error);
+        }
</file context>

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/mcp-utils/src/aggregate/gateway-client.ts">

<violation number="1" location="packages/mcp-utils/src/aggregate/gateway-client.ts:115">
P1: Switching the namespace prefix from a `slugify`-based slug to a hash-based `namespaceCode` breaks resolution for any persisted namespaced identifiers. The `resolveToolTarget`/`resolvePromptTarget` fallback only handles un-namespaced names and new-format namespaced names, but not old-format namespaced names. If external systems or saved configurations store namespaced tool/prompt names (e.g., workflow steps, allow-lists, cached selections), they will fail to resolve after this change.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Switching the namespace prefix from a slugify-based slug to a hash-based namespaceCode breaks resolution for any persisted namespaced identifiers. The resolveToolTarget/resolvePromptTarget fallback only handles un-namespaced names and new-format namespaced names, but not old-format namespaced names. If external systems or saved configurations store namespaced tool/prompt names (e.g., workflow steps, allow-lists, cached selections), they will fail to resolve after this change.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/mcp-utils/src/aggregate/gateway-client.ts, line 115:

<comment>Switching the namespace prefix from a `slugify`-based slug to a hash-based `namespaceCode` breaks resolution for any persisted namespaced identifiers. The `resolveToolTarget`/`resolvePromptTarget` fallback only handles un-namespaced names and new-format namespaced names, but not old-format namespaced names. If external systems or saved configurations store namespaced tool/prompt names (e.g., workflow steps, allow-lists, cached selections), they will fail to resolve after this change.</comment>

<file context>
@@ -89,7 +112,7 @@ export function stripToolNamespace(
 ): string {
   if (!clientId) return namespacedName;
-  const prefix = `${slugify(clientId)}_`;
+  const prefix = `${namespaceCode(clientId)}_`;
   return namespacedName.startsWith(prefix)
     ? namespacedName.slice(prefix.length)
</file context>

[vibegui]

Thanks for the contribution @AriOliv ! One thing: did you forget to add an outbound/errors.ts file?

Claude:

🔴 Critical finding: this PR does not compile

The per-user-auth robustness fix (#5) references two functions and one module that don't exist anywhere on the PR branch:

• apps/mesh/src/api/routes/proxy.ts:421-422 calls isPerUserAuthorizationRequiredError(error) and renderPerUserAuthorizationRequired(error) — and proxy.ts imports neither (I read the full import block, lines 14-39; they're absent).
• apps/mesh/src/mcp-clients/lazy-client.ts:32 does import { isPerUserAuthorizationRequiredError } from "./outbound/errors" — but apps/mesh/src/mcp-clients/outbound/errors.ts does not exist on the branch (confirmed via git ls-tree and full-tree git grep).

There is no definition of either function anywhere in the branch. The author almost certainly forgot to git add a new outbound/errors.ts. Consequences:

• bun run check (typecheck) fails — undefined import + two unresolved identifiers.
• proxy.ts would throw ReferenceError at runtime if that path executed.
• bun test would fail to load the modules.

The only green check on the PR is cubic · AI code reviewer; the actual typecheck/test CI either isn't wired to this PR or hasn't reported — the PR is mergeStateStatus: BLOCKED. This must be fixed before any merge. Ask AriOliv for the missing outbound/errors.ts.

[AriOliv]

Thanks for the catch @vibegui — you were right, outbound/errors.ts never made it into this branch. Rather than patching it here (this branch predates the apps/mesh → apps/api restructure, and the other pieces — namespaceCode, metadata.oauthResource — were already cherry-picked in dc1dca2), I've re-implemented the whole per-user OAuth feature on the current layout, including the missing file and the circuit-breaker piece: #6023. Closing this one in favor of it.