Share the scoped MCP route list and request parser across hosts

Author: RhysSullivan

apps/cloud/src/mcp/agent-handler.ts

@@ -4,8 +4,7 @@ import { Effect, Predicate } from "effect";
 import {
   McpAuthProvider,
   jsonRpcErrorBody,
-  defaultMcpResource,
-  mcpResourceFromPathname,
+  mcpResourceFromRequest,
   orgWriteAccessForPrincipal,
   withOrgWriteAccess,
   UNAVAILABLE_RETRY_AFTER_SECONDS,
@@ -156,14 +155,6 @@ const runTraced = <A>(request: Request, program: Effect.Effect<A>): Promise<A> =
   );
 };
 
-// The MCP resource the request targets. `server.ts` routes the bare `/mcp` and
-// every scoped sub-resource to this handler (`prepareMcpOrgScope` strips the
-// org selector but keeps the resource segments), so a session minted on a
-// scoped path serves that projection of the catalog. The grammar is the shared
-// one from host-mcp; a path `classifyMcpPath` accepted always parses here.
-const resourceFromPath = (request: Request): McpResource =>
-  mcpResourceFromPathname(new URL(request.url).pathname) ?? defaultMcpResource;
-
 const propsForPrincipal = (
   request: Request,
   principal: Extract<AuthOutcome, { readonly _tag: "Authenticated" }>["principal"],
@@ -287,7 +278,10 @@ export const makeCloudMcpAgentHandler = () => {
       }
     }
 
-    const resource = resourceFromPath(request);
+    // `prepareMcpOrgScope` already stripped the org selector, so the path is
+    // the bare resource path and a session minted on a scoped path serves that
+    // projection of the catalog.
+    const resource = mcpResourceFromRequest(request);
     const props = await runTraced(request, propsForPrincipal(request, outcome.principal, resource));
     (ctx as ExecutionContext & { props?: McpSessionProps }).props = props;
     const forwarded = withOrgWriteAccess(

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

@@ -37,6 +37,8 @@ import {
   unauthorized,
   unavailable,
   McpAuthProvider,
+  mcpResourceFromRequest,
+  scopedMcpRoutePaths,
   type AuthOutcome,
   type McpDiscoveryRoute,
   type Principal,
@@ -48,7 +50,6 @@ import { CoreSharedServices } from "../auth/workos";
 import {
   bearerChallengeFor,
   mcpOrganizationFromRequest,
-  mcpResourceFromRequest,
   protectedResourceMetadataUrlFor,
   PROTECTED_RESOURCE_METADATA_PATH,
   McpAuth,
@@ -66,13 +67,6 @@ import {
 } from "./oauth-metadata";
 
 const AUTHORIZATION_SERVER_METADATA_PATH = "/.well-known/oauth-authorization-server";
-// One metadata doc per MCP sub-resource kind; the doc's `resource` mirrors the
-// path the client dialed (RFC 9728 same-origin check).
-const SCOPED_PROTECTED_RESOURCE_METADATA_PATHS = [
-  `${PROTECTED_RESOURCE_METADATA_PATH}/toolkits/:slug`,
-  `${PROTECTED_RESOURCE_METADATA_PATH}/integrations/:slugs`,
-  `${PROTECTED_RESOURCE_METADATA_PATH}/tools/:toolId`,
-] as const;
 
 const NO_ORGANIZATION_MESSAGE = "No organization in session — log in via the web app first";
 
@@ -140,9 +134,11 @@ export const cloudMcpAuthProviderLayer: Layer.Layer<
           mcpResourceFromRequest(request),
         ),
       );
+    // One metadata doc per resource; its `resource` mirrors the path the client
+    // dialed (RFC 9728 same-origin check).
     const discoveryRoutes: ReadonlyArray<McpDiscoveryRoute> = [
       { path: PROTECTED_RESOURCE_METADATA_PATH, handler: protectedResourceMetadata },
-      ...SCOPED_PROTECTED_RESOURCE_METADATA_PATHS.map((path) => ({
+      ...scopedMcpRoutePaths(PROTECTED_RESOURCE_METADATA_PATH).map((path) => ({
         path,
         handler: protectedResourceMetadata,
       })),

apps/cloud/src/mcp/auth.ts

@@ -14,8 +14,8 @@ import { Context, Effect, Layer, Predicate } from "effect";
 
 import {
   defaultMcpResource,
-  mcpResourceFromPathname,
   mcpResourcePath,
+  OAUTH_PROTECTED_RESOURCE_PREFIX,
   type McpResource,
 } from "@executor-js/host-mcp";
 
@@ -75,20 +75,6 @@ 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 a request names, read off its (already org-stripped) path.
- * Both the transport path (`/mcp/toolkits/<slug>`) and its metadata doc
- * (`/.well-known/oauth-protected-resource/mcp/toolkits/<slug>`) resolve to the
- * same resource. Defaults to the whole catalog for anything else.
- */
-export const mcpResourceFromRequest = (request: Request): McpResource => {
-  const pathname = new URL(request.url).pathname;
-  const bare = pathname.startsWith(PRM_PREFIX) ? pathname.slice(PRM_PREFIX.length) : pathname;
-  return mcpResourceFromPathname(bare) ?? defaultMcpResource;
-};
-
-const PRM_PREFIX = "/.well-known/oauth-protected-resource";
-
 /** 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. */
@@ -106,8 +92,8 @@ export const protectedResourceMetadataUrlFor = (
   resource: McpResource = defaultMcpResource,
 ): string =>
   organizationSelector
-    ? `${RESOURCE_ORIGIN}${PRM_PREFIX}/${organizationSelector}${mcpResourcePath(resource)}`
-    : `${RESOURCE_ORIGIN}${PRM_PREFIX}${mcpResourcePath(resource)}`;
+    ? `${RESOURCE_ORIGIN}${OAUTH_PROTECTED_RESOURCE_PREFIX}/${organizationSelector}${mcpResourcePath(resource)}`
+    : `${RESOURCE_ORIGIN}${OAUTH_PROTECTED_RESOURCE_PREFIX}${mcpResourcePath(resource)}`;
 
 type McpUnauthorizedReason = "missing_bearer" | "invalid_token";
 

apps/cloud/src/mcp/mount.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, it } from "@effect/vitest";
 
-import { mcpResourceFromRequest, protectedResourceMetadataUrlFor, resourceUrlFor } from "./auth";
+import { mcpResourceFromRequest } from "@executor-js/host-mcp";
+
+import { protectedResourceMetadataUrlFor, resourceUrlFor } from "./auth";
 import { classifyMcpPath, prepareMcpOrgScope } from "./mount";
 
 describe("cloud MCP scoped route normalization", () => {

apps/host-cloudflare/src/mcp/agent-handler.ts

@@ -3,8 +3,7 @@ import { Effect, Predicate } from "effect";
 import {
   McpAuthProvider,
   jsonRpcErrorBody,
-  defaultMcpResource,
-  mcpResourceFromPathname,
+  mcpResourceFromRequest,
   orgWriteAccessForPrincipal,
   withOrgWriteAccess,
   type AuthOutcome,
@@ -74,12 +73,6 @@ const authenticate = (request: Request, config: CloudflareConfig) =>
     return { auth, outcome };
   }).pipe(Effect.provide(cloudflareAccessMcpAuth(config)));
 
-// The MCP resource the request targets (`worker.ts` routes every path the
-// shared grammar recognizes here), so a session minted on a scoped path serves
-// that projection of the catalog.
-const resourceFromPath = (request: Request): McpResource =>
-  mcpResourceFromPathname(new URL(request.url).pathname) ?? defaultMcpResource;
-
 const propsForPrincipal = (
   request: Request,
   principal: Principal,
@@ -153,7 +146,9 @@ export const makeCloudflareMcpAgentHandler = (config: CloudflareConfig) => {
       }
     }
 
-    const resource = resourceFromPath(request);
+    // `worker.ts` routes every path the shared grammar recognizes here, so a
+    // session minted on a scoped path serves that projection of the catalog.
+    const resource = mcpResourceFromRequest(request);
     const props = await Effect.runPromise(propsForPrincipal(request, outcome.principal, resource));
     (ctx as ExecutionContext & { props?: McpSessionProps }).props = props;
     const forwarded = withOrgWriteAccess(

apps/host-cloudflare/src/mcp/auth.ts

@@ -2,38 +2,23 @@ import { Effect, Layer } from "effect";
 
 import {
   authenticated,
-  defaultMcpResource,
   McpAuthProvider,
-  mcpResourceFromPathname,
+  mcpResourceFromRequest,
   mcpResourcePath,
+  OAUTH_PROTECTED_RESOURCE_PREFIX,
+  scopedMcpRoutePaths,
   unauthorized,
   type McpDiscoveryRoute,
-  type McpResource,
 } from "@executor-js/host-mcp";
 
 import { makeAccessVerifier } from "../auth/cloudflare-access";
 import type { CloudflareConfig } from "../config";
 
-const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
-const MCP_PROTECTED_RESOURCE_METADATA_PATH = `${PROTECTED_RESOURCE_METADATA_PATH}/mcp`;
-const SCOPED_PROTECTED_RESOURCE_METADATA_PATHS = [
-  `${MCP_PROTECTED_RESOURCE_METADATA_PATH}/toolkits/:slug`,
-  `${MCP_PROTECTED_RESOURCE_METADATA_PATH}/integrations/:slugs`,
-  `${MCP_PROTECTED_RESOURCE_METADATA_PATH}/tools/:toolId`,
-] as const;
-
-// The resource a request names, whether it dialed the transport path or its
-// metadata doc. The grammar is the shared one from host-mcp.
-const resourceForRequest = (request: Request): McpResource => {
-  const pathname = new URL(request.url).pathname;
-  const bare = pathname.startsWith(PROTECTED_RESOURCE_METADATA_PATH)
-    ? pathname.slice(PROTECTED_RESOURCE_METADATA_PATH.length)
-    : pathname;
-  return mcpResourceFromPathname(bare) ?? defaultMcpResource;
-};
+const PROTECTED_RESOURCE_METADATA_PATH = OAUTH_PROTECTED_RESOURCE_PREFIX;
+const MCP_PROTECTED_RESOURCE_METADATA_PATH = `${PROTECTED_RESOURCE_METADATA_PATH}/mcp` as const;
 
 const resourcePathForRequest = (request: Request): string =>
-  mcpResourcePath(resourceForRequest(request));
+  mcpResourcePath(mcpResourceFromRequest(request));
 
 const metadataPathForRequest = (request: Request): string =>
   `${PROTECTED_RESOURCE_METADATA_PATH}${resourcePathForRequest(request)}`;
@@ -76,7 +61,7 @@ export const cloudflareAccessMcpAuth = (config: CloudflareConfig): Layer.Layer<M
       path: MCP_PROTECTED_RESOURCE_METADATA_PATH,
       handler: (request) => Effect.succeed(protectedResourceMetadataResponse(request)),
     },
-    ...SCOPED_PROTECTED_RESOURCE_METADATA_PATHS.map((path) => ({
+    ...scopedMcpRoutePaths(MCP_PROTECTED_RESOURCE_METADATA_PATH).map((path) => ({
       path,
       handler: (request: Request) => Effect.succeed(protectedResourceMetadataResponse(request)),
     })),

apps/host-selfhost/src/mcp/auth.ts

@@ -5,12 +5,13 @@ import { IdentityProvider, isPlatformPrincipal } from "@executor-js/api/server";
 import {
   authenticated,
   McpAuthProvider,
-  mcpResourceFromPathname,
+  mcpResourceFromRequest,
   mcpResourcePath,
+  OAUTH_PROTECTED_RESOURCE_PREFIX,
+  scopedMcpRoutePaths,
   unauthorized,
   type AuthOutcome,
   type McpDiscoveryRoute,
-  type McpResource,
   type Principal,
 } from "@executor-js/host-mcp";
 
@@ -57,14 +58,9 @@ import { MCP_ORIGINAL_PATH_HEADER, mcpResourcePathFromOriginalPath } from "./org
 // stay on the Better Auth handler mounted at /api/auth — NOT in this seam.
 // ---------------------------------------------------------------------------
 
-const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
-// One metadata doc per scoped MCP sub-resource kind (the default doc is the
-// bare well-known path itself, Better Auth's convention).
-const SCOPED_PROTECTED_RESOURCE_METADATA_PATHS = [
-  `${PROTECTED_RESOURCE_METADATA_PATH}/mcp/toolkits/:slug`,
-  `${PROTECTED_RESOURCE_METADATA_PATH}/mcp/integrations/:slugs`,
-  `${PROTECTED_RESOURCE_METADATA_PATH}/mcp/tools/:toolId`,
-] as const;
+// The default doc is the bare well-known path itself (Better Auth's
+// convention); scoped docs sit under `<prefix>/mcp/...`.
+const PROTECTED_RESOURCE_METADATA_PATH = OAUTH_PROTECTED_RESOURCE_PREFIX;
 const AUTHORIZATION_SERVER_METADATA_PATH = "/.well-known/oauth-authorization-server";
 
 const parseRoles = (role: string | null | undefined): ReadonlyArray<string> =>
@@ -99,26 +95,11 @@ const originalOrgScopedPathFor = (request: Request): string | null => {
   return header ? mcpResourcePathFromOriginalPath(header) : null;
 };
 
-/**
- * The scoped MCP resource a bare request names, read off its own path (the
- * transport path or its metadata doc), or `null` for the default endpoint.
- * The grammar is the shared one from host-mcp.
- */
-const scopedResourceFor = (request: Request): McpResource | null => {
-  const pathname = new URL(request.url).pathname;
-  const bare = pathname.startsWith(PROTECTED_RESOURCE_METADATA_PATH)
-    ? pathname.slice(PROTECTED_RESOURCE_METADATA_PATH.length)
-    : pathname;
-  const resource = mcpResourceFromPathname(bare);
-  return resource === null || resource.kind === "default" ? null : resource;
-};
+const isScopedRequest = (request: Request): boolean =>
+  mcpResourceFromRequest(request).kind !== "default";
 
-const mcpResourcePathFor = (request: Request): string => {
-  const orgScoped = originalOrgScopedPathFor(request);
-  if (orgScoped) return orgScoped;
-  const scoped = scopedResourceFor(request);
-  return scoped ? mcpResourcePath(scoped) : "/mcp";
-};
+const mcpResourcePathFor = (request: Request): string =>
+  originalOrgScopedPathFor(request) ?? mcpResourcePath(mcpResourceFromRequest(request));
 
 /**
  * Absolute protected-resource metadata URL for the 401 challenge. Derive the
@@ -131,9 +112,8 @@ const resourceMetadataUrlFor = (baseURL: string | undefined, request: Request):
   const origin = baseURL && baseURL.length > 0 ? baseURL : new URL(request.url).origin;
   const orgScoped = originalOrgScopedPathFor(request);
   if (orgScoped) return `${origin}${PROTECTED_RESOURCE_METADATA_PATH}${orgScoped}`;
-  const scoped = scopedResourceFor(request);
-  return scoped
-    ? `${origin}${PROTECTED_RESOURCE_METADATA_PATH}${mcpResourcePath(scoped)}`
+  return isScopedRequest(request)
+    ? `${origin}${PROTECTED_RESOURCE_METADATA_PATH}${mcpResourcePathFor(request)}`
     : `${origin}${PROTECTED_RESOURCE_METADATA_PATH}`;
 };
 
@@ -150,7 +130,7 @@ const scopedProtectedResourceMetadata = (
   response: Response,
   baseURL: string | undefined,
 ): Effect.Effect<Response> => {
-  if (scopedResourceFor(request) === null) return Effect.succeed(response);
+  if (!isScopedRequest(request)) return Effect.succeed(response);
   return Effect.promise(async () => {
     const body = (await response.json()) as Record<string, unknown>;
     const headers = new Headers(response.headers);
@@ -189,7 +169,7 @@ export const selfHostMcpAuth: Layer.Layer<McpAuthProvider, never, BetterAuth | I
         );
       const discoveryRoutes: ReadonlyArray<McpDiscoveryRoute> = [
         { path: PROTECTED_RESOURCE_METADATA_PATH, handler: protectedResourceMetadata },
-        ...SCOPED_PROTECTED_RESOURCE_METADATA_PATHS.map((path) => ({
+        ...scopedMcpRoutePaths(`${PROTECTED_RESOURCE_METADATA_PATH}/mcp`).map((path) => ({
           path,
           handler: protectedResourceMetadata,
         })),