Mcpjam hosted multi tenancy

mcpjam-inspector/HOSTED_MCPJAM.md

@@ -0,0 +1,17 @@
+# Goal
+
+We want to create a hosted version of MCPJam. It will be hosted via Docker on Railway. It must have everything the Desktop version has.
+
+# Current limitations
+
+Currently MCPJam was designed to be a Desktop app ran locally either through `npx`, Electron, Docker. The Hono backend has a MCPClientManager singleton. This means if we host it, everyone will be sharing the same MCPClientManager object, and we will have collisions. People will have access to other people's MCP servers and see everyone else's logs.
+
+We cannot have this singleton behavior in a hosted version. Everyone should have their own MCPClientManager in isolation.
+
+# Requirements
+
+- We want to create a mono-repo that supports both the current local desktop, but also a hosted version.
+- In hosted environment, everyone must have their own client manager in isolation.
+- Try to scale, handle what happens when there are LOTS of people connected to the server.
+- Must be deployable via Docker.
+- Changes must be as minimalistic as possible. Least amount of impact and code required as possible.

mcpjam-inspector/server/app.ts

@@ -16,7 +16,12 @@ import { MCPClientManager } from "@mcpjam/sdk";
 import { initElicitationCallback } from "./routes/mcp/elicitation.js";
 import { rpcLogBus } from "./services/rpc-log-bus.js";
 import { progressStore } from "./services/progress-store.js";
+import {
+  createClientManagerStore,
+  readSessionStoreOptionsFromEnv,
+} from "./services/client-manager-store.js";
 import { CORS_ORIGINS, HOSTED_MODE, ALLOWED_HOSTS } from "./config.js";
+import { resolveRequestSessionId } from "./middleware/client-manager-session.js";
 import path from "path";
 
 // Security imports
@@ -82,52 +87,54 @@ export function createHonoApp() {
   generateSessionToken();
   const app = new Hono();
 
-  // Create the MCPJam client manager instance and wire RPC logging to SSE bus
-  const mcpClientManager = new MCPClientManager(
-    {},
-    {
-      rpcLogger: ({ direction, message, serverId }) => {
-        rpcLogBus.publish({
-          serverId,
-          direction,
-          timestamp: new Date().toISOString(),
-          message,
-        });
-      },
-      progressHandler: ({
-        serverId,
-        progressToken,
-        progress,
-        total,
-        message,
-      }) => {
-        // Store progress for UI access using the real progressToken from the notification
-        progressStore.publish({
-          serverId,
-          progressToken,
-          progress,
-          total,
-          message,
-          timestamp: new Date().toISOString(),
-        });
-      },
-    },
-  );
+  const mcpClientManagerStore = createClientManagerStore({
+    hostedMode: HOSTED_MODE,
+    managerFactory: (sessionId) => {
+      // Create a manager and wire RPC/progress logging for each isolated session.
+      const manager = new MCPClientManager(
+        {},
+        {
+          rpcLogger: ({ direction, message, serverId }) => {
+            rpcLogBus.publish({
+              sessionId,
+              serverId,
+              direction,
+              timestamp: new Date().toISOString(),
+              message,
+            });
+          },
+          progressHandler: ({
+            serverId,
+            progressToken,
+            progress,
+            total,
+            message,
+          }) => {
+            // Store progress for UI access using the real progressToken from the notification
+            progressStore.publish({
+              sessionId,
+              serverId,
+              progressToken,
+              progress,
+              total,
+              message,
+              timestamp: new Date().toISOString(),
+            });
+          },
+        },
+      );
 
-  // Initialize elicitation callback immediately so tasks/result calls work
-  // without needing to hit the elicitation endpoints first
-  initElicitationCallback(mcpClientManager);
+      // Register callback per manager instance so task-related elicitation works.
+      initElicitationCallback(manager);
+      return manager;
+    },
+    sessionStoreOptions: readSessionStoreOptionsFromEnv(),
+  });
 
   if (process.env.DEBUG_MCP_SELECTION === "1") {
     appLogger.debug("[mcpjam][boot] DEBUG_MCP_SELECTION enabled");
   }
 
-  // Middleware to inject the client manager into context
-  app.use("*", async (c, next) => {
-    c.mcpClientManager = mcpClientManager;
-    await next();
-  });
-
   // ===== SECURITY MIDDLEWARE STACK =====
   // Order matters: headers -> origin validation -> session auth
 
@@ -142,6 +149,14 @@ export function createHonoApp() {
 
   // ===== END SECURITY MIDDLEWARE =====
 
+  // Resolve the manager only after security middleware has run.
+  app.use("*", async (c, next) => {
+    const sessionId = resolveRequestSessionId(c, HOSTED_MODE);
+    c.mcpSessionId = sessionId;
+    c.mcpClientManager = mcpClientManagerStore.getManager(sessionId);
+    await next();
+  });
+
   // Middleware - only enable HTTP request logging in dev mode or when --verbose is passed
   const enableHttpLogs =
     process.env.NODE_ENV !== "production" ||

mcpjam-inspector/server/index.ts

@@ -22,6 +22,7 @@ import {
   sessionAuthMiddleware,
   scrubTokenFromUrl,
 } from "./middleware/session-auth";
+import { resolveRequestSessionId } from "./middleware/client-manager-session";
 import { originValidationMiddleware } from "./middleware/origin-validation";
 import { securityHeadersMiddleware } from "./middleware/security-headers";
 
@@ -82,8 +83,14 @@ function logBox(content: string, title?: string) {
 // Import routes and services
 import mcpRoutes from "./routes/mcp/index";
 import appsRoutes from "./routes/apps/index";
+import { initElicitationCallback } from "./routes/mcp/elicitation";
 import { rpcLogBus } from "./services/rpc-log-bus";
+import { progressStore } from "./services/progress-store";
 import { tunnelManager } from "./services/tunnel-manager";
+import {
+  createClientManagerStore,
+  readSessionStoreOptionsFromEnv,
+} from "./services/client-manager-store";
 import {
   SERVER_PORT,
   SERVER_HOSTNAME,
@@ -218,24 +225,45 @@ if (!process.env.CONVEX_HTTP_URL) {
   );
 }
 
-// Initialize centralized MCPJam Client Manager and wire RPC logging to SSE bus
-const mcpClientManager = new MCPClientManager(
-  {},
-  {
-    rpcLogger: ({ direction, message, serverId }) => {
-      rpcLogBus.publish({
-        serverId,
-        direction,
-        timestamp: new Date().toISOString(),
-        message,
-      });
-    },
+const mcpClientManagerStore = createClientManagerStore({
+  hostedMode: HOSTED_MODE,
+  managerFactory: (sessionId) => {
+    const manager = new MCPClientManager(
+      {},
+      {
+        rpcLogger: ({ direction, message, serverId }) => {
+          rpcLogBus.publish({
+            sessionId,
+            serverId,
+            direction,
+            timestamp: new Date().toISOString(),
+            message,
+          });
+        },
+        progressHandler: ({
+          serverId,
+          progressToken,
+          progress,
+          total,
+          message,
+        }) => {
+          progressStore.publish({
+            sessionId,
+            serverId,
+            progressToken,
+            progress,
+            total,
+            message,
+            timestamp: new Date().toISOString(),
+          });
+        },
+      },
+    );
+
+    initElicitationCallback(manager);
+    return manager;
   },
-);
-// Middleware to inject client manager into context
-app.use("*", async (c, next) => {
-  c.mcpClientManager = mcpClientManager;
-  await next();
+  sessionStoreOptions: readSessionStoreOptionsFromEnv(),
 });
 
 // ===== SECURITY MIDDLEWARE STACK =====
@@ -252,6 +280,14 @@ app.use("*", sessionAuthMiddleware);
 
 // ===== END SECURITY MIDDLEWARE =====
 
+// Resolve a manager only after the security stack has run.
+app.use("*", async (c, next) => {
+  const sessionId = resolveRequestSessionId(c, HOSTED_MODE);
+  c.mcpSessionId = sessionId;
+  c.mcpClientManager = mcpClientManagerStore.getManager(sessionId);
+  await next();
+});
+
 // Middleware - only enable HTTP request logging in dev mode or when --verbose is passed
 const enableHttpLogs =
   process.env.NODE_ENV !== "production" || process.env.VERBOSE_LOGS === "true";
@@ -410,14 +446,16 @@ const server = serve({
 
 // Handle graceful shutdown
 process.on("SIGINT", async () => {
-  console.log("\n🛑 Shutting down gracefully...");
+  appLogger.info("\n🛑 Shutting down gracefully...");
+  await mcpClientManagerStore.dispose();
   await tunnelManager.closeAll();
   server.close();
   process.exit(0);
 });
 
 process.on("SIGTERM", async () => {
-  console.log("\n🛑 Shutting down gracefully...");
+  appLogger.info("\n🛑 Shutting down gracefully...");
+  await mcpClientManagerStore.dispose();
   await tunnelManager.closeAll();
   server.close();
   process.exit(0);

mcpjam-inspector/server/middleware/__tests__/client-manager-session.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { Hono } from "hono";
+import { resolveRequestSessionId } from "../client-manager-session.js";
+
+function createTestApp(hostedMode: boolean): Hono {
+  const app = new Hono();
+
+  app.use("*", async (c, next) => {
+    (c as any).resolvedSessionId = resolveRequestSessionId(c, hostedMode);
+    await next();
+  });
+
+  app.get("/api/test", (c) => {
+    return c.json({ sessionId: (c as any).resolvedSessionId ?? null });
+  });
+
+  return app;
+}
+
+describe("resolveRequestSessionId", () => {
+  it("does not create a session when hosted mode is disabled", async () => {
+    const app = createTestApp(false);
+
+    const res = await app.request("/api/test");
+    const data = await res.json();
+
+    expect(data.sessionId).toBeNull();
+    expect(res.headers.get("set-cookie")).toBeNull();
+  });
+
+  it("uses explicit session header when present", async () => {
+    const app = createTestApp(true);
+
+    const res = await app.request("/api/test", {
+      headers: { "x-mcpjam-session-id": "header-session-1" },
+    });
+    const data = await res.json();
+
+    expect(data.sessionId).toBe("header-session-1");
+    expect(res.headers.get("set-cookie")).toBeNull();
+  });
+
+  it("uses existing cookie session when present", async () => {
+    const app = createTestApp(true);
+
+    const res = await app.request("/api/test", {
+      headers: { Cookie: "mcpjam_session_id=cookie-session-1" },
+    });
+    const data = await res.json();
+
+    expect(data.sessionId).toBe("cookie-session-1");
+    expect(res.headers.get("set-cookie")).toBeNull();
+  });
+
+  it("creates a new session cookie when no session identifier exists", async () => {
+    const app = createTestApp(true);
+
+    const res = await app.request("/api/test");
+    const data = await res.json();
+    const setCookie = res.headers.get("set-cookie");
+
+    expect(data.sessionId).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    );
+    expect(setCookie).toContain(`mcpjam_session_id=${data.sessionId}`);
+    expect(setCookie).toContain("HttpOnly");
+  });
+});