feat(connect): one-click LINK — connect your Studio org to Claude over MCP + OAuth

[vibegui]

What this does

Adds a one-click "LINK" button to the app topbar that connects your Studio
org to Claude (and any MCP client) over its unified MCP endpoint — and brings in
the OAuth backend that makes that connection actually work end to end. Once
linked, Claude can browse/edit your Library, run your agents, and enable + call
any MCP tool in the org, all behind OAuth 2.1 and governed by your existing
RBAC/Decopilot rules.

The org's unified endpoint (/api/:org/mcp) already aggregates every connection
enabled in the org. This PR is the surface that hands that endpoint out, plus the
auth plumbing an external client needs to use it.

Frontend — surfacing the connection

• Topbar LINK button → focused "Connect to Claude" modal built around a
  single action:
  • Claude Code: one button copies the claude mcp add --transport http --scope user studio <url> one-liner (paste in a terminal; OAuth opens the browser on first use).
  • Claude Desktop / claude.ai: copy the MCP URL to add as a custom connector.
  • The modal spells out exactly what Claude gets (Library, agents, MCP tools).
• Connect settings page (/$org/settings/connect) for power users: per-client
  install snippets (Claude Code, Cursor, Codex, Claude Desktop, raw URL) with
  OAuth and API key modes; mint / list / revoke per-user keys via the
  self-MCP tools (API_KEY_CREATE/LIST/DELETE) for headless/CI clients.
• Additional entry points: sidebar footer icon, account menu ("Connect to
  Agents"), and a dismissible banner on Organization settings.
• Shared components/connect/mcp-url.ts helper (mcpUrl / claudeCodeCommand)
  reused by the modal and the settings page so the two can't drift.

Backend — external OAuth clients can use the org endpoint

Cherry-picked (authorship preserved) from #4263 by @AriOliv, the changes an
external MCP OAuth client needs to authenticate and call tools:

• Serve OAuth Protected Resource Metadata at the aggregate endpoint
  /api/:org/mcp/.well-known/oauth-protected-resource and for virtual://
  connections — so clients can discover Studio's Better Auth authorization server
  (with Dynamic Client Registration; the client's own redirect_uri is accepted).
• Honor X-Forwarded-Proto when advertising resource_metadata, so the URL
  is https:// behind a TLS-terminating proxy (Claude rejects non-https).
• Resolve the org from the /api/:org/... path for MCP OAuth sessions —
  fixes multi-org members 403-ing on every tool call (they don't send
  x-org-* headers, so role resolution previously found no membership).
• Per-connection RFC 8707 resource override (metadata.oauthResource),
  defaulting to the connection URL.
• Don't force offline_access on per-connection OAuth — strict servers
  reject it during DCR (e.g. Pipedrive 400 /register); refresh tokens are
  already requested via grant_types.
• Short, stable namespace code for aggregated tool names, keeping them under
  the 64-char limit so every tool lists and works across clients.

Not included / follow-ups

• fix(mcp-oauth): let external OAuth clients use aggregate/virtual MCP endpoints #4263's two "don't trip the circuit breaker on per-user authorization" commits
  (proxy.ts, lazy-client.ts) are omitted — they depend on an
  mcp-clients/outbound/errors.ts helper that isn't on main yet. The core
  aggregate connect flow and all org-owned/shared-auth tools work without it; the
  only gap is that a per_user connection's first tool call could trip the
  breaker instead of cleanly returning a "connect your account" prompt. Can be
  added once that helper lands.
• Overlaps fix(mcp-oauth): let external OAuth clients use aggregate/virtual MCP endpoints #4263 on the backend files — coordinate merge order to avoid a
  double-land conflict.

Test plan

• Topbar LINK button opens the "Connect to Claude" modal; copy actions work.
• claude mcp add … <org-url> → Claude Code completes OAuth against Studio and lists org tools.
• As an owner/admin and as a multi-org member, tool calls succeed (no 403 Access denied).
• GET /api/:org/mcp/.well-known/oauth-protected-resource → 200, advertising Studio's Better Auth AS.
• Behind a TLS proxy, the 401 WWW-Authenticate resource_metadata URL is https://.
• Settings → Connect: OAuth + API-key tabs render correct snippets; key mint/list/revoke works.
• Aggregated tool names stay ≤ 64 chars (gateway-client tests pass).

[github-actions]

Release Options

Suggested: Minor (2.374.0) — based on feat: prefix

React with an emoji to override the release type:

Reaction	Type	Next Version
👍	Prerelease	2.373.8-alpha.1
🎉	Patch	2.373.8
❤️	Minor	2.374.0
🚀	Major	3.0.0

Current version: 2.373.7

Note: If multiple reactions exist, the smallest bump wins. If no reactions, the suggested bump is used (default: patch).

[github-actions]

🧪 Benchmark

Should we run the Virtual MCP strategy benchmark for this PR?

React with 👍 to run the benchmark.

Reaction	Action
👍	Run quick benchmark (10 & 128 tools)

Benchmark will run on the next push after you react.

[cubic-dev-ai]

3 issues found across 4 files

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/web/components/connect-studio/connect-studio-modal.tsx">

<violation number="1" location="apps/mesh/src/web/components/connect-studio/connect-studio-modal.tsx:43">
P3: Local environment detection misses IPv6 loopback (`::1`), which can hide the Connect action during local development.</violation>
</file>

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

<violation number="1" location="apps/mesh/src/api/routes/decopilot/routes.ts:327">
P1: Use `getUserId(ctx)` instead of `ctx.auth?.user?.id` — this will incorrectly return 401 for requests authenticated via API key. The DELETE endpoint already uses `getUserId(ctx)` correctly.

(Based on your team's feedback about using getUserId(ctx) for user-based or API-key authentication.) [FEEDBACK_USED]</violation>

<violation number="2" location="apps/mesh/src/api/routes/decopilot/routes.ts:343">
P1: Use `getUserId(ctx)` instead of `ctx.auth?.user?.id` — under API-key auth, this returns `undefined`, causing a spurious 401 and embedding `"undefined"` in the created API key name.

(Based on your team's feedback about using getUserId(ctx) for user-based or API-key authentication.) [FEEDBACK_USED]</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P1: Use getUserId(ctx) instead of ctx.auth?.user?.id — under API-key auth, this returns undefined, causing a spurious 401 and embedding "undefined" in the created API key name.

(Based on your team's feedback about using getUserId(ctx) for user-based or API-key authentication.)

View Feedback

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/decopilot/routes.ts, line 343:

<comment>Use `getUserId(ctx)` instead of `ctx.auth?.user?.id` — under API-key auth, this returns `undefined`, causing a spurious 401 and embedding `"undefined"` in the created API key name.

(Based on your team's feedback about using getUserId(ctx) for user-based or API-key authentication.) </comment>

<file context>
@@ -192,6 +192,349 @@ export function createDecopilotRoutes(deps: DecopilotDeps) {
+  app.post("/:org/decopilot/connect-studio", async (c) => {
+    const ctx = c.get("meshContext");
+    const organization = ensureOrganization(c);
+    const userId = ctx.auth?.user?.id;
+    if (!userId) {
+      throw new HTTPException(401, { message: "Authentication required" });
</file context>

Suggested change

	const userId = ctx.auth?.user?.id;
	const userId = getUserId(ctx);

[cubic-dev-ai]

P1: Use getUserId(ctx) instead of ctx.auth?.user?.id — this will incorrectly return 401 for requests authenticated via API key. The DELETE endpoint already uses getUserId(ctx) correctly.

(Based on your team's feedback about using getUserId(ctx) for user-based or API-key authentication.)

View Feedback

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/decopilot/routes.ts, line 327:

<comment>Use `getUserId(ctx)` instead of `ctx.auth?.user?.id` — this will incorrectly return 401 for requests authenticated via API key. The DELETE endpoint already uses `getUserId(ctx)` correctly.

(Based on your team's feedback about using getUserId(ctx) for user-based or API-key authentication.) </comment>

<file context>
@@ -192,6 +192,349 @@ export function createDecopilotRoutes(deps: DecopilotDeps) {
+
+  app.get("/:org/decopilot/connect-studio/status", async (c) => {
+    const ctx = c.get("meshContext");
+    if (!ctx.auth?.user?.id) {
+      throw new HTTPException(401, { message: "Authentication required" });
+    }
</file context>

Suggested change

	if (!ctx.auth?.user?.id) {
	if (!getUserId(ctx)) {

[cubic-dev-ai]

P3: Local environment detection misses IPv6 loopback (::1), which can hide the Connect action during local development.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/web/components/connect-studio/connect-studio-modal.tsx, line 43:

<comment>Local environment detection misses IPv6 loopback (`::1`), which can hide the Connect action during local development.</comment>

<file context>
@@ -0,0 +1,379 @@
+  return (
+    typeof window !== "undefined" &&
+    (window.location.hostname === "localhost" ||
+      window.location.hostname === "127.0.0.1")
+  );
+}
</file context>