MCP install URLs pin the org slug; the server accepts slug or legacy id

The connect-agent card and setup-mcp onboarding now print
/<org-slug>/mcp instead of /org_xxx/mcp. Server-side the MCP path
classifier claims slug-shaped segments alongside the legacy org_ form
(the slug grammar reserves every routable root segment, so console
paths ending in /mcp still fall through to the SPA), and the org
authorizer resolves a slug through the mirror before the live WorkOS
membership check — the URL stays a selector, not a trust boundary.
Existing org_-pinned URLs in agents' configs keep working; discovery
docs echo whichever selector form the client used.

Self-host and cloudflare cards print the bare /mcp — their servers
only mount the bare endpoint and a single-org instance has nothing to
select.

Author: RhysSullivan

apps/cloud/src/app-paths.test.ts

@@ -19,6 +19,12 @@ describe("isAppOwnedPath", () => {
     "/mcp",
     "/.well-known/oauth-protected-resource/mcp",
     "/.well-known/oauth-authorization-server",
+    // Org-pinned MCP: the org's URL slug (what the install card prints) and
+    // the legacy WorkOS org-id form both select an org on the MCP plane.
+    "/acme-corp/mcp",
+    "/org_01ABCDEF/mcp",
+    "/.well-known/oauth-protected-resource/acme-corp/mcp",
+    "/.well-known/oauth-protected-resource/org_01ABCDEF/mcp",
   ];
   for (const pathname of appOwned) {
     it(`forwards ${pathname} to the app handler`, () => {
@@ -28,7 +34,19 @@ describe("isAppOwnedPath", () => {
 
   // Start-owned: the React shell + its routes. Note `/billing` (the React page)
   // is distinct from `/api/billing/*` (the proxy) — only the latter is app-owned.
-  const startOwned = ["/", "/policies", "/login", "/billing", "/org", "/assets/app.js"];
+  // `/settings/mcp` guards the slug-selector grammar: a RESERVED first segment
+  // can never be an org slug, so console-route-shaped paths ending in /mcp fall
+  // through to the SPA instead of being swallowed by the MCP plane.
+  const startOwned = [
+    "/",
+    "/policies",
+    "/login",
+    "/billing",
+    "/org",
+    "/assets/app.js",
+    "/settings/mcp",
+    "/integrations/mcp",
+  ];
   for (const pathname of startOwned) {
     it(`leaves ${pathname} to the Start router`, () => {
       expect(isAppOwnedPath(pathname)).toBe(false);

apps/cloud/src/mcp/auth-provider.ts

@@ -123,33 +123,35 @@ export const cloudMcpAuthProviderLayer: Layer.Layer<
         // not on the org outcome, to preserve that telemetry.
         const parseBody = request.method === "POST";
 
-        // URL is the source of truth for the active org when pinned (`/org_xxx/mcp`,
-        // carried in the header by `prepareMcpOrgScope`); the bare `/mcp` falls back
-        // to the token's `org_id`. Either way `orgAuth.authorize` re-checks live
-        // WorkOS membership below, so the URL is a selector, not a trust boundary.
-        const organizationId = mcpOrganizationFromRequest(request) ?? token.organizationId;
-        if (!organizationId) {
+        // URL is the source of truth for the active org when pinned — the org's
+        // slug (`/acme/mcp`, what the install card prints) or a legacy org id
+        // (`/org_xxx/mcp`), carried in the header by `prepareMcpOrgScope`; the
+        // bare `/mcp` falls back to the token's `org_id`. Either way
+        // `orgAuth.authorize` resolves the selector and re-checks live WorkOS
+        // membership below, so the URL is a selector, not a trust boundary.
+        const organizationSelector = mcpOrganizationFromRequest(request) ?? token.organizationId;
+        if (!organizationSelector) {
           yield* annotateMcpRequest(request, { token, parseBody });
           return forbidden(NO_ORGANIZATION_MESSAGE, -32001);
         }
 
-        const allowed = yield* orgAuth.authorize(token.accountId, organizationId).pipe(
+        const organizationId = yield* orgAuth.authorize(token.accountId, organizationSelector).pipe(
           Effect.catchCause((error) =>
             Effect.gen(function* () {
               yield* Effect.annotateCurrentSpan({
                 "mcp.auth.organization_authorize_error": Cause.pretty(error),
               });
-              return false;
+              return null;
             }),
           ),
           Effect.withSpan("mcp.auth.authorize_organization", {
-            attributes: { "mcp.auth.organization_id": organizationId },
+            attributes: { "mcp.auth.organization_selector": organizationSelector },
           }),
         );
 
         yield* annotateMcpRequest(request, { token, parseBody });
 
-        if (!allowed) return forbidden(NO_ORGANIZATION_MESSAGE, -32001);
+        if (!organizationId) return forbidden(NO_ORGANIZATION_MESSAGE, -32001);
         return authenticated(principalFromToken(token, organizationId));
       });
 

apps/cloud/src/mcp/auth.ts

@@ -16,7 +16,7 @@ import { createCachedRemoteJWKSet } from "../auth/jwks-cache";
 import { ApiKeyService } from "../auth/api-keys";
 import { BEARER_PREFIX } from "../auth/bearer";
 import { authorizeOrganization } from "../auth/organization";
-import { makeUserStoreLayer } from "../auth/context";
+import { UserStoreService, makeUserStoreLayer } from "../auth/context";
 import { CoreSharedServices } from "../auth/workos";
 import { makeDbLayer } from "../db/db";
 import { bearerChallenge } from "./responses";
@@ -68,14 +68,16 @@ export const MCP_ORGANIZATION_HEADER = "x-executor-mcp-organization";
 export const mcpOrganizationFromRequest = (request: Request): string | null =>
   request.headers.get(MCP_ORGANIZATION_HEADER);
 
-/** The MCP resource URL for an org (`…/org_xxx/mcp`), or the bare resource. */
-export const resourceUrlFor = (organizationId: string | null): string =>
-  organizationId ? `${RESOURCE_ORIGIN}/${organizationId}${MCP_PATH}` : RESOURCE_URL;
+/** The MCP resource URL for an org selector (`…/acme/mcp` slug or legacy
+ *  `…/org_xxx/mcp` id — echoed verbatim so it matches the URL the client
+ *  used), or the bare resource. */
+export const resourceUrlFor = (organizationSelector: string | null): string =>
+  organizationSelector ? `${RESOURCE_ORIGIN}/${organizationSelector}${MCP_PATH}` : RESOURCE_URL;
 
-/** The protected-resource-metadata URL for an org, or the bare one. */
-export const protectedResourceMetadataUrlFor = (organizationId: string | null): string =>
-  organizationId
-    ? `${RESOURCE_ORIGIN}/.well-known/oauth-protected-resource/${organizationId}/mcp`
+/** The protected-resource-metadata URL for an org selector, or the bare one. */
+export const protectedResourceMetadataUrlFor = (organizationSelector: string | null): string =>
+  organizationSelector
+    ? `${RESOURCE_ORIGIN}/.well-known/oauth-protected-resource/${organizationSelector}/mcp`
     : PROTECTED_RESOURCE_METADATA_URL;
 
 type McpUnauthorizedReason = "missing_bearer" | "invalid_token";
@@ -137,10 +139,16 @@ export class McpAuth extends Context.Service<
 export class McpOrganizationAuth extends Context.Service<
   McpOrganizationAuth,
   {
+    /**
+     * Authorize `accountId` against an org SELECTOR — a WorkOS org id
+     * (`org_…`, from the token or a legacy URL) or the org's URL slug (the
+     * form the install card prints). Returns the resolved org id when the
+     * caller holds an active membership, `null` otherwise.
+     */
     readonly authorize: (
       accountId: string,
-      organizationId: string,
-    ) => Effect.Effect<boolean, unknown>;
+      organizationSelector: string,
+    ) => Effect.Effect<string | null, unknown>;
   }
 >()("@executor-js/cloud/McpOrganizationAuth") {}
 
@@ -164,10 +172,28 @@ const makeMcpOrganizationAuthServices = () => {
   return Layer.mergeAll(dbLive, userStoreLive, CoreSharedServices);
 };
 
+// A URL slug resolves through the mirror to its org id before the membership
+// check; an unknown slug authorizes nothing. Ids pass straight through —
+// `authorizeOrganization` verifies live WorkOS membership either way.
+const resolveOrgSelector = (selector: string) =>
+  selector.startsWith("org_")
+    ? Effect.succeed(selector)
+    : Effect.gen(function* () {
+        const users = yield* UserStoreService;
+        const org = yield* users.use((s) => s.getOrganizationBySlug(selector));
+        return org?.id ?? null;
+      });
+
 export const McpOrganizationAuthLive = Layer.succeed(McpOrganizationAuth)({
-  authorize: (accountId, organizationId) =>
-    authorizeOrganization(accountId, organizationId).pipe(
-      Effect.map((org) => org !== null),
+  authorize: (accountId, organizationSelector) =>
+    resolveOrgSelector(organizationSelector).pipe(
+      Effect.flatMap((organizationId) =>
+        organizationId
+          ? authorizeOrganization(accountId, organizationId).pipe(
+              Effect.map((org) => (org ? org.id : null)),
+            )
+          : Effect.succeed(null),
+      ),
       Effect.provide(makeMcpOrganizationAuthServices()),
     ),
 });

apps/cloud/src/mcp/mount.ts

@@ -27,6 +27,7 @@
 import { HttpRouter, HttpServer } from "effect/unstable/http";
 import { Layer } from "effect";
 
+import { isValidOrgSlug } from "@executor-js/api";
 import { McpServingRoutes } from "@executor-js/host-mcp";
 
 import {
@@ -45,20 +46,27 @@ type McpRouteKind = "mcp" | "oauth-protected-resource" | "oauth-authorization-se
 
 type McpRoute = {
   readonly kind: McpRouteKind;
-  /** Org id pinned in the URL (`/org_xxx/mcp`), or `null` for the bare path. */
+  /** Org selector pinned in the URL (`/acme/mcp` slug or legacy `/org_xxx/mcp`
+   *  id), or `null` for the bare path. Resolved to an org id — and re-checked
+   *  against live membership — in the auth provider. */
   readonly organizationId: string | null;
 } | null;
 
-// A path segment counts as an org selector only when it has the WorkOS org-id
-// shape (`org_…`), so an unrelated `/<seg>/mcp` still falls through to routing.
-const orgIdSegment = (segment: string | undefined): string | null =>
-  segment && segment.startsWith("org_") ? segment : null;
+// A path segment counts as an org selector when it's the org's URL slug (the
+// canonical form the install card prints) or has the WorkOS org-id shape
+// (`org_…`, the legacy form already in agents' configs). The slug grammar
+// reserves every routable root segment (`integrations`, `api-keys`, …), so an
+// unrelated `/<seg>/mcp` still falls through to routing.
+const orgSelectorSegment = (segment: string | undefined): string | null =>
+  segment && (segment.startsWith("org_") || isValidOrgSlug(segment)) ? segment : null;
 
 // Matches a trailing MCP endpoint — `mcp` (bare) or `<org>/mcp`. Returns the org
-// id, `null` for the bare form, or `undefined` when the segments are neither.
+// selector, `null` for the bare form, or `undefined` when the segments are neither.
 const matchMcpSuffix = (segments: readonly string[]): string | null | undefined => {
   if (segments.length === 1 && segments[0] === "mcp") return null;
-  if (segments.length === 2 && segments[1] === "mcp") return orgIdSegment(segments[0]) ?? undefined;
+  if (segments.length === 2 && segments[1] === "mcp") {
+    return orgSelectorSegment(segments[0]) ?? undefined;
+  }
   return undefined;
 };
 

apps/cloud/src/routes/__root.tsx

@@ -296,7 +296,10 @@ function AuthGate() {
         <ExecutorProvider onHandledError={captureFrontendError}>
           <React.Suspense fallback={<ShellSkeleton />}>
             <ExecutorPluginsProvider plugins={clientPlugins}>
-              <OrganizationProvider organizationId={auth.organization.id}>
+              <OrganizationProvider
+                organizationId={auth.organization.id}
+                organizationSlug={activeSlug}
+              >
                 <OrgSlugGate
                   activeSlug={activeSlug}
                   foreignSlug={(slug) => <ForeignOrgSlug slug={slug} />}

apps/cloud/src/web/pages/setup-mcp.tsx

@@ -20,7 +20,8 @@ import { useAuth } from "../auth";
 export const SetupMcpPage = () => {
   const navigate = useNavigate();
   const auth = useAuth();
-  const organizationId = auth.status === "authenticated" ? (auth.organization?.id ?? null) : null;
+  const organizationSlug =
+    auth.status === "authenticated" ? (auth.organization?.slug ?? null) : null;
   const [origin, setOrigin] = useState<string | null>(null);
   const [advancedOpen, setAdvancedOpen] = useState(false);
   const [elicitationMode, setElicitationMode] = useState<McpElicitationMode>("model");
@@ -34,7 +35,7 @@ export const SetupMcpPage = () => {
         origin,
         desktop: null,
         elicitationMode,
-        organizationId,
+        organizationSlug,
       })
     : "";
   const command = origin
@@ -43,7 +44,7 @@ export const SetupMcpPage = () => {
         isDev: false,
         origin,
         elicitationMode,
-        organizationId,
+        organizationSlug,
       })
     : "";
 

apps/host-cloudflare/web/routes/__root.tsx

@@ -74,6 +74,9 @@ function AuthenticatedApp() {
   return (
     <ExecutorProvider>
       <ExecutorPluginsProvider plugins={clientPlugins}>
+        {/* No organizationSlug: the worker serves only the bare /mcp (see
+            wrangler.jsonc run_worker_first), so a slug-pinned URL would fall
+            through to the SPA. */}
         <OrganizationProvider organizationId={organization?.id ?? null}>
           {organization ? <OrgSlugGate activeSlug={organization.slug}>{gated}</OrgSlugGate> : gated}
         </OrganizationProvider>

apps/host-selfhost/web/routes/__root.tsx

@@ -82,6 +82,9 @@ function AuthenticatedApp() {
   return (
     <ExecutorProvider>
       <ExecutorPluginsProvider plugins={clientPlugins}>
+        {/* No organizationSlug: the self-host MCP endpoint is the bare /mcp —
+            a slug-pinned URL would 404, and a single-org instance has nothing
+            to select anyway. */}
         <OrganizationProvider organizationId={organization?.id ?? null}>
           {organization ? <OrgSlugGate activeSlug={organization.slug}>{gated}</OrgSlugGate> : gated}
         </OrganizationProvider>

e2e/cloud/mcp-protocol.test.ts

@@ -296,6 +296,37 @@ scenario(
     ).toBeTruthy();
     yield* Effect.promise(() => member.text());
 
+    // The slug form — what the install card prints (`/acme/mcp`) — selects
+    // the same org. The slug comes from the account surface.
+    const me = yield* Effect.promise(() =>
+      fetch(new URL("/api/account/me", target.baseUrl), { headers: identity.headers }).then(
+        (r) => r.json() as Promise<{ organization: { slug: string } | null }>,
+      ),
+    );
+    const ownSlug = me.organization?.slug;
+    expect(ownSlug, "the account surface advertises the org's URL slug").toBeTruthy();
+    const slugged = yield* Effect.promise(() =>
+      mcpPost(new URL(`/${ownSlug}/mcp`, target.baseUrl), {
+        bearer,
+        body: INITIALIZE_REQUEST,
+      }),
+    );
+    expect(slugged.status, "the member's slug-pinned URL opens a session").toBe(200);
+    expect(
+      slugged.headers.get("mcp-session-id"),
+      "the slug-pinned session is a real session",
+    ).toBeTruthy();
+    yield* Effect.promise(() => slugged.text());
+
+    // An unknown slug selects nothing — same rejection as a foreign org id.
+    const unknownSlug = yield* Effect.promise(() =>
+      mcpPost(new URL(`/zz-no-such-org-${randomBytes(3).toString("hex")}/mcp`, target.baseUrl), {
+        bearer,
+        body: INITIALIZE_REQUEST,
+      }),
+    );
+    expect(unknownSlug.status, "an unknown slug authorizes nothing").toBe(403);
+
     const foreignOrg = `org_e2e_${randomBytes(4).toString("hex")}`;
     const foreign = yield* Effect.promise(() =>
       mcpPost(new URL(`/${foreignOrg}/mcp`, target.baseUrl), {

e2e/cloud/onboarding-mcp-url.test.ts

@@ -45,16 +45,21 @@ scenario(
 
       const mcpUrlSection = page.getByRole("region", { name: "MCP server URL" });
       const mcpUrl = await mcpUrlSection.locator("span.font-mono").innerText();
-      expect(mcpUrl, "MCP URL is org-scoped").toMatch(/\/org_[^/]+\/mcp/);
+      // Org-scoped via the org's URL slug (the readable form), not the raw
+      // WorkOS org_… id — and not the bare /mcp path.
+      expect(mcpUrl, "MCP URL is slug-scoped").toMatch(/\/[a-z0-9-]+\/mcp/);
+      expect(mcpUrl, "the slug form, not the org_ id").not.toMatch(/\/org_[^/]+\/mcp/);
 
       const installSection = page.getByRole("region", { name: "Install command" });
       await installSection.waitFor();
       const installCommand = await installSection.locator("code").innerText();
 
       // The install command must reference the SAME org as the displayed URL
       // — not a different one or a bare /mcp path.
-      const orgId = /\/(org_[^/]+)\/mcp/.exec(mcpUrl)?.[1] ?? "(no org segment in MCP URL)";
-      expect(installCommand, "the install command references the same org").toContain(orgId);
+      const orgSlug = /\/([a-z0-9-]+)\/mcp/.exec(mcpUrl)?.[1] ?? "(no org segment in MCP URL)";
+      expect(installCommand, "the install command references the same org").toContain(
+        `/${orgSlug}/mcp`,
+      );
     });
   }),
 );