fix(local): reuse database for toolkit MCP sessions

Author: jamieb72-afk

.changeset/toolkit-mcp-shared-database.md

@@ -0,0 +1,5 @@
+---
+"executor": patch
+---
+
+Fix toolkit MCP routes in the local daemon by reusing its owned SQLite database instead of trying to acquire the same data directory a second time.

apps/local/src/executor.ts

@@ -11,6 +11,7 @@ import {
   runSqliteDataMigrations,
   type AnyPlugin,
   type Executor,
+  type FumaDb,
 } from "@executor-js/sdk";
 import { collectTables } from "@executor-js/api/server";
 import { loadPluginsFromJsonc } from "@executor-js/config";
@@ -92,6 +93,7 @@ const loadLocalPlugins = (options: LocalExecutorOptions = {}) =>
 interface LocalExecutorBundle {
   readonly executor: Executor<LocalPlugins>;
   readonly plugins: LocalPlugins;
+  readonly db: FumaDb;
   /** Where this daemon's web UI is reachable, resolved once at boot. Surfaced
    *  so callers building user-facing links (MCP artifact deep links) use the
    *  same origin the executor itself was configured with. */
@@ -142,6 +144,42 @@ const handleOrNull = (promise: ReturnType<typeof createExecutorHandle>) =>
     ),
   );
 
+const createExecutorBundleForDb = (db: FumaDb, cwd: string, plugins: LocalPlugins) =>
+  Effect.gen(function* () {
+    const tenantId = makeTenantId(cwd);
+    // webBaseUrl is where the executor's web UI listens - same port as the
+    // daemon API since the daemon serves both. Mirrors serve.ts's port
+    // resolution so a custom $PORT flows through. EXECUTOR_WEB_BASE_URL
+    // overrides entirely for deployments where the UI is on a different host.
+    const webBaseUrl =
+      process.env.EXECUTOR_WEB_BASE_URL ?? `http://localhost:${process.env.PORT ?? "4788"}`;
+
+    const executor = yield* createExecutor({
+      tenant: Tenant.make(tenantId),
+      subject: Subject.make(LOCAL_SUBJECT),
+      db,
+      plugins,
+      onIntegrationChange: (event) =>
+        localAnalytics.record(
+          event.kind === "added" ? "integration_added" : "integration_removed",
+          { plugin_key: event.pluginKey },
+        ),
+      onElicitation: "accept-all",
+      oauthEndpointUrlPolicy: { allowHttp: true },
+      // EXPLICIT OAuth callback - the daemon serves the v2 `/api/oauth/callback`
+      // route on the same origin as the web UI. Derived from `webBaseUrl`
+      // (loopback localhost is correct + intended for the local CLI, but it
+      // is wired explicitly here rather than relying on a hidden default).
+      redirectUri: new URL("/api/oauth/callback", webBaseUrl).toString(),
+      // Built-in agent-facing tools (integrations / connections / policies).
+      coreTools: {
+        webBaseUrl,
+      },
+    });
+
+    return { executor, plugins, db, webBaseUrl };
+  });
+
 const createLocalExecutorLayer = (options: LocalExecutorOptions = {}) => {
   const storage = resolveStorage();
 
@@ -184,35 +222,8 @@ const createLocalExecutorLayer = (options: LocalExecutorOptions = {}) => {
         ),
       );
 
-      // webBaseUrl is where the executor's web UI listens — same port as the
-      // daemon API since the daemon serves both. Mirrors serve.ts's port
-      // resolution so a custom $PORT flows through. EXECUTOR_WEB_BASE_URL
-      // overrides entirely for deployments where the UI is on a different host.
-      const webBaseUrl =
-        process.env.EXECUTOR_WEB_BASE_URL ?? `http://localhost:${process.env.PORT ?? "4788"}`;
-
-      const executor = yield* createExecutor({
-        tenant: Tenant.make(tenantId),
-        subject: Subject.make(LOCAL_SUBJECT),
-        db: sqlite.db,
-        plugins,
-        onIntegrationChange: (event) =>
-          localAnalytics.record(
-            event.kind === "added" ? "integration_added" : "integration_removed",
-            { plugin_key: event.pluginKey },
-          ),
-        onElicitation: "accept-all",
-        oauthEndpointUrlPolicy: { allowHttp: true },
-        // EXPLICIT OAuth callback — the daemon serves the v2 `/api/oauth/callback`
-        // route on the same origin as the web UI. Derived from `webBaseUrl`
-        // (loopback localhost is correct + intended for the local CLI, but it
-        // is wired explicitly here rather than relying on a hidden default).
-        redirectUri: new URL("/api/oauth/callback", webBaseUrl).toString(),
-        // Built-in agent-facing tools (integrations / connections / policies).
-        coreTools: {
-          webBaseUrl,
-        },
-      });
+      const bundle = yield* createExecutorBundleForDb(sqlite.db, cwd, plugins);
+      const executor = bundle.executor;
 
       if (migration.migrated) {
         console.warn(
@@ -243,7 +254,7 @@ const createLocalExecutorLayer = (options: LocalExecutorOptions = {}) => {
           );
       }
 
-      return { executor, plugins, webBaseUrl };
+      return bundle;
     }),
   );
 };
@@ -257,6 +268,7 @@ export const createExecutorHandle = async (options: LocalExecutorOptions = {}) =
     executor: bundle.executor,
     plugins: bundle.plugins,
     webBaseUrl: bundle.webBaseUrl,
+    db: bundle.db,
     dispose: async () => {
       await Effect.runPromise(Effect.ignore(bundle.executor.close()));
       await ignorePromiseFailure("disposeRuntime", () => runtime.dispose());
@@ -310,6 +322,20 @@ const loadSharedHandle = (): Promise<ExecutorHandle> => {
 export const getExecutor = () => loadSharedHandle().then((handle) => handle.executor);
 export const getExecutorBundle = () => loadSharedHandle();
 
+export const createScopedExecutorHandle = async (options: LocalExecutorOptions = {}) => {
+  const shared = await getExecutorBundle();
+  const { cwd, plugins } = await Effect.runPromise(loadLocalPlugins(options));
+  const bundle = await Effect.runPromise(createExecutorBundleForDb(shared.db, cwd, plugins));
+
+  return {
+    executor: bundle.executor,
+    plugins: bundle.plugins,
+    dispose: async () => {
+      await Effect.runPromise(Effect.ignore(bundle.executor.close()));
+    },
+  };
+};
+
 export const disposeExecutor = async (): Promise<void> => {
   const currentHandlePromise = sharedHandlePromise;
   sharedHandlePromise = null;

apps/local/src/main.ts

@@ -8,7 +8,7 @@ import { smokeRenderArtifact } from "@executor-js/mcp-apps-shell/smoke-render";
 import { makeQuickJsExecutor } from "@executor-js/runtime-quickjs";
 import { localAnalytics } from "./analytics";
 import { makeLocalApiHandler } from "./app";
-import { createExecutorHandle, disposeExecutor, getExecutorBundle } from "./executor";
+import { createScopedExecutorHandle, disposeExecutor, getExecutorBundle } from "./executor";
 import { createMcpRequestHandler, type McpRequestHandler } from "./mcp";
 
 // ---------------------------------------------------------------------------
@@ -137,7 +137,7 @@ export const createServerHandlers = async (token: string): Promise<ServerHandler
             },
           };
         }
-        const handle = await createExecutorHandle({
+        const handle = await createScopedExecutorHandle({
           activeToolkitSlug: resource.slug,
         });
         const toolkitEngine = withExecutionAnalytics(

apps/local/src/serve.test.ts

@@ -85,6 +85,31 @@ describe("startServer static/SPA routing (unauthenticated)", () => {
 });
 
 describe("startServer startup cleanup", () => {
+  it("opens a toolkit MCP session without reacquiring database ownership", async () => {
+    server = await startServer({ port: 0, clientDir, authToken: TOKEN });
+    const response = await fetch(`http://127.0.0.1:${server.port}/mcp/toolkits/missing-toolkit`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${TOKEN}`,
+        accept: "application/json, text/event-stream",
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion: "2025-03-26",
+          capabilities: {},
+          clientInfo: { name: "local-toolkit-test", version: "1.0.0" },
+        },
+      }),
+    });
+
+    expect(response.status).toBe(200);
+    await response.body?.cancel();
+  });
+
   it("releases the owned DB when a default-handler server stops", async () => {
     server = await startServer({ port: 0, clientDir, authToken: TOKEN });
     await server.stop();