feat: unify local and hosted authorization paths

mcpjam-inspector/client/src/App.tsx

@@ -101,6 +101,7 @@ import {
   getChatboxPathTokenFromLocation,
 } from "./components/hosted/ChatboxChatPage";
 import { useHostedApiContext } from "./hooks/hosted/use-hosted-api-context";
+import { useLocalStateMigration } from "./hooks/use-local-state-migration";
 import { AppReadyProvider } from "./hooks/use-app-ready";
 import { useInspectorCommandBus } from "./hooks/use-inspector-command-bus";
 import { HOSTED_MODE, NON_PROD_LOCKDOWN } from "./lib/config";
@@ -802,6 +803,12 @@ export default function App() {
       : undefined,
   });
   useInspectorCommandBus();
+  // One-time migration from legacy localStorage state to Convex. No-op in
+  // hosted mode and after the first successful run; safe to keep in the tree.
+  useLocalStateMigration({
+    isAuthenticated,
+    organizationId: activeOrganizationId,
+  });
   const oauthDebuggerServersRef = useRef(appState.servers);
   oauthDebuggerServersRef.current = appState.servers;
   const projectServersRef = useRef(projectServers);

mcpjam-inspector/client/src/hooks/__tests__/use-server-state.hosted-oauth.test.tsx

@@ -63,6 +63,8 @@ vi.mock("@/lib/oauth/mcp-oauth", () => ({
 
 vi.mock("@/lib/apis/web/context", () => ({
   injectHostedServerMapping: vi.fn(),
+  tryGetHostedServerDisplayName: vi.fn(),
+  tryResolveProjectServer: vi.fn(() => null),
 }));
 
 vi.mock("@/lib/session-token", () => ({

mcpjam-inspector/client/src/hooks/__tests__/use-server-state.test.tsx

@@ -72,6 +72,8 @@ vi.mock("@/lib/oauth/mcp-oauth", () => ({
 
 vi.mock("@/lib/apis/web/context", () => ({
   injectHostedServerMapping: vi.fn(),
+  tryGetHostedServerDisplayName: vi.fn(),
+  tryResolveProjectServer: vi.fn(() => null),
 }));
 
 vi.mock("@/lib/session-token", () => ({

mcpjam-inspector/client/src/hooks/hosted/use-hosted-api-context.ts

@@ -1,5 +1,4 @@
 import { useLayoutEffect } from "react";
-import { HOSTED_MODE } from "@/lib/config";
 import { setHostedApiContext } from "@/lib/apis/web/context";
 
 interface UseHostedApiContextOptions {
@@ -35,11 +34,6 @@ export function useHostedApiContext({
   // between this effect's cleanup (which nulls the context) and its setup,
   // causing "Hosted server not found" errors for shared-chat OAuth servers.
   useLayoutEffect(() => {
-    if (!HOSTED_MODE) {
-      setHostedApiContext(null);
-      return;
-    }
-
     if (!enabled) {
       return;
     }

mcpjam-inspector/client/src/hooks/use-local-state-migration.ts

@@ -0,0 +1,78 @@
+import { useEffect, useRef } from "react";
+import { useMutation } from "convex/react";
+import {
+  hasMigrationCompleted,
+  runLocalStateMigration,
+} from "@/lib/local-state-migration";
+import { HOSTED_MODE } from "@/lib/config";
+import { useLogger } from "./use-logger";
+
+interface UseLocalStateMigrationOptions {
+  /** True when Convex auth has resolved (signed-in user OR guest). */
+  isAuthenticated: boolean;
+  /**
+   * Optional org id to migrate into. Undefined defers to Convex's
+   * resolveProjectOrganizationId which falls back to the actor's default
+   * organization (provisioned by `users:ensureUser`).
+   */
+  organizationId?: string;
+}
+
+/**
+ * Runs the legacy-localStorage → Convex migration exactly once per install.
+ *
+ * Skips when:
+ *   - HOSTED_MODE (hosted users never had localStorage state)
+ *   - The migration flag is already set
+ *   - Convex auth hasn't resolved
+ *   - Migration is already in flight (prevents duplicate fires across renders)
+ */
+export function useLocalStateMigration({
+  isAuthenticated,
+  organizationId,
+}: UseLocalStateMigrationOptions): void {
+  const logger = useLogger("LocalStateMigration");
+  const inFlightRef = useRef(false);
+  const doneRef = useRef(false);
+  const createProject = useMutation("projects:createProject" as any);
+
+  useEffect(() => {
+    if (HOSTED_MODE) return;
+    if (!isAuthenticated) return;
+    if (doneRef.current) return;
+    if (inFlightRef.current) return;
+    if (hasMigrationCompleted()) {
+      doneRef.current = true;
+      return;
+    }
+
+    inFlightRef.current = true;
+    runLocalStateMigration({
+      createProject: createProject as any,
+      organizationId,
+      logger,
+    })
+      .then((result) => {
+        if (result.ok) {
+          doneRef.current = true;
+          if (result.projectsMigrated > 0) {
+            logger.info("Local state migration completed", {
+              projectsMigrated: result.projectsMigrated,
+            });
+          }
+        } else {
+          logger.warn("Local state migration partially failed; will retry", {
+            errors: result.errors,
+          });
+        }
+      })
+      .catch((error) => {
+        logger.error("Local state migration threw", {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      })
+      .finally(() => {
+        inFlightRef.current = false;
+      });
+  }, [isAuthenticated, organizationId, createProject, logger]);
+}

mcpjam-inspector/client/src/hooks/use-server-state.ts

@@ -39,6 +39,7 @@ import { HOSTED_MODE } from "@/lib/config";
 import {
   injectHostedServerMapping,
   tryGetHostedServerDisplayName,
+  tryResolveProjectServer,
 } from "@/lib/apis/web/context";
 import type { OAuthTestProfile } from "@/lib/oauth/profile";
 import { authFetch } from "@/lib/session-token";
@@ -733,6 +734,18 @@ export function useServerState({
   const guardedTestConnection = useCallback(
     async (serverConfig: MCPServerConfig, serverName: string) => {
       assertClientConfigSynced();
+      // Opt into the resolver path when both projectId and a Convex serverId
+      // are populated in the API context; otherwise fall back to legacy
+      // {serverConfig, serverId} so brand-new servers (not yet synced to
+      // Convex) keep working. The 2-arg call signature is preserved when no
+      // resolver context is available so existing test mocks keep matching.
+      const resolved = tryResolveProjectServer(serverName);
+      if (resolved) {
+        return testConnection(serverConfig, resolved.serverId, {
+          projectId: resolved.projectId,
+          serverName,
+        });
+      }
       return testConnection(serverConfig, serverName);
     },
     [assertClientConfigSynced]
@@ -741,6 +754,13 @@ export function useServerState({
   const guardedReconnectServer = useCallback(
     async (serverName: string, serverConfig: MCPServerConfig) => {
       assertClientConfigSynced();
+      const resolved = tryResolveProjectServer(serverName);
+      if (resolved) {
+        return reconnectServer(resolved.serverId, serverConfig, {
+          projectId: resolved.projectId,
+          serverName,
+        });
+      }
       return reconnectServer(serverName, serverConfig);
     },
     [assertClientConfigSynced]
@@ -1683,54 +1703,45 @@ export function useServerState({
         oauthFlowProfile: formOAuthProfile,
         hasClientSecret: nextHasClientSecret,
       };
-      if (HOSTED_MODE) {
-        let syncErr: unknown;
-        try {
-          const serverId = await syncServerToConvex(
-            formData.name,
-            serverEntryForSave,
-            clientSecretSyncOptions
-          );
-          if (serverId) {
-            hostedServerId = serverId;
-            injectHostedServerMapping(formData.name, serverId);
-          }
-        } catch (err) {
-          syncErr = err;
-          logger.warn("Sync to Convex failed (pre-connection)", {
-            serverName: formData.name,
-            err,
-          });
-        }
-        // OAuth in hosted mode requires a Convex serverId to bind credentials
-        // to. Without it, prepareHostedProjectOAuthRedirect is a no-op and the
-        // local fallback can't persist tokens either (mcp-oauth.saveTokens is
-        // gated on !HOSTED_MODE), so the OAuth dance would complete without a
-        // durable credential. Fail loudly instead.
-        if (formData.useOAuth && !hostedServerId) {
-          const errorMessage =
-            syncErr instanceof Error
-              ? `Could not save the hosted server before starting OAuth: ${syncErr.message}`
-              : "Could not save the hosted server before starting OAuth. Please try again.";
-          dispatch({
-            type: "CONNECT_FAILURE",
-            name: formData.name,
-            error: errorMessage,
-          });
-          toast.error(errorMessage);
-          return;
-        }
-      } else {
-        syncServerToConvex(
+      // Both modes: await Convex sync so the returned serverId is available
+      // for OAuth binding (hosted) and for the new {projectId, serverId}
+      // request shape (local mode resolver path). Failure is non-fatal in
+      // local mode — the legacy {serverConfig, serverId: name} body still
+      // works as a fallback.
+      let syncErr: unknown;
+      try {
+        const serverId = await syncServerToConvex(
           formData.name,
           serverEntryForSave,
           clientSecretSyncOptions
-        ).catch((err) =>
-          logger.warn("Background sync to Convex failed (pre-connection)", {
-            serverName: formData.name,
-            err,
-          })
         );
+        if (serverId) {
+          hostedServerId = serverId;
+          injectHostedServerMapping(formData.name, serverId);
+        }
+      } catch (err) {
+        syncErr = err;
+        logger.warn("Sync to Convex failed (pre-connection)", {
+          serverName: formData.name,
+          err,
+        });
+      }
+      if (HOSTED_MODE && formData.useOAuth && !hostedServerId) {
+        // OAuth in hosted mode requires a Convex serverId to bind credentials
+        // to; without it the OAuth dance would complete without a durable
+        // credential. Local-mode OAuth follows the same constraint post-
+        // unification but the legacy localStorage fallback still catches it.
+        const errorMessage =
+          syncErr instanceof Error
+            ? `Could not save the hosted server before starting OAuth: ${syncErr.message}`
+            : "Could not save the hosted server before starting OAuth. Please try again.";
+        dispatch({
+          type: "CONNECT_FAILURE",
+          name: formData.name,
+          error: errorMessage,
+        });
+        toast.error(errorMessage);
+        return;
       }
       if (!isAuthenticated) {
         const project = appState.projects[appState.activeProjectId];