fix(connect-studio): make the connect command actually work end-to-end

Two real bugs surfaced by testing the generated command against a live
local Studio (Claude Code → HTTP 400, then 0 tools):

1. Aggregate org resolution (HTTP 400). `/api/:org/mcp` →
   handleVirtualMcpRequest resolved the org ONLY from x-org-id/x-org-slug
   headers, which external MCP clients (Claude Code/Desktop) never send —
   the org is in the URL path, already in ctx.organization via
   resolveOrgFromPath. Fall back to it so the endpoint stops 400ing with
   "Agent ID or organization ID is required".

2. Empty toolset. The bare aggregate resolves to the Decopilot agent,
   which is a pure orchestrator with connections:[] (routes via subtask) —
   so an external client sees ZERO tools. Point the connect URL at
   `/api/:org/mcp/self` instead: the org's real management surface (Library
   files, agents, connections, automations, brand, AI providers, secrets).
   Verified live: initialize + tools/list (142 tools) + a real
   ORGANIZATION_LIST call all succeed over the API-key command.

Also: derive the MCP server name in the command from the host
(`belo-horizonte.localhost` locally, `studio.decocms.com` in prod) so each
deployment gets a distinct entry and adding two never collides.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: vibegui

apps/mesh/src/api/routes/virtual-mcp.ts

@@ -47,7 +47,13 @@ export async function handleVirtualMcpRequest(
   const ctx = c.get("meshContext");
 
   try {
-    // Prefer x-org-id header (no DB lookup) over x-org-slug (requires DB lookup)
+    // Prefer x-org-id header (no DB lookup) over x-org-slug (requires DB lookup).
+    // External MCP clients (Claude Code/Desktop) send NEITHER — the org is in
+    // the URL path (`/api/:org/mcp`), already resolved into `ctx.organization`
+    // by the resolveOrgFromPath middleware. Fall back to it so the aggregate
+    // (Decopilot) endpoint works without the internal UI's x-org-* headers;
+    // otherwise organizationId stays null and the request 400s with
+    // "Agent ID or organization ID is required".
     const orgId = c.req.header("x-org-id");
     const orgSlug = c.req.header("x-org-slug");
 
@@ -60,7 +66,7 @@ export async function handleVirtualMcpRequest(
             .where("slug", "=", orgSlug)
             .executeTakeFirst()
             .then((org) => org?.id)
-        : null;
+        : (ctx.organization?.id ?? null);
 
     const virtualId = virtualMcpId
       ? virtualMcpId

apps/mesh/src/web/components/connect/install-snippet.tsx

@@ -1,6 +1,7 @@
 import { Button } from "@deco/ui/components/button.tsx";
 import { useCopy } from "@deco/ui/hooks/use-copy.ts";
 import { Check, Copy01 } from "@untitledui/icons";
+import { connectServerName } from "@/web/components/connect/mcp-url";
 
 export type ConnectClient =
   | "claude-code"
@@ -11,8 +12,6 @@ export type ConnectClient =
 
 export type ConnectMode = "oauth" | "api-key";
 
-const SERVER_NAME = "studio";
-
 interface SnippetBlock {
   language: string;
   code: string;
@@ -32,17 +31,18 @@ function buildSnippet({
   apiKey?: string;
 }): SnippetBlock {
   const key = apiKey ?? "<paste-your-api-key>";
+  const serverName = connectServerName();
 
   if (client === "claude-code") {
     if (mode === "oauth") {
       return {
         language: "bash",
-        code: `claude mcp add --transport http --scope user ${SERVER_NAME} ${url}`,
+        code: `claude mcp add --transport http --scope user ${serverName} ${url}`,
       };
     }
     return {
       language: "bash",
-      code: `claude mcp add --transport http --scope user ${SERVER_NAME} ${url} \\\n  --header "Authorization: Bearer ${key}"`,
+      code: `claude mcp add --transport http --scope user ${serverName} ${url} \\\n  --header "Authorization: Bearer ${key}"`,
     };
   }
 
@@ -54,12 +54,12 @@ function buildSnippet({
     return {
       language: "json",
       pathHint: "~/.cursor/mcp.json",
-      code: JSON.stringify({ mcpServers: { [SERVER_NAME]: server } }, null, 2),
+      code: JSON.stringify({ mcpServers: { [serverName]: server } }, null, 2),
     };
   }
 
   if (client === "codex") {
-    const lines = [`[mcp_servers.${SERVER_NAME}]`, `url = "${url}"`];
+    const lines = [`[mcp_servers.${serverName}]`, `url = "${url}"`];
     if (mode === "api-key") {
       lines.push(`http_headers = { "Authorization" = "Bearer ${key}" }`);
     }
@@ -78,7 +78,7 @@ function buildSnippet({
     return {
       language: "json",
       pathHint: "claude_desktop_config.json",
-      code: JSON.stringify({ mcpServers: { [SERVER_NAME]: server } }, null, 2),
+      code: JSON.stringify({ mcpServers: { [serverName]: server } }, null, 2),
     };
   }
 

apps/mesh/src/web/components/connect/mcp-url.ts

@@ -4,16 +4,34 @@
  * dialog and the full Connect settings page can't drift apart.
  */
 
-/** MCP server name registered in the client's config (e.g. `studio`). */
-const CONNECT_SERVER_NAME = "studio";
+/**
+ * MCP server name registered in the client's config — derived from the current
+ * host so each Studio deployment gets a distinct entry and adding two never
+ * collides: `studio.decocms.com` in prod, `belo-horizonte.localhost` locally.
+ * Falls back to `studio` during SSR (no `window`).
+ */
+export function connectServerName(): string {
+  if (typeof window === "undefined") return "studio";
+  return window.location.hostname || "studio";
+}
 
-/** The org-scoped unified MCP endpoint: `<origin>/api/<slug>/mcp`. */
+/**
+ * The org-scoped MCP endpoint a client should connect to:
+ * `<origin>/api/<slug>/mcp/self`.
+ *
+ * NOT the bare aggregate `/api/<slug>/mcp` — that resolves to the Decopilot
+ * agent, which is a pure orchestrator with NO directly-callable tools (it routes
+ * everything through sub-agents via `subtask`), so an external client sees zero
+ * tools. `/mcp/self` is the org's own management surface: Library files, agents,
+ * connections, automations, brand, AI providers, secrets — i.e. everything you
+ * need to actually drive the org from Claude.
+ */
 export function mcpUrl(orgSlug: string): string {
   const origin =
     typeof window === "undefined"
       ? "http://localhost:3000"
       : window.location.origin;
-  return `${origin}/api/${orgSlug}/mcp`;
+  return `${origin}/api/${orgSlug}/mcp/self`;
 }
 
 /**
@@ -27,5 +45,5 @@ export function claudeCodeCommandWithKey(
   orgSlug: string,
   apiKey: string,
 ): string {
-  return `claude mcp add --transport http --scope user ${CONNECT_SERVER_NAME} ${mcpUrl(orgSlug)} --header "Authorization: Bearer ${apiKey}"`;
+  return `claude mcp add --transport http --scope user ${connectServerName()} ${mcpUrl(orgSlug)} --header "Authorization: Bearer ${apiKey}"`;
 }