Serve every MCP endpoint as a projection of one executor

Author: RhysSullivan

.changeset/mcp-projections.md

@@ -0,0 +1,9 @@
+---
+"executor": minor
+"@executor-js/sdk": minor
+"@executor-js/plugin-toolkits": minor
+---
+
+Serve every MCP endpoint as a projection of one executor. A toolkit endpoint (`/mcp/toolkits/<slug>`) now narrows the same executor the default `/mcp` endpoint uses instead of building a separate one, so workspace `require_approval` and `block` policies apply on toolkit endpoints too. Two new scoped endpoints share the same path: `/mcp/integrations/<slug>[,<slug>…]` exposes every tool of the named integrations, and `/mcp/tools/<tool id>` exposes one tool.
+
+For plugin authors, `toolPolicyProvider` is replaced by `toolProjections`, and `executor.project(name)` returns a narrowed view over the same database.

apps/cloud/executor.config.ts

@@ -47,11 +47,10 @@ interface CloudPluginDeps {
    *  bypass the real WorkOS API. Production leaves this undefined and
    *  falls back to the credential-driven default. */
   readonly workosVaultClient?: WorkOSVaultClient;
-  readonly activeToolkitSlug?: string;
 }
 
 export default defineExecutorConfig({
-  plugins: ({ workosCredentials, workosVaultClient, activeToolkitSlug }: CloudPluginDeps = {}) =>
+  plugins: ({ workosCredentials, workosVaultClient }: CloudPluginDeps = {}) =>
     [
       openApiHttpPlugin({
         presets: [...googleCatalog, ...microsoftCatalog],
@@ -61,7 +60,7 @@ export default defineExecutorConfig({
         dangerouslyAllowStdioMCP: false,
       }),
       graphqlHttpPlugin(),
-      toolkitsPlugin({ activeToolkitSlug }),
+      toolkitsPlugin(),
       workosVaultPlugin({
         credentials: workosCredentials ?? { apiKey: "", clientId: "" },
         ...(workosVaultClient ? { client: workosVaultClient } : {}),

apps/cloud/src/engine/execution-stack.ts

@@ -63,21 +63,18 @@ const cloudPluginFactory = executorConfig.plugins as (deps: {
     readonly clientId: string;
     readonly apiUrl?: string;
   };
-  readonly activeToolkitSlug?: string;
 }) => readonly AnyPlugin[];
 
 // Fresh plugin instances per request, carrying the Worker env's WorkOS Vault
 // credentials. Matches the old `createScopedExecutor`'s `orgPlugins()`.
 export const CloudPluginsProvider: Layer.Layer<PluginsProvider> = Layer.succeed(PluginsProvider)({
-  plugins: (context) =>
+  plugins: () =>
     cloudPluginFactory({
       workosCredentials: {
         apiKey: env.WORKOS_API_KEY,
         clientId: env.WORKOS_CLIENT_ID,
         apiUrl: env.WORKOS_API_URL,
       },
-      activeToolkitSlug:
-        context?.mcpResource?.kind === "toolkit" ? context.mcpResource.slug : undefined,
     }),
 });
 

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

@@ -5,6 +5,7 @@ import {
   McpAuthProvider,
   jsonRpcErrorBody,
   defaultMcpResource,
+  mcpResourceFromPathname,
   orgWriteAccessForPrincipal,
   withOrgWriteAccess,
   UNAVAILABLE_RETRY_AFTER_SECONDS,
@@ -155,17 +156,13 @@ const runTraced = <A>(request: Request, program: Effect.Effect<A>): Promise<A> =
   );
 };
 
-// The MCP resource the request targets. `server.ts` routes both the bare `/mcp`
-// and `/mcp/toolkits/<slug>` to this handler (`prepareMcpOrgScope` strips the org
-// selector but keeps the toolkit segment), so a session minted on a toolkit path
-// scopes its tool catalog to that toolkit.
-const resourceFromPath = (request: Request): McpResource => {
-  const segments = new URL(request.url).pathname.split("/").filter((s) => s.length > 0);
-  if (segments.length === 3 && segments[0] === "mcp" && segments[1] === "toolkits" && segments[2]) {
-    return { kind: "toolkit", slug: segments[2] };
-  }
-  return defaultMcpResource;
-};
+// 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,
@@ -204,12 +201,12 @@ export const makeCloudMcpAgentHandler = () => {
   // The agents SDK builds an exact-match `URLPattern` from the path handed to
   // `serve` (see `createStreamingHttpHandler` in `agents/dist/mcp/index.js`) —
   // a single `/mcp` handler never matches `/mcp/toolkits/<slug>` and falls
-  // through to its own internal 404. A second `serve` mounted on the
-  // parameterized path picks it up (`URLPattern` supports `:slug` segments);
-  // the auth/ownership/props logic above is unchanged and shared, only the
-  // final dispatch target differs.
+  // through to its own internal 404. A second `serve` mounted on a two-segment
+  // wildcard picks up every scoped sub-resource (`URLPattern` supports `:kind`
+  // segments); the auth/ownership/props logic above is unchanged and shared,
+  // only the final dispatch target differs.
   const serve = McpSessionDOSqlite.serve("/mcp", serveOptions);
-  const serveToolkit = McpSessionDOSqlite.serve("/mcp/toolkits/:slug", serveOptions);
+  const serveScoped = McpSessionDOSqlite.serve("/mcp/:kind/:value", serveOptions);
 
   const ALLOWED_METHODS = new Set(["GET", "POST", "DELETE", "OPTIONS"]);
 
@@ -304,7 +301,7 @@ export const makeCloudMcpAgentHandler = () => {
       ),
       orgWriteAccessForPrincipal(outcome.principal),
     );
-    const target = resource.kind === "toolkit" ? serveToolkit : serve;
+    const target = resource.kind === "default" ? serve : serveScoped;
     let response: Response;
     // oxlint-disable-next-line executor/no-try-catch-or-throw -- adapter boundary: the agents SDK aborts the isolate (throws) instead of returning a response for a condemned session
     try {

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

@@ -48,9 +48,9 @@ import { CoreSharedServices } from "../auth/workos";
 import {
   bearerChallengeFor,
   mcpOrganizationFromRequest,
+  mcpResourceFromRequest,
   protectedResourceMetadataUrlFor,
   PROTECTED_RESOURCE_METADATA_PATH,
-  toolkitSlugFromRequest,
   McpAuth,
   McpAuthLive,
   McpOrganizationAuth,
@@ -66,7 +66,13 @@ import {
 } from "./oauth-metadata";
 
 const AUTHORIZATION_SERVER_METADATA_PATH = "/.well-known/oauth-authorization-server";
-const TOOLKIT_PROTECTED_RESOURCE_METADATA_PATH = `${PROTECTED_RESOURCE_METADATA_PATH}/toolkits/:toolkitSlug`;
+// 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";
 
@@ -125,29 +131,21 @@ export const cloudMcpAuthProviderLayer: Layer.Layer<
     const auth = yield* McpAuth;
     const orgAuth = yield* McpOrganizationAuth;
 
+    // The bare paths are the only ones mounted; `prepareMcpOrgScope` rewrites an
+    // org-scoped discovery doc onto them and pins the org in the header we read.
+    const protectedResourceMetadata = (request: Request) =>
+      Effect.succeed(
+        protectedResourceMetadataResponse(
+          mcpOrganizationFromRequest(request),
+          mcpResourceFromRequest(request),
+        ),
+      );
     const discoveryRoutes: ReadonlyArray<McpDiscoveryRoute> = [
-      {
-        path: PROTECTED_RESOURCE_METADATA_PATH,
-        // The bare path is the only one mounted; `prepareMcpOrgScope` rewrites an
-        // org-scoped discovery doc onto it and pins the org in the header we read.
-        handler: (request) =>
-          Effect.succeed(
-            protectedResourceMetadataResponse(
-              mcpOrganizationFromRequest(request),
-              toolkitSlugFromRequest(request),
-            ),
-          ),
-      },
-      {
-        path: TOOLKIT_PROTECTED_RESOURCE_METADATA_PATH,
-        handler: (request) =>
-          Effect.succeed(
-            protectedResourceMetadataResponse(
-              mcpOrganizationFromRequest(request),
-              toolkitSlugFromRequest(request),
-            ),
-          ),
-      },
+      { path: PROTECTED_RESOURCE_METADATA_PATH, handler: protectedResourceMetadata },
+      ...SCOPED_PROTECTED_RESOURCE_METADATA_PATHS.map((path) => ({
+        path,
+        handler: protectedResourceMetadata,
+      })),
       {
         path: AUTHORIZATION_SERVER_METADATA_PATH,
         handler: () => authorizationServerMetadataResponse,
@@ -157,7 +155,7 @@ export const cloudMcpAuthProviderLayer: Layer.Layer<
     const resourceMetadataUrl = (request: Request): string =>
       protectedResourceMetadataUrlFor(
         mcpOrganizationFromRequest(request),
-        toolkitSlugFromRequest(request),
+        mcpResourceFromRequest(request),
       );
 
     /**
@@ -252,7 +250,7 @@ export const cloudMcpAuthProviderLayer: Layer.Layer<
             bearerChallengeFor(
               result,
               mcpOrganizationFromRequest(request),
-              toolkitSlugFromRequest(request),
+              mcpResourceFromRequest(request),
             ),
           ),
         ),

apps/cloud/src/mcp/auth.ts

@@ -12,6 +12,13 @@
 import { env } from "cloudflare:workers";
 import { Context, Effect, Layer, Predicate } from "effect";
 
+import {
+  defaultMcpResource,
+  mcpResourceFromPathname,
+  mcpResourcePath,
+  type McpResource,
+} from "@executor-js/host-mcp";
+
 import { createCachedRemoteJWKSet } from "../auth/jwks-cache";
 import { ApiKeyService } from "../auth/api-keys";
 import { BEARER_PREFIX } from "../auth/bearer";
@@ -50,7 +57,6 @@ const MCP_PATH = "/mcp";
 export const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource/mcp";
 export const PROTECTED_RESOURCE_METADATA_URL = `${RESOURCE_ORIGIN}${PROTECTED_RESOURCE_METADATA_PATH}`;
 export const RESOURCE_URL = `${RESOURCE_ORIGIN}${MCP_PATH}`;
-const TOOLKIT_SEGMENT = "/toolkits/";
 
 // ---------------------------------------------------------------------------
 // Org-scoped MCP (the URL pins an org: `/org_xxx/mcp`)
@@ -69,39 +75,39 @@ export const MCP_ORGANIZATION_HEADER = "x-executor-mcp-organization";
 export const mcpOrganizationFromRequest = (request: Request): string | null =>
   request.headers.get(MCP_ORGANIZATION_HEADER);
 
-/** The toolkit slug selected by `/mcp/toolkits/:slug` or its metadata doc. */
-export const toolkitSlugFromRequest = (request: Request): string | null => {
+/**
+ * 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 index = pathname.indexOf(TOOLKIT_SEGMENT);
-  if (index < 0) return null;
-  const slug = pathname.slice(index + TOOLKIT_SEGMENT.length).split("/", 1)[0];
-  return slug && slug.length > 0 ? slug : null;
+  const bare = pathname.startsWith(PRM_PREFIX) ? pathname.slice(PRM_PREFIX.length) : pathname;
+  return mcpResourceFromPathname(bare) ?? defaultMcpResource;
 };
 
-const toolkitMcpPath = (toolkitSlug: string | null): string =>
-  toolkitSlug ? `${MCP_PATH}/toolkits/${toolkitSlug}` : MCP_PATH;
+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. */
 export const resourceUrlFor = (
   organizationSelector: string | null,
-  toolkitSlug: string | null = null,
+  resource: McpResource = defaultMcpResource,
 ): string =>
   organizationSelector
-    ? `${RESOURCE_ORIGIN}/${organizationSelector}${toolkitMcpPath(toolkitSlug)}`
-    : `${RESOURCE_ORIGIN}${toolkitMcpPath(toolkitSlug)}`;
+    ? `${RESOURCE_ORIGIN}/${organizationSelector}${mcpResourcePath(resource)}`
+    : `${RESOURCE_ORIGIN}${mcpResourcePath(resource)}`;
 
 /** The protected-resource-metadata URL for an org selector, or the bare one. */
 export const protectedResourceMetadataUrlFor = (
   organizationSelector: string | null,
-  toolkitSlug: string | null = null,
-): string => {
-  const toolkitSuffix = toolkitSlug ? `/toolkits/${toolkitSlug}` : "";
-  return organizationSelector
-    ? `${RESOURCE_ORIGIN}/.well-known/oauth-protected-resource/${organizationSelector}/mcp${toolkitSuffix}`
-    : `${PROTECTED_RESOURCE_METADATA_URL}${toolkitSuffix}`;
-};
+  resource: McpResource = defaultMcpResource,
+): string =>
+  organizationSelector
+    ? `${RESOURCE_ORIGIN}${PRM_PREFIX}/${organizationSelector}${mcpResourcePath(resource)}`
+    : `${RESOURCE_ORIGIN}${PRM_PREFIX}${mcpResourcePath(resource)}`;
 
 type McpUnauthorizedReason = "missing_bearer" | "invalid_token";
 
@@ -140,11 +146,11 @@ export const mcpUnauthorized = (
 export const bearerChallengeFor = (
   result: McpUnauthorizedResult,
   organizationId: string | null = null,
-  toolkitSlug: string | null = null,
+  resource: McpResource = defaultMcpResource,
 ): string =>
   bearerChallenge(
     { reason: result.reason, description: result.description },
-    protectedResourceMetadataUrlFor(organizationId, toolkitSlug),
+    protectedResourceMetadataUrlFor(organizationId, resource),
   );
 
 // ---------------------------------------------------------------------------

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

@@ -1,32 +1,49 @@
 import { describe, expect, it } from "@effect/vitest";
 
-import { protectedResourceMetadataUrlFor, resourceUrlFor, toolkitSlugFromRequest } from "./auth";
+import { mcpResourceFromRequest, protectedResourceMetadataUrlFor, resourceUrlFor } from "./auth";
 import { classifyMcpPath, prepareMcpOrgScope } from "./mount";
 
-describe("cloud MCP toolkit route normalization", () => {
-  it("classifies toolkit MCP and protected-resource metadata paths", () => {
+describe("cloud MCP scoped route normalization", () => {
+  it("classifies scoped MCP and protected-resource metadata paths", () => {
+    expect(classifyMcpPath("/mcp")).toEqual({
+      kind: "mcp",
+      organizationId: null,
+      resource: { kind: "default" },
+    });
     expect(classifyMcpPath("/mcp/toolkits/deploy")).toEqual({
       kind: "mcp",
       organizationId: null,
-      toolkitSlug: "deploy",
+      resource: { kind: "toolkit", slug: "deploy" },
     });
     expect(classifyMcpPath("/acme/mcp/toolkits/deploy")).toEqual({
       kind: "mcp",
       organizationId: "acme",
-      toolkitSlug: "deploy",
+      resource: { kind: "toolkit", slug: "deploy" },
+    });
+    expect(classifyMcpPath("/acme/mcp/integrations/github,linear")).toEqual({
+      kind: "mcp",
+      organizationId: "acme",
+      resource: { kind: "integrations", slugs: ["github", "linear"] },
+    });
+    expect(classifyMcpPath("/mcp/tools/github.repos.list")).toEqual({
+      kind: "mcp",
+      organizationId: null,
+      resource: { kind: "tool", toolId: "github.repos.list" },
     });
     expect(classifyMcpPath("/.well-known/oauth-protected-resource/mcp/toolkits/deploy")).toEqual({
       kind: "oauth-protected-resource",
       organizationId: null,
-      toolkitSlug: "deploy",
+      resource: { kind: "toolkit", slug: "deploy" },
     });
     expect(
       classifyMcpPath("/.well-known/oauth-protected-resource/acme/mcp/toolkits/deploy"),
     ).toEqual({
       kind: "oauth-protected-resource",
       organizationId: "acme",
-      toolkitSlug: "deploy",
+      resource: { kind: "toolkit", slug: "deploy" },
     });
+    expect(classifyMcpPath("/mcp/unknown/x")).toBeNull();
+    expect(classifyMcpPath("/mcp/toolkits")).toBeNull();
   });
 
   it("rewrites org-scoped toolkit metadata to the mounted toolkit metadata route", () => {
@@ -41,17 +58,33 @@ describe("cloud MCP toolkit route normalization", () => {
     expect(url.pathname).toBe("/.well-known/oauth-protected-resource/mcp/toolkits/deploy");
     expect(url.search).toBe("?x=1");
     expect(rewritten.headers.get("x-executor-mcp-organization")).toBe("acme");
-    expect(toolkitSlugFromRequest(rewritten)).toBe("deploy");
+    expect(mcpResourceFromRequest(rewritten)).toEqual({ kind: "toolkit", slug: "deploy" });
   });
 
-  it("builds toolkit-specific resource and metadata URLs", () => {
-    expect(resourceUrlFor(null, "deploy")).toBe("https://executor.sh/mcp/toolkits/deploy");
-    expect(resourceUrlFor("acme", "deploy")).toBe("https://executor.sh/acme/mcp/toolkits/deploy");
-    expect(protectedResourceMetadataUrlFor(null, "deploy")).toBe(
+  it("rewrites an org-scoped integrations endpoint to the bare scoped path", () => {
+    const rewritten = prepareMcpOrgScope(
+      new Request("https://executor.sh/acme/mcp/integrations/github,linear"),
+    );
+    expect(new URL(rewritten.url).pathname).toBe("/mcp/integrations/github,linear");
+    expect(rewritten.headers.get("x-executor-mcp-organization")).toBe("acme");
+    expect(mcpResourceFromRequest(rewritten)).toEqual({
+      kind: "integrations",
+      slugs: ["github", "linear"],
+    });
+  });
+
+  it("builds scoped resource and metadata URLs", () => {
+    const toolkit = { kind: "toolkit", slug: "deploy" } as const;
+    expect(resourceUrlFor(null, toolkit)).toBe("https://executor.sh/mcp/toolkits/deploy");
+    expect(resourceUrlFor("acme", toolkit)).toBe("https://executor.sh/acme/mcp/toolkits/deploy");
+    expect(protectedResourceMetadataUrlFor(null, toolkit)).toBe(
       "https://executor.sh/.well-known/oauth-protected-resource/mcp/toolkits/deploy",
     );
-    expect(protectedResourceMetadataUrlFor("acme", "deploy")).toBe(
+    expect(protectedResourceMetadataUrlFor("acme", toolkit)).toBe(
       "https://executor.sh/.well-known/oauth-protected-resource/acme/mcp/toolkits/deploy",
     );
+    expect(resourceUrlFor("acme", { kind: "tool", toolId: "github.repos.list" })).toBe(
+      "https://executor.sh/acme/mcp/tools/github.repos.list",
+    );
   });
 });