lael-labs/executor

apps/cloud/src/mcp/agent-handler.ts+5−11

 import {
   McpAuthProvider,
   jsonRpcErrorBody,
-  defaultMcpResource,
+  mcpResourceFromRequest,
-  mcpResourceFromPathname,
   orgWriteAccessForPrincipal,
   withOrgWriteAccess,
   UNAVAILABLE_RETRY_AFTER_SECONDS,
   );
 };
-// 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"],
       }
     }
-    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+5−9

   unauthorized,
   unavailable,
   McpAuthProvider,
+  mcpResourceFromRequest,
+  scopedMcpRoutePaths,
   type AuthOutcome,
   type McpDiscoveryRoute,
   type Principal,
 import {
   bearerChallengeFor,
   mcpOrganizationFromRequest,
-  mcpResourceFromRequest,
   protectedResourceMetadataUrlFor,
   PROTECTED_RESOURCE_METADATA_PATH,
   McpAuth,
 } 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";
           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+3−17

 import {
   defaultMcpResource,
-  mcpResourceFromPathname,
   mcpResourcePath,
+  OAUTH_PROTECTED_RESOURCE_PREFIX,
   type McpResource,
 } from "@executor-js/host-mcp";
 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. */
   resource: McpResource = defaultMcpResource,
 ): string =>
   organizationSelector
-    ? `${RESOURCE_ORIGIN}${PRM_PREFIX}/${organizationSelector}${mcpResourcePath(resource)}`
+    ? `${RESOURCE_ORIGIN}${OAUTH_PROTECTED_RESOURCE_PREFIX}/${organizationSelector}${mcpResourcePath(resource)}`
-    : `${RESOURCE_ORIGIN}${PRM_PREFIX}${mcpResourcePath(resource)}`;
+    : `${RESOURCE_ORIGIN}${OAUTH_PROTECTED_RESOURCE_PREFIX}${mcpResourcePath(resource)}`;
 type McpUnauthorizedReason = "missing_bearer" | "invalid_token";

apps/cloud/src/mcp/mount.test.ts+3−1

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

apps/host-cloudflare/src/mcp/agent-handler.ts+4−9

 import {
   McpAuthProvider,
   jsonRpcErrorBody,
-  defaultMcpResource,
+  mcpResourceFromRequest,
-  mcpResourceFromPathname,
   orgWriteAccessForPrincipal,
   withOrgWriteAccess,
   type AuthOutcome,
     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,
       }
     }
-    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+7−22

 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 PROTECTED_RESOURCE_METADATA_PATH = OAUTH_PROTECTED_RESOURCE_PREFIX;
-const MCP_PROTECTED_RESOURCE_METADATA_PATH = `${PROTECTED_RESOURCE_METADATA_PATH}/mcp`;
+const MCP_PROTECTED_RESOURCE_METADATA_PATH = `${PROTECTED_RESOURCE_METADATA_PATH}/mcp` as const;
-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 resourcePathForRequest = (request: Request): string =>
-  mcpResourcePath(resourceForRequest(request));
+  mcpResourcePath(mcpResourceFromRequest(request));
 const metadataPathForRequest = (request: Request): string =>
   `${PROTECTED_RESOURCE_METADATA_PATH}${resourcePathForRequest(request)}`;
       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+14−34

 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";
 // stay on the Better Auth handler mounted at /api/auth — NOT in this seam.
 // ---------------------------------------------------------------------------
-const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
+// The default doc is the bare well-known path itself (Better Auth's
-// One metadata doc per scoped MCP sub-resource kind (the default doc is the
+// convention); scoped docs sit under `<prefix>/mcp/...`.
-// bare well-known path itself, Better Auth's convention).
+const PROTECTED_RESOURCE_METADATA_PATH = OAUTH_PROTECTED_RESOURCE_PREFIX;
-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;
 const AUTHORIZATION_SERVER_METADATA_PATH = "/.well-known/oauth-authorization-server";
 const parseRoles = (role: string | null | undefined): ReadonlyArray<string> =>
   return header ? mcpResourcePathFromOriginalPath(header) : null;
 };
-/**
+const isScopedRequest = (request: Request): boolean =>
- * The scoped MCP resource a bare request names, read off its own path (the
+  mcpResourceFromRequest(request).kind !== "default";
- * 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 mcpResourcePathFor = (request: Request): string => {
+const mcpResourcePathFor = (request: Request): string =>
-  const orgScoped = originalOrgScopedPathFor(request);
+  originalOrgScopedPathFor(request) ?? mcpResourcePath(mcpResourceFromRequest(request));
-  if (orgScoped) return orgScoped;
-  const scoped = scopedResourceFor(request);
-  return scoped ? mcpResourcePath(scoped) : "/mcp";
-};
 /**
  * Absolute protected-resource metadata URL for the 401 challenge. Derive the
   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 isScopedRequest(request)
-  return scoped
+    ? `${origin}${PROTECTED_RESOURCE_METADATA_PATH}${mcpResourcePathFor(request)}`
-    ? `${origin}${PROTECTED_RESOURCE_METADATA_PATH}${mcpResourcePath(scoped)}`
     : `${origin}${PROTECTED_RESOURCE_METADATA_PATH}`;
 };
   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);
         );
       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,
         })),

apps/local/src/main.ts+22−48

 import { makeLocalApiHandler } from "./app";
 import { disposeExecutor, getExecutorBundle } from "./executor";
 import { createMcpRequestHandler, type McpRequestHandler } from "./mcp";
+import type { ExecutorMcpServerConfig } from "@executor-js/host-mcp/tool-server";
 // ---------------------------------------------------------------------------
 // Local server handlers.
     // part of the shared API). Reuse the shared boot bundle so the MCP executor is
     // byte-identical to the one the API serves.
     const { executor, webBaseUrl } = await getExecutorBundle();
-    // Both engines below serve MCP endpoints, so the wrap binds the "mcp"
-    // plane structurally; a projected engine additionally marks `toolkit`
-    // (the resource's own label is user data and never recorded).
-    const engine = withExecutionAnalytics(
-      createExecutionEngine({
-        executor,
-        codeExecutor: makeQuickJsExecutor(),
-      }),
-      localAnalytics,
-      { plane: "mcp", toolkit: false },
-    );
     // The generative-UI surface, shared by every resource this daemon serves.
-    // A scoped resource is a projection of the boot executor, so `artifacts`
-    // is bound per resource below rather than hoisted with the rest.
-    //
     // Including the create-time smoke render, on the same terms as every other
     // host. This daemon is a dependency of `apps/cli`, whose build does not
     // configure `jsx`, and the renderer used to be unusable here for that
       onArtifactUsage: (action: "created" | "viewed" | "updated") =>
         localAnalytics.record(`artifact_${action}`, { via: "agent" }),
     };
+    // One config shape for every resource. The default endpoint serves the
+    // boot executor; a scoped one serves the same executor through a
+    // projection (same database handle — this process holds the data dir's
+    // exclusive lock, so a second open would contend with ourselves — same
+    // plugins, same workspace policies, narrowed to what the resource
+    // exposes). The wrap binds the "mcp" plane structurally; `toolkit` marks
+    // a projected engine (the resource's own label is user data and never
+    // recorded).
+    const configFor = (view: typeof executor, toolkit: boolean): ExecutorMcpServerConfig => ({
+      engine: withExecutionAnalytics(
+        createExecutionEngine({ executor: view, codeExecutor: makeQuickJsExecutor() }),
+        localAnalytics,
+        { plane: "mcp", toolkit },
+      ),
+      artifacts: view.artifacts,
+      connections: view.connections,
+      ...appsConfig,
+    });
     mcp = createMcpRequestHandler({
-      defaultConfig: {
+      defaultConfig: configFor(executor, false),
-        engine,
-        artifacts: executor.artifacts,
-        connections: executor.connections,
-        ...appsConfig,
-      },
       createConfigForResource: async (resource) => {
         const projection = projectionForMcpResource(resource);
-        if (projection === undefined) {
+        if (projection === undefined) return { config: configFor(executor, false) };
-          return {
-            config: {
-              engine,
-              artifacts: executor.artifacts,
-              connections: executor.connections,
-              ...appsConfig,
-            },
-          };
-        }
-        // A scoped resource is the boot executor seen through a projection:
-        // same database handle (this process holds the data dir's exclusive
-        // lock, so a second open would contend with ourselves), same plugins,
-        // same workspace policies, narrowed to what the resource exposes.
         const projected = await Effect.runPromise(executor.project(projection));
-        const projectedEngine = withExecutionAnalytics(
-          createExecutionEngine({
-            executor: projected,
-            codeExecutor: makeQuickJsExecutor(),
-          }),
-          localAnalytics,
-          { plane: "mcp", toolkit: true },
-        );
         return {
-          config: {
+          config: configFor(projected, true),
-            engine: projectedEngine,
-            artifacts: projected.artifacts,
-            connections: projected.connections,
-            ...appsConfig,
-          },
           close: () => Effect.runPromise(Effect.ignore(projected.close())),
         };
       },

packages/core/sdk/src/index.ts+0−4

 // Tool projections — a narrowed view over the catalog, layered on policies.
 export {
-  fullToolProjection,
-  isVisibleInProjection,
-  mostRestrictivePolicy,
   resolveProjectedPolicy,
-  resolveProjectionRule,
   type ToolProjection,
   type ToolProjectionRule,
 } from "./tool-projection";

packages/core/sdk/src/tool-projection.ts+3−6

   readonly excludePersonal?: boolean;
 }
-/** The projection that exposes every tool under the workspace policy alone. */
-export const fullToolProjection: ToolProjection = { visible: ["*"], rules: [] };
 const isPersonalToolId = (toolId: string): boolean => toolId.split(".")[1] === "user";
 const blockedOutsideProjection: EffectivePolicy = {
  * workspace "approve" does. When neither side has a rule both fall through to
  * the same plugin default.
  */
-export const mostRestrictivePolicy = (
+const mostRestrictivePolicy = (
   workspace: EffectivePolicy,
   overlay: EffectivePolicy,
 ): EffectivePolicy => {
 };
 /** Whether `toolId` falls inside the projection's capability boundary. */
-export const isVisibleInProjection = (projection: ToolProjection, toolId: string): boolean => {
+const isVisibleInProjection = (projection: ToolProjection, toolId: string): boolean => {
   if (projection.excludePersonal && isPersonalToolId(toolId)) return false;
   return projection.visible.some((pattern) => matchPattern(pattern, toolId));
 };
  * rule, else the plugin default. Does not consult the workspace policy; see
  * {@link resolveProjectedPolicy} for the combined answer.
  */
-export const resolveProjectionRule = (
+const resolveProjectionRule = (
   projection: ToolProjection,
   toolId: string,
   defaultRequiresApproval?: boolean,

packages/hosts/mcp/src/envelope.ts+2−6

   McpErrorReporter,
   McpSessionStore,
   mcpResourceFromPathname,
+  scopedMcpRoutePaths,
   type AuthOutcome,
   type McpDispatchResult,
   type McpResource,
 // ---------------------------------------------------------------------------
 const MCP_PATH = "/mcp";
-const SCOPED_MCP_PATHS = [
-  "/mcp/toolkits/:slug",
-  "/mcp/integrations/:slugs",
-  "/mcp/tools/:toolId",
-] as const;
 /** The methods the streamable-HTTP transport accepts on `/mcp`. */
 const ALLOWED_MCP_METHODS = new Set(["GET", "POST", "DELETE", "OPTIONS"]);
       );
     }
     yield* router.add("*", MCP_PATH, mcpRoute(defaultMcpResource));
-    for (const path of SCOPED_MCP_PATHS) {
+    for (const path of scopedMcpRoutePaths(MCP_PATH)) {
       yield* router.add("*", path, scopedMcpRoute);
     }
   }),

packages/hosts/mcp/src/index.ts+3−0

   McpErrorReporterNoop,
   defaultMcpResource,
   mcpResourceFromPathname,
+  mcpResourceFromRequest,
   mcpResourceFromSegments,
   mcpResourceKey,
   mcpResourcePath,
+  OAUTH_PROTECTED_RESOURCE_PREFIX,
+  scopedMcpRoutePaths,
   principalOwns,
   orgWriteAccessForPrincipal,
   withOrgWriteAccess,

packages/hosts/mcp/src/seams.ts+31−0

@@ -173,6 +173,37 @@ export const mcpResourceFromSegments = (segments: readonly string[]): McpResourc · 172 unmodified lines
173	export const mcpResourceFromPathname = (pathname: string): McpResource \| null =>	173	export const mcpResourceFromPathname = (pathname: string): McpResource \| null =>
174	mcpResourceFromSegments(pathname.split("/"));	174	mcpResourceFromSegments(pathname.split("/"));
175		175
		176	/** The RFC 9728 well-known prefix every host mounts its resource metadata under. */
		177	export const OAUTH_PROTECTED_RESOURCE_PREFIX = "/.well-known/oauth-protected-resource";
		178
		179	/**
		180	* The resource a request names, whether it dialed the transport path or that
		181	* path's protected-resource metadata document. Anything the grammar does not
		182	* recognize (a host's bare metadata doc, an unrelated path) is the default.
		183	* Hosts that add a leading org selector strip it before the request gets here.
		184	*/
		185	export const mcpResourceFromRequest = (request: Request): McpResource => {
		186	const pathname = new URL(request.url).pathname;
		187	const bare = pathname.startsWith(OAUTH_PROTECTED_RESOURCE_PREFIX)
		188	? pathname.slice(OAUTH_PROTECTED_RESOURCE_PREFIX.length)
		189	: pathname;
		190	return mcpResourceFromPathname(bare) ?? defaultMcpResource;
		191	};
		192
		193	const SCOPED_MCP_ROUTE_SUFFIXES = [
		194	`/${TOOLKITS_SEGMENT}/:slug`,
		195	`/${INTEGRATIONS_SEGMENT}/:slugs`,
		196	`/${TOOLS_SEGMENT}/:toolId`,
		197	] as const;
		198
		199	/**
		200	* Router patterns for the scoped sub-resources under `prefix` (a path ending
		201	* in `/mcp`): the transport routes for the envelope, the metadata-doc routes
		202	* for a host's discovery seam. One list, so a new resource kind is one edit.
		203	*/
		204	export const scopedMcpRoutePaths = (prefix: `/${string}`): readonly `/${string}`[] =>
		205	SCOPED_MCP_ROUTE_SUFFIXES.map((suffix) => `${prefix}${suffix}` as const);
		206
176	/**	207	/**
177	* The bare pathname that names `resource`: the inverse of	208	* The bare pathname that names `resource`: the inverse of
178	* {@link mcpResourceFromPathname}. Hosts prefix it with their org selector or	209	* {@link mcpResourceFromPathname}. Hosts prefix it with their org selector or