@enfyra/mcp-server 0.0.43 → 0.0.45

package/README.md

@@ -17,9 +17,9 @@ From your **Enfyra project root**:
 npx @enfyra/mcp-server config
 ```
 
-- **Interactive (default in a terminal):** first asks **where** to write config with an arrow-key selector — Claude Code, Cursor, Codex, or all — unless you already passed target flags. Then prompts for `ENFYRA_API_URL`, `ENFYRA_EMAIL`, and `ENFYRA_PASSWORD` when missing. Press **Enter** to accept bracketed defaults from env or existing `enfyra` config. Password **Enter** keeps the current saved password when updating.
+- **Interactive (default in a terminal):** first asks **where** to write config with an arrow-key selector — Claude Code, Cursor, Codex, or all — unless you already passed target flags. Then prompts for `ENFYRA_API_URL` and `ENFYRA_API_TOKEN` when missing. Press **Enter** to accept bracketed defaults from env or existing `enfyra` config.
 - **Re-run anytime** to update the same files; other entries under `mcpServers` are preserved.
-- **Non-interactive** (CI / scripts): `npx @enfyra/mcp-server config --yes` plus optional `-a` / `-e` / `-p` and/or env vars.
+- **Non-interactive** (CI / scripts): `npx @enfyra/mcp-server config --yes` plus optional `-a` / `-t` and/or env vars.
 - **One host only:** `--claude-code` / `--claude` / `--claude-only` → `./.mcp.json`. `--cursor` / `--cursor-only` → `./.cursor/mcp.json`. `--codex` / `--codex-only` → `./.codex/config.toml`. Pass multiple target flags to write each selected host.
 - **Reconfigure:** `npx @enfyra/mcp-server config --reconfig` prompts for the target host again, uses existing project values as defaults, and replaces the old project `enfyra` entry for that host.
 - **Global/user config:** add `--global` only when you intentionally want the selected host config under your home directory instead of this project.
@@ -57,8 +57,7 @@ Non-interactive:
 ```bash
 npx @enfyra/mcp-server config --codex --yes \
   -a http://localhost:3000/api \
-  -e your-email@example.com \
-  -p your-password
+  -t efy_pat_your-token
 ```
 
 The generated TOML section is:
@@ -70,8 +69,7 @@ args = ["-y", "@enfyra/mcp-server"]
 
 [mcp_servers.enfyra.env]
 ENFYRA_API_URL = "http://localhost:3000/api"
-ENFYRA_EMAIL = "your-email@example.com"
-ENFYRA_PASSWORD = "your-password"
+ENFYRA_API_TOKEN = "efy_pat_your-token"
 ```
 
 The config writer replaces only `[mcp_servers.enfyra]` and `[mcp_servers.enfyra.env]`; other Codex config and other MCP servers are preserved. Open this folder in a new Codex session after updating `./.codex/config.toml`. Use `--global --codex` only when you intentionally want `~/.codex/config.toml`.
@@ -103,22 +101,19 @@ Use the CLI (recommended). **User** and **local** configs are stored in **`~/.cl
 # User scope — available in all projects (options before server name per Claude Code docs)
 claude mcp add --transport stdio --scope user \
   --env ENFYRA_API_URL=http://localhost:3000/api \
-  --env ENFYRA_EMAIL=your-email@example.com \
-  --env ENFYRA_PASSWORD=your-password \
+  --env ENFYRA_API_TOKEN=efy_pat_your-token \
   enfyra -- npx -y @enfyra/mcp-server
 
 # Local scope (default) — only when this repo is cwd; still stored in ~/.claude.json under project path
 claude mcp add --transport stdio \
   --env ENFYRA_API_URL=http://localhost:3000/api \
-  --env ENFYRA_EMAIL=your-email@example.com \
-  --env ENFYRA_PASSWORD=your-password \
+  --env ENFYRA_API_TOKEN=efy_pat_your-token \
   enfyra -- npx -y @enfyra/mcp-server
 
 # Project scope — writes/updates .mcp.json at repo root (good for teams)
 claude mcp add --transport stdio --scope project \
   --env ENFYRA_API_URL=http://localhost:3000/api \
-  --env ENFYRA_EMAIL=your-email@example.com \
-  --env ENFYRA_PASSWORD=your-password \
+  --env ENFYRA_API_TOKEN=efy_pat_your-token \
   enfyra -- npx -y @enfyra/mcp-server
 ```
 
@@ -148,7 +143,7 @@ Cursor reads MCP from **`mcp.json`** in two places ([Cursor docs](https://cursor
 | **Global** | `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows) |
 | **Project** | **`.cursor/mcp.json`** inside the project (directory **`.cursor`** at repo root) |
 
-Paste the **same** `mcpServers` structure as in the [Shared](#shared-enfyra-mcp-json-and-environment) section. Cursor supports **interpolation**, e.g. `${env:ENFYRA_PASSWORD}`, `${workspaceFolder}`, for secrets and paths.
+Paste the **same** `mcpServers` structure as in the [Shared](#shared-enfyra-mcp-json-and-environment) section. Cursor supports **interpolation**, e.g. `${env:ENFYRA_API_TOKEN}`, `${workspaceFolder}`, for secrets and paths.
 
 Optional **STDIO** fields per Cursor: `type`, `command`, `args`, `env`, `envFile` — see [STDIO server configuration](https://cursor.com/docs/context/mcp).
 
@@ -172,8 +167,7 @@ Use this block in any host-specific `mcp.json` / `mcpServers` merge (adjust env
       "args": ["-y", "@enfyra/mcp-server"],
       "env": {
         "ENFYRA_API_URL": "http://localhost:3000/api",
-        "ENFYRA_EMAIL": "your-email@example.com",
-        "ENFYRA_PASSWORD": "your-password"
+        "ENFYRA_API_TOKEN": "efy_pat_your-token"
       }
     }
   }
@@ -186,8 +180,7 @@ Use this block in any host-specific `mcp.json` / `mcpServers` merge (adjust env
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `ENFYRA_API_URL` | Base for REST + GraphQL + auth through the Nuxt/app proxy | `http://localhost:3000/api` |
-| `ENFYRA_EMAIL` | Admin email | — |
-| `ENFYRA_PASSWORD` | Admin password | — |
+| `ENFYRA_API_TOKEN` | Programmatic token from eApp `/me`. MCP exchanges it through `/auth/token/exchange` for an access token. | — |
 
 ### `ENFYRA_API_URL` — use the app proxy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "description": "MCP server for Enfyra - manage your Enfyra instance via Claude Code",
   "type": "module",
   "license": "MIT",

package/src/index.mjs

@@ -20,8 +20,7 @@ Common config flags:
   --reconfig          Prompt for host and credentials again, replacing the enfyra entry
   --yes               Non-interactive
   -a, --api-url       ENFYRA_API_URL
-  -e, --email         ENFYRA_EMAIL
-  -p, --password      ENFYRA_PASSWORD
+  -t, --api-token     ENFYRA_API_TOKEN
   -h, --help          Show config help
 
 Run \`npx @enfyra/mcp-server config --help\` for full config details.

package/src/lib/auth.js

@@ -1,6 +1,6 @@
 /**
  * Authentication module for Enfyra MCP Server
- * Handles login, token refresh, and token validation
+ * Handles API-token exchange and token validation
  */
 
 // Token state
@@ -11,8 +11,7 @@ let isRefreshing = false;
 
 // Config
 let API_URL = 'http://localhost:3000/api';
-let EMAIL = '';
-let PASSWORD = '';
+let API_TOKEN = '';
 
 // Refresh buffer: refresh token 1 minute before expiry
 const TOKEN_REFRESH_BUFFER = 60000;
@@ -20,16 +19,16 @@ const TOKEN_REFRESH_BUFFER = 60000;
 /**
  * Initialize auth module with config
  */
-export function initAuth(apiUrl, email, password) {
+export function initAuth(apiUrl, apiToken = '') {
   API_URL = apiUrl;
-  EMAIL = email;
-  PASSWORD = password;
+  API_TOKEN = apiToken;
 }
 
 /**
  * Check if token needs refresh (expires within 1 minute)
  */
 export function needsRefresh() {
+  if (tokenExpiry === Infinity) return false;
   if (!tokenExpiry) return true;
   const now = Date.now();
   return now + TOKEN_REFRESH_BUFFER >= tokenExpiry;
@@ -49,54 +48,54 @@ export function getTokenExpiry() {
   return tokenExpiry;
 }
 
-/**
- * Login and get access + refresh tokens
- */
-export async function login(url, email, password) {
+export async function exchangeApiToken(url, apiToken) {
   const apiUrl = url || API_URL;
-  const authEmail = email || EMAIL;
-  const authPassword = password || PASSWORD;
+  const token = apiToken || API_TOKEN;
 
-  if (!authEmail || !authPassword) {
-    throw new Error('Email and password required');
+  if (!token) {
+    throw new Error('API token required');
   }
 
-  console.error('[Auth] Logging in...');
-  const response = await fetch(`${apiUrl}/auth/login`, {
+  console.error('[Auth] Exchanging API token...');
+  const response = await fetch(`${apiUrl}/auth/token/exchange`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ email: authEmail, password: authPassword }),
+    body: JSON.stringify({ apiToken: token }),
   });
 
   if (!response.ok) {
-    throw new Error(`Login failed: ${await response.text()}`);
+    throw new Error(`API token exchange failed: ${await response.text()}`);
   }
 
   const data = await response.json();
   accessToken = data.accessToken || data.access_token;
-  refreshToken = data.refreshToken || data.refresh_token;
-  tokenExpiry = data.expTime;
+  refreshToken = null;
+  tokenExpiry = data.expTime == null ? Infinity : data.expTime;
 
-  console.error(`[Auth] Logged in as ${authEmail}, token expires at ${new Date(tokenExpiry).toISOString()}`);
+  const expiryLabel = tokenExpiry === Infinity
+    ? 'no expiration'
+    : new Date(tokenExpiry).toISOString();
+  console.error(`[Auth] API token exchanged, access token expires at ${expiryLabel}`);
   return accessToken;
 }
 
 /**
  * Refresh access token using refresh token
  */
-export async function refreshAccessToken(url, email, password) {
+export async function refreshAccessToken(url) {
   const apiUrl = url || API_URL;
-  const authEmail = email || EMAIL;
-  const authPassword = password || PASSWORD;
 
   if (isRefreshing) {
     await new Promise(resolve => setTimeout(resolve, 500));
     return accessToken;
   }
 
+  if (API_TOKEN) {
+    return await exchangeApiToken(apiUrl, API_TOKEN);
+  }
+
   if (!refreshToken) {
-    console.error('[Auth] No refresh token, performing fresh login');
-    return await login(apiUrl, authEmail, authPassword);
+    throw new Error('ENFYRA_API_TOKEN required');
   }
 
   isRefreshing = true;
@@ -109,9 +108,8 @@ export async function refreshAccessToken(url, email, password) {
     });
 
     if (!response.ok) {
-      console.error('[Auth] Refresh failed, logging in fresh');
       refreshToken = null;
-      return await login(apiUrl, authEmail, authPassword);
+      return await exchangeApiToken(apiUrl, API_TOKEN);
     }
 
     const data = await response.json();
@@ -129,16 +127,17 @@ export async function refreshAccessToken(url, email, password) {
 /**
  * Get valid access token, refreshing if needed
  */
-export async function getValidToken(url, email, password) {
+export async function getValidToken(url) {
   const apiUrl = url || API_URL;
-  const authEmail = email || EMAIL;
-  const authPassword = password || PASSWORD;
 
   if (!accessToken || needsRefresh()) {
+    if (API_TOKEN) {
+      return await exchangeApiToken(apiUrl, API_TOKEN);
+    }
     if (refreshToken) {
-      return await refreshAccessToken(apiUrl, authEmail, authPassword);
+      return await refreshAccessToken(apiUrl);
     }
-    return await login(apiUrl, authEmail, authPassword);
+    throw new Error('ENFYRA_API_TOKEN required');
   }
   return accessToken;
 }

package/src/lib/config-local.mjs

@@ -20,8 +20,7 @@ Writes project config under the current working directory:
 
 Options:
   --api-url, -a <url>     ENFYRA_API_URL
-  --email, -e <email>     ENFYRA_EMAIL
-  --password, -p <secret> ENFYRA_PASSWORD
+  --api-token, -t <secret> ENFYRA_API_TOKEN
   --global                Write global/user config for selected hosts instead of project config
   --reconfig              Always choose target again in interactive mode and replace the old enfyra config for that target
   --yes                   Non-interactive: no prompts (CI / scripts); use CLI, env, existing file, then defaults
@@ -32,7 +31,7 @@ Options:
   Passing multiple target flags writes each selected target.
   -h, --help              Show this help
 
-Interactive mode: lets you choose Claude Code / Cursor / Codex / all if you did not pass target flags; then asks for URL / email / password
+Interactive mode: lets you choose Claude Code / Cursor / Codex / all if you did not pass target flags; then asks for URL / API token
   when missing. Existing project config is used as defaults. Re-run to update.
 
 Examples:
@@ -42,17 +41,16 @@ Examples:
   npx @enfyra/mcp-server config --codex --yes
   npx @enfyra/mcp-server config --global --codex
   npx @enfyra/mcp-server config --reconfig
-  npx @enfyra/mcp-server config -a http://localhost:3000/api -e admin@x.com -p 'secret'
+  npx @enfyra/mcp-server config -a http://localhost:3000/api -t 'efy_pat_...'
   npx @enfyra/mcp-server config --yes
-  ENFYRA_PASSWORD=secret npx @enfyra/mcp-server config --yes -e admin@x.com
+  ENFYRA_API_TOKEN=efy_pat_... npx @enfyra/mcp-server config --yes
 `);
 }
 
 function parseArgs(argv) {
   const out = {
     apiUrl: undefined,
-    email: undefined,
-    password: undefined,
+    apiToken: undefined,
     claude: true,
     cursor: true,
     codex: true,
@@ -78,8 +76,10 @@ function parseArgs(argv) {
     else if (a === '--reconfig') out.reconfig = true;
     else if (a === '--global') out.global = true;
     else if (a === '--api-url' || a === '-a') out.apiUrl = next();
-    else if (a === '--email' || a === '-e') out.email = next();
-    else if (a === '--password' || a === '-p') out.password = next();
+    else if (a === '--api-token' || a === '-t') out.apiToken = next();
+    else if (a === '--email' || a === '-e' || a === '--password' || a === '-p') {
+      throw new Error(`${a} is no longer supported; use --api-token instead`);
+    }
     else if (a === '--claude-only' || a === '--claude-code' || a === '--claude') pickClaude = true;
     else if (a === '--cursor-only' || a === '--cursor') pickCursor = true;
     else if (a === '--codex-only' || a === '--codex') pickCodex = true;
@@ -94,14 +94,13 @@ function parseArgs(argv) {
   return out;
 }
 
-function buildServerEntry(apiUrl, email, password) {
+function buildServerEntry(apiUrl, apiToken) {
   return {
     command: 'npx',
     args: ['-y', '@enfyra/mcp-server'],
     env: {
       ENFYRA_API_URL: apiUrl,
-      ENFYRA_EMAIL: email,
-      ENFYRA_PASSWORD: password,
+      ENFYRA_API_TOKEN: apiToken,
     },
   };
 }
@@ -129,7 +128,7 @@ function tomlString(value) {
   return JSON.stringify(String(value ?? ''));
 }
 
-function buildCodexTomlBlock(apiUrl, email, password) {
+function buildCodexTomlBlock(apiUrl, apiToken) {
   return [
     '[mcp_servers.enfyra]',
     'command = "npx"',
@@ -137,13 +136,12 @@ function buildCodexTomlBlock(apiUrl, email, password) {
     '',
     '[mcp_servers.enfyra.env]',
     `ENFYRA_API_URL = ${tomlString(apiUrl)}`,
-    `ENFYRA_EMAIL = ${tomlString(email)}`,
-    `ENFYRA_PASSWORD = ${tomlString(password)}`,
+    `ENFYRA_API_TOKEN = ${tomlString(apiToken)}`,
     '',
   ].join('\n');
 }
 
-async function mergeCodexConfig(absPath, apiUrl, email, password) {
+async function mergeCodexConfig(absPath, apiUrl, apiToken) {
   let raw = '';
   try {
     raw = await readFile(absPath, 'utf8');
@@ -162,7 +160,7 @@ async function mergeCodexConfig(absPath, apiUrl, email, password) {
     if (!skip) kept.push(line);
   }
 
-  const next = `${kept.join('\n').trimEnd()}\n\n${buildCodexTomlBlock(apiUrl, email, password)}`;
+  const next = `${kept.join('\n').trimEnd()}\n\n${buildCodexTomlBlock(apiUrl, apiToken)}`;
   await mkdir(dirname(absPath), { recursive: true });
   await writeFile(absPath, next, 'utf8');
 }
@@ -180,7 +178,7 @@ function parseTomlString(value) {
 async function readCodexEnfyraEnv(absPath) {
   try {
     const raw = await readFile(absPath, 'utf8');
-    const values = { apiUrl: '', email: '', password: '' };
+    const values = { apiUrl: '', apiToken: '' };
     let inEnv = false;
     for (const line of raw.split(/\r?\n/)) {
       const header = line.match(/^\s*\[([^\]]+)\]\s*$/);
@@ -194,10 +192,9 @@ async function readCodexEnfyraEnv(absPath) {
       const key = pair[1];
       const value = parseTomlString(pair[2]);
       if (key === 'ENFYRA_API_URL') values.apiUrl = value;
-      if (key === 'ENFYRA_EMAIL') values.email = value;
-      if (key === 'ENFYRA_PASSWORD') values.password = value;
+      if (key === 'ENFYRA_API_TOKEN') values.apiToken = value;
     }
-    if (values.apiUrl || values.email || values.password) return values;
+    if (values.apiUrl || values.apiToken) return values;
   } catch {
     /* */
   }
@@ -229,11 +226,10 @@ async function loadExistingEnfyraEnv(root, readClaude, readCursor, readCodex, gl
       const raw = await readFile(p, 'utf8');
       const j = JSON.parse(raw);
       const e = j?.mcpServers?.[SERVER_KEY]?.env;
-      if (e && typeof e === 'object' && (e.ENFYRA_API_URL || e.ENFYRA_EMAIL || e.ENFYRA_PASSWORD)) {
+      if (e && typeof e === 'object' && (e.ENFYRA_API_URL || e.ENFYRA_API_TOKEN)) {
         return {
           apiUrl: typeof e.ENFYRA_API_URL === 'string' ? e.ENFYRA_API_URL : '',
-          email: typeof e.ENFYRA_EMAIL === 'string' ? e.ENFYRA_EMAIL : '',
-          password: typeof e.ENFYRA_PASSWORD === 'string' ? e.ENFYRA_PASSWORD : '',
+          apiToken: typeof e.ENFYRA_API_TOKEN === 'string' ? e.ENFYRA_API_TOKEN : '',
         };
       }
     } catch {
@@ -244,7 +240,7 @@ async function loadExistingEnfyraEnv(root, readClaude, readCursor, readCodex, gl
     const codex = await readCodexEnfyraEnv(getCodexConfigPath(root, globalScope));
     if (codex) return codex;
   }
-  return { apiUrl: '', email: '', password: '' };
+  return { apiUrl: '', apiToken: '' };
 }
 
 async function promptTargetChoice() {
@@ -357,10 +353,9 @@ async function promptTargetSelect(choices, initialIndex = 0) {
 
 async function promptConfig(opts, existing) {
   let apiUrl = opts.apiUrl;
-  let email = opts.email;
-  let password = opts.password;
-  if (apiUrl !== undefined && email !== undefined && password !== undefined) {
-    return { apiUrl: String(apiUrl).replace(/\/$/, ''), email, password };
+  let apiToken = opts.apiToken;
+  if (apiUrl !== undefined && apiToken !== undefined) {
+    return { apiUrl: String(apiUrl).replace(/\/$/, ''), apiToken };
   }
 
   const rl = createInterface({ input, output });
@@ -378,22 +373,15 @@ async function promptConfig(opts, existing) {
   }
   apiUrl = String(apiUrl).replace(/\/$/, '');
 
-  const defaultEmail = opts.email ?? process.env.ENFYRA_EMAIL ?? existing.email ?? '';
-  if (email === undefined) {
-    const hint = defaultEmail ? `[${defaultEmail}]` : '[empty]';
-    const line = (await q(`ENFYRA_EMAIL ${hint}: `)).trim();
-    email = line || defaultEmail;
-  }
-
-  const defaultPass = opts.password ?? process.env.ENFYRA_PASSWORD ?? existing.password ?? '';
-  if (password === undefined) {
-    const hint = existing.password ? '(Enter = keep current)' : '(optional)';
-    const line = (await q(`ENFYRA_PASSWORD ${hint}: `)).trim();
-    password = line !== '' ? line : defaultPass;
+  const defaultApiToken = opts.apiToken ?? process.env.ENFYRA_API_TOKEN ?? existing.apiToken ?? '';
+  if (apiToken === undefined) {
+    const hint = defaultApiToken ? '(Enter = keep current)' : '(recommended)';
+    const line = (await q(`ENFYRA_API_TOKEN ${hint}: `)).trim();
+    apiToken = line !== '' ? line : defaultApiToken;
   }
 
   await rl.close();
-  return { apiUrl, email, password };
+  return { apiUrl, apiToken };
 }
 
 function resolveNonInteractive(opts, existing) {
@@ -403,9 +391,8 @@ function resolveNonInteractive(opts, existing) {
     (existing.apiUrl || undefined) ??
     'http://localhost:3000/api'
   ).replace(/\/$/, '');
-  const email = opts.email ?? process.env.ENFYRA_EMAIL ?? existing.email ?? '';
-  const password = opts.password ?? process.env.ENFYRA_PASSWORD ?? existing.password ?? '';
-  return { apiUrl, email, password };
+  const apiToken = opts.apiToken ?? process.env.ENFYRA_API_TOKEN ?? existing.apiToken ?? '';
+  return { apiUrl, apiToken };
 }
 
 export async function runLocalConfig(argv) {
@@ -439,21 +426,18 @@ export async function runLocalConfig(argv) {
   const existing = await loadExistingEnfyraEnv(root, writeClaude, writeCursor, writeCodex, opts.global);
 
   let apiUrl;
-  let email;
-  let password;
+  let apiToken;
   if (usePrompt) {
     const resolved = await promptConfig(opts, existing);
     apiUrl = resolved.apiUrl;
-    email = resolved.email;
-    password = resolved.password;
+    apiToken = resolved.apiToken;
   } else {
     const resolved = resolveNonInteractive(opts, existing);
     apiUrl = resolved.apiUrl;
-    email = resolved.email;
-    password = resolved.password;
+    apiToken = resolved.apiToken;
   }
 
-  const serverEntry = buildServerEntry(apiUrl, email, password);
+  const serverEntry = buildServerEntry(apiUrl, apiToken);
   const written = [];
 
   if (writeClaude) {
@@ -468,7 +452,7 @@ export async function runLocalConfig(argv) {
   }
   if (writeCodex) {
     const p = getCodexConfigPath(root, opts.global);
-    await mergeCodexConfig(p, apiUrl, email, password);
+    await mergeCodexConfig(p, apiUrl, apiToken);
     written.push(p);
   }
 
@@ -479,7 +463,7 @@ export async function runLocalConfig(argv) {
   console.log('  • Claude Code: open this folder; approve project MCP if prompted (`claude mcp reset-project-choices` to reset).');
   console.log('  • Cursor: open this folder, restart Cursor or reload MCP, then confirm server under Settings → MCP.');
   console.log('  • Run `config` again anytime to change values (same files are merged/overwritten for `enfyra`).');
-  if (!email || !password) {
-    console.log('\nWarning: ENFYRA_EMAIL or ENFYRA_PASSWORD is empty — tools may not authenticate until set.');
+  if (!apiToken) {
+    console.log('\nWarning: ENFYRA_API_TOKEN is empty — tools will not authenticate until set.');
   }
 }

package/src/lib/mcp-examples.js

@@ -377,7 +377,7 @@ return @DATA`,
           <h2 class="text-lg font-semibold">Cloud projects</h2>
 
           <PermissionGate :condition="canCreateCloudProject">
-            <UButton icon="i-lucide-plus" label="Create instance" @click="openCreate = true" />
+            <UButton icon="i-lucide-plus" label="Create project" @click="openCreate = true" />
           </PermissionGate>
         </div>
 
@@ -647,6 +647,36 @@ create_extension({
           'Put page-level actions in useHeaderActionRegistry or useSubHeaderActionRegistry.',
           'Page extensions should be full-bleed by default and responsive from the first version.',
           'The extension root is already inside eApp main; do not add root-level page padding.',
+          'After saving, open eApp tabs should update through the server/eApp realtime reload contract; do not tell the user to refresh unless that contract is proven broken.',
+        ],
+      },
+      {
+        name: 'Debug menu or extension changes that do not appear in open eApp tabs',
+        code: `// Server side: menu_definition and extension_definition are runtime UI definitions.
+// They must participate in partial reload, just like metadata/routes.
+// Expected server contract:
+// - cache orchestrator maps menu_definition -> menu reload
+// - cache orchestrator maps extension_definition -> extension reload
+// - successful writes emit $system:reload to the admin Socket.IO namespace
+
+// eApp side expected listener behavior:
+// if reload target is metadata/menu:
+//   await fetch menus
+//   rebuild menu registry with reset: true
+//   invalidate dynamic extension cache too, because route-to-extension mapping may change
+// if reload target is extension/menu or extension/global:
+//   clear dynamic extension component/meta cache
+
+// Verification pattern:
+// 1. Save the menu or extension record.
+// 2. Watch the open eApp tab for the $system:reload event.
+// 3. Confirm sidebar/menu registry or extension component cache changed.
+// 4. Only use manual reload endpoints or browser refresh after the natural event path is proven stale.`,
+        notes: [
+          'Do not treat menu and extension writes as plain CRUD when debugging live admin UI.',
+          'Check both halves: ASV/ESV emits the reload event, and eApp consumes it.',
+          'Menu reload should also invalidate extension cache because menu records attach page extensions to routes.',
+          'Manual reload is a fallback, not the default fix.',
         ],
       },
       {

package/src/lib/mcp-instructions.js

@@ -40,7 +40,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '### Capability map (current Enfyra system)',
     '- **Schema/metadata:** `table_definition`, `relation_definition`, and schema tools manage tables, columns, relations, validation, and migrations. `column_definition` is internal/no-route; columns are created/updated through table schema operations.',
     '- **Dynamic REST API:** `route_definition`, `route_handler_definition`, `pre_hook_definition`, `post_hook_definition`, `route_permission_definition`, and `method_definition` define paths, methods, handlers, hooks, and permissions.',
-    '- **Auth/OAuth/session:** `user_definition`, `role_definition`, `oauth_config_definition`, `oauth_account_definition`; `session_definition` is internal/no-route. OAuth is browser redirect only; MCP login is email/password. `user_definition` is the single source of truth for app users.',
+    '- **Auth/OAuth/session:** `user_definition`, `role_definition`, `api_token_definition`, `oauth_config_definition`, `oauth_account_definition`; `session_definition` and `api_token_definition` are internal/no-route. OAuth is browser redirect only. MCP uses `ENFYRA_API_TOKEN` through `/auth/token/exchange`; configure tokens from eApp `/me`. `user_definition` is the single source of truth for app users.',
     '- **Guards/permissions/validation:** `guard_definition`, `guard_rule_definition`, `field_permission_definition`, and `column_rule_definition` control route guards, field access, and request body validation.',
     '- **GraphQL:** `gql_definition` enables tables in GraphQL. GraphQL endpoint and schema share `ENFYRA_API_URL`; GraphQL requires Bearer auth.',
     '- **Files/storage/assets:** `file_definition`, `file_permission_definition`, `folder_definition`, `storage_config_definition` plus upload/assets routes and file helpers.',
@@ -64,7 +64,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- OAuth starts on the same proxy prefix, e.g. **`GET /enfyra/auth/{provider}?redirect=<absoluteReturnUrl>&cookieBridgePrefix=/enfyra`**. `redirect` must be an absolute `http(s)` URL with the app origin. `cookieBridgePrefix` is the third app proxy prefix that forwards to the Enfyra API; Enfyra normalizes it, so `enfyra`, `/enfyra`, and `/enfyra/` all mean `/enfyra`. Use token-query callback handling only when the app intentionally manages tokens itself.',
     '- Socket.IO uses the app bridge too. Browser clients should connect to the gateway namespace with the Socket.IO transport path on the app origin, e.g. `io("/chat", { path: "/socket.io", withCredentials: true })`, while Nuxt proxies `/socket.io/**` to the Enfyra app bridge `/ws/socket.io/**`. Do not connect browser code directly to the hidden backend Socket.IO endpoint.',
     '- If a project explicitly standardizes on `/api/**` instead of `/enfyra/**`, keep the same Cloud-style behavior under that prefix: proxy to the Enfyra API and avoid generated cookie-management routes unless the user asks for a custom auth boundary.',
-    '- If you are explaining MCP\'s own internal authentication, that is separate: this MCP server logs itself in with email/password against `{ENFYRA_API_URL}/auth/login`; for normal app work, `ENFYRA_API_URL` must still be the app proxy base such as `{{ nuxtApp }}/api`.',
+    '- If you are explaining MCP\'s own internal authentication, that is separate: this MCP server exchanges `ENFYRA_API_TOKEN` against `{ENFYRA_API_URL}/auth/token/exchange`. For normal app work, `ENFYRA_API_URL` must still be the app proxy base such as `{{ nuxtApp }}/api`.',
     '',
     '### Routes vs tables (custom endpoints, handlers, hooks)',
     '- REST-first workflow for any feature: **`inspect_feature`** to locate candidates → **`inspect_table`** for table/field/relation/rule context → **`inspect_route`** for handlers/hooks/guards/permissions → **`test_rest_endpoint`** to verify the actual HTTP behavior.',
@@ -88,7 +88,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Common mapping: one owner record → `many-to-one`; one record has many children → define the child `many-to-one` and use inverse/read deep relation; peer/tag lists → `many-to-many`; one profile/settings row per parent → `one-to-one` when supported by the model.',
     '- If the user asks to add a foreign key field, interpret it as a relation request unless they explicitly say they need a plain scalar column. Do not create both a relation and a duplicate scalar FK column for the same concept.',
     '- **Never ask for or provide physical FK column names** when creating/updating relations. Do not include `fkCol`, `fkColumn`, `foreignKeyColumn`, `sourceColumn`, `targetColumn`, `junctionSourceColumn`, or `junctionTargetColumn` in create/update payloads unless you are only displaying existing metadata. Enfyra relation cascade derives physical FK/junction names from `propertyName` and table metadata, then hides FK columns from app form/schema definition.',
-    '- For relation CRUD payloads, the public interface is the relation `propertyName`: example create body uses `"author": {"id": 1}`, not `"authorId"` or a physical FK column. Query/deep/filter keys also use relation `propertyName`.',
+    '- For relation CRUD payloads and generated server logic, the public interface is the relation `propertyName`: example create body uses `"author": {"id": 1}` or `"author": 1`, not `"authorId"` or a physical FK column. Query/deep/filter keys also use relation `propertyName`, e.g. `{ "author": { "_eq": 1 } }` or `{ "author": { "id": { "_eq": 1 } } }`. Do not hardcode physical FK fields such as `userId` in handlers, hooks, flows, services, or extension-adjacent code unless you are deliberately querying raw SQL outside Enfyra metadata APIs.',
     '- **Realtime/chat unread modeling:** unread/read is per user and per message. Do not put `read` or `lastRead` on `chat_conversation` globally. Prefer a join table such as `chat_message_read` with relations `message`, `conversation`, `member`, boolean `isRead`, nullable `readAt`, unique `["message","member"]`, and indexes `["member","isRead","conversation"]` plus `["conversation","member","isRead"]`. The UI can render a dot by checking existence of unread rows instead of counting every unread message.',
     '- **Realtime/chat latest message modeling:** keep `chat_conversation.lastMessage` as a nullable many-to-one relation to `chat_message`. Do not duplicate latest message text/date onto `chat_conversation`. Load conversation lists with relation fields such as `lastMessage.id,lastMessage.text,lastMessage.createdAt`, update `lastMessage` after the message is persisted, and repair it in a `DELETE /chat_message` post-hook when deleting the current latest message.',
     '- **Chat deletion modeling:** user-level delete/leave should remove the user from `chat_conversation_member` or otherwise make membership inactive. Do not add duplicated `deleted_at` state to both conversation and membership unless the product explicitly needs restore/audit behavior. A DM deleted for both sides is a membership operation for both members; a group is physically deleted only when no memberships remain.',
@@ -122,7 +122,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- If the **current request method** is listed in **publishedMethods** for that route, the server allows the call **without** a Bearer token (`RoleGuard`).',
     '- Otherwise the client must send an **Authorization** header with **Bearer** JWT from login. Then the user must satisfy **routePermissions** (unless root admin).',
     '- Cloud owner-scoped GET handlers must keep normal users filtered to their own `cloud_projects.owner`, but root admin operational views must bypass that owner filter with `@USER.isRootAdmin`. Apply this consistently to `cloud_projects`, `cloud_subscriptions`, `cloud_payment_orders`, `cloud_provisioning_history`, and `/cloud/projects` so admin data routes match admin summary APIs.',
-    '- MCP tools that use `fetchAPI` authenticate with the configured admin credentials; explain to users that **direct HTTP** calls need a token unless the route/method is published.',
+    '- MCP tools that use `fetchAPI` authenticate with the configured `ENFYRA_API_TOKEN`. Explain to users that **direct HTTP** calls need a Bearer token unless the route/method is published.',
     '',
     '### Post-hooks (REST)',
     '- **post-hooks always run** after the handler, including when the handler or a pre-hook throws — then `@ERROR` / `$ctx.$error` is set and `@DATA` is null.',
@@ -163,7 +163,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- Prefer `set(key, value, ttlMs)` with a TTL. `setNoExpire` is allowed, but persistent user-cache entries can still be evicted by the soft allocation limit.',
     '',
     '### OAuth login (browser / frontend — not the MCP `login` tool)',
-    '- **MCP `login`** uses **email + password** → `POST {base}/auth/login`. It cannot complete OAuth (no browser redirect).',
+    '- **MCP `login`** exchanges an API token through `POST {base}/auth/token/exchange`. It cannot complete OAuth (no browser redirect) and does not use email/password credentials.',
     '- **Supported providers (server):** `google`, `facebook`, `github` only.',
     '',
     '**Redirect URI must match everywhere (critical):**',
@@ -286,12 +286,13 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Operational list data loading:** do not use arbitrary fixed limits such as `limit=50` as the whole data strategy for admin pages. Use pagination, expose result count when the API supports `meta=filterCount`, and add search/filter controls for natural lookup keys such as project id, name, and subdomain.',
     '- **ESV aggregate contract:** aggregate query must be an object keyed by a real field or relation, for example `aggregate: { id: { count: true }, status: { count: { _eq: "failed" } }, amount: { sum: true } }`. Results are returned in `response.meta.aggregate`. Time windows and cross-field conditions belong in top-level `filter`, not inside a field aggregate condition. Field aggregate conditions only support operators on that same field; relation aggregates use `countRecords`.',
     '- **Aggregate numeric rule:** `sum` and `avg` require a numeric field in ESV. Do not aggregate money stored as varchar/text. Use a numeric money field such as `amount_usd` with type `float`, `amount_cents`, or `amount` for revenue stats, or build a dedicated stats route that normalizes legacy values explicitly. If metadata says `float` but SQL aggregate still fails with `sum(character varying)`, the Enfyra Server physical schema is stale or missing the SQL float DDL mapping and must be redeployed/healed before relying on aggregate.',
-    '- **Partial reload default:** ESV automatically triggers partial reloads for metadata, routes, extensions, flows, handlers, and related caches after successful writes. Do not reflexively call `/admin/reload`, `/admin/reload/metadata`, or `/admin/reload/routes` after each change. Verify naturally first; use manual reload only when verification shows stale behavior, a reload event failed, or a concrete error indicates the partial reload did not apply.',
+    '- **Partial reload default:** ESV/ASV automatically triggers partial reloads for metadata, routes, menus, extensions, flows, handlers, and related caches after successful writes. Do not reflexively call `/admin/reload`, `/admin/reload/metadata`, or `/admin/reload/routes` after each change. Verify naturally first; use manual reload only when verification shows stale behavior, a reload event failed, or a concrete error indicates the partial reload did not apply.',
+    '- **Menu/extension realtime reload contract:** `menu_definition` and `extension_definition` writes are runtime UI changes, not plain CRUD. The server cache orchestrator must emit `$system:reload` through the admin Socket.IO channel with identifiers that eApp handles; eApp must refetch menus/rebuild the menu registry for menu reloads and invalidate dynamic extension caches for extension reloads. Menu reloads can change route-to-extension mapping, so they should also invalidate extension cache. If an open admin tab does not reflect menu/extension changes, debug this two-sided reload contract before telling the user to refresh.',
     '- **Dashboard stats:** time range buttons must change the query filter and reload stats. Cloud dashboard should summarize flow execution errors from `flow_execution_definition` and billing stats from order/subscription records; successful/no-error flow runs do not need a standalone provisioning menu.',
     '- **Page layout default:** page extensions should render full-bleed inside the app shell by default. The extension root is already inside the eApp page `<main>`, so do not add root-level page padding such as `p-4 sm:p-6 xl:p-8`; use spacing between internal sections only. Do not wrap the entire page in a centered card/container unless explicitly requested. Use responsive grids/stacks from the first version so the page works on desktop, tablet, and mobile.',
     '- **PageHeader is mandatory for page extensions:** eApp already renders `CommonPageHeader` from `usePageHeaderRegistry()` in the app shell. Page extensions must call `const { registerPageHeader } = usePageHeaderRegistry()` and register app-level context such as `{ title, description, leadingIcon, gradient, variant }` instead of rendering their own top `<header>` inside extension content. Use `variant: "minimal"` for operational/admin detail pages unless the page intentionally needs a larger title strip.',
     '- **Do not misuse PageHeader stats:** `PageHeader.stats` renders prominent stat cards inside the shell header. Do not put normal operational KPIs, host capacity, billing totals, or detail metrics there by default; keep those as body cards/tables where the operator can scan them with the page content. Only use PageHeader stats for a deliberately compact overview page where the stats are truly header-level context.',
-    '- **Page actions belong in registries:** Move page-level buttons into `useHeaderActionRegistry` or `useSubHeaderActionRegistry`; keep the extension body for operational content only. Sensitive registry actions must include a `permission` condition, for example `{ id: "create", label: "Create instance", permission: { and: [{ route: "/cloud_projects", methods: ["POST"] }] }, onClick }`.',
+    '- **Page actions belong in registries:** Move page-level buttons into `useHeaderActionRegistry` or `useSubHeaderActionRegistry`; keep the extension body for operational content only. Sensitive registry actions must include a `permission` condition, for example `{ id: "create", label: "Create project", permission: { and: [{ route: "/cloud_projects", methods: ["POST"] }] }, onClick }`.',
     '- **Extension navigation:** prefer `NuxtLink` or Nuxt UI components with `:to` for visible navigation links and drill-down cards/buttons. Use `navigateTo(...)` only for imperative navigation after submit, confirm, mutation, or another side effect.',
     '- **Extension runtime scope:** eApp exposes Vue APIs and injected Nuxt/Enfyra composables both to script global scope and Vue app `globalProperties`. Template expressions may call injected helpers directly, for example after a save handler can call `navigateTo("/data/cloud_projects")`, because Vue compiles template helpers to `_ctx.*`.',
     '- **Extension CSS affects shell utility ordering:** dynamic extension CSS is injected after the app shell CSS. Shell/page-header code must not put conflicting plain Tailwind utilities on the same element, such as `flex-col` plus `flex-row`, `items-start` plus `items-center`, or `text-left` plus `text-center`. Choose one mutually exclusive class per state; otherwise extension CSS can change which utility wins and shift shell layout.',
@@ -300,9 +301,12 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **PermissionGate is mandatory inside admin extensions:** every sensitive action button, form, mutation, destructive workflow, and data shortcut must be wrapped in `PermissionGate` or guarded with `usePermissions()` before rendering/enabling. Default gates: list/detail visibility needs `methods: ["GET"]`; create and custom flow-trigger routes usually need `methods: ["POST"]`; native record edits need `methods: ["PATCH"]`; native delete routes need `methods: ["DELETE"]`. Root admin still passes through normal permission helpers, but extension code must not rely on root-only assumptions.',
     '- **Extension permission UX:** if the current user can read a page but cannot perform an action, hide the action by default. If hiding would confuse the workflow, render a disabled state with a short reason. Never let the button render active and depend only on the server rejection; server permissions are the final boundary, not the UI contract.',
     '- **Cloud project admin operations:** use canonical `cloud_projects` table routes as the single source of truth. Admin manual create uses `POST /cloud_projects` with schema-safe fields `owner: { id }`, `plan: { id }`, `admin_email`, `admin_password`, `name`, `subdomain`, and `status: "creating"`. The UI must show tenant admin credential as an email/password pair and include a generate-password action before create; do not build an email-only credential form. Project detail is the place for destructive lifecycle actions. Disable uses `PATCH /cloud_projects/:id` with body `{ status: "disabled" }` and `confirm_tenant_id`/`confirm_hash` in query params. Enable uses `PATCH /cloud_projects/:id` with body `{ status: "running" }`. Delete uses `DELETE /cloud_projects/:id` with typed `confirm_tenant_id`, returned `requiredConfirmHash`, and the matching hash before triggering `cloud-delete-project`. Do not create separate one-off `/cloud/admin/projects/*` action routes for create/disable/enable/delete when the canonical table route can own the workflow.',
+    '- **Cloud admin terminology:** in Cloud admin UI, call physical tenant workloads "projects" everywhere. Do not label creation or details as "instance" unless the user explicitly asks for that word.',
+    '- **Cloud project create UI:** manual Cloud project creation should use `CommonDrawer`, not a wide modal. Let the operator search/select `user_definition` by email and select a plan with cards; do not expose duplicate free-text `user id` or `plan id` inputs when selectors exist. Prefer sending only the selected owner id, plan id, and required workflow fields such as `expiredAt` when the canonical handler can derive customer email, project name, subdomain, and password. Expiry selection should use quick presets plus a manual calendar (`UCalendar` when available, loaded through `install_package`/`getPackages` if an app package is needed).',
+    '- **Cloud host settings and creation UI:** host settings store only provider selection codes Enfyra controls, currently location and server type. Do not expose or save provider-derived RAM, disk, vCPU, or cost values by hand. Query the provider catalog route, show real package/location cards, support load-more/search when the list is long, and snapshot provider facts onto `cloud_servers` only during host creation.',
     '- **Flow schedule UI:** schedule trigger editors must keep the server contract as `triggerConfig.cron` and `triggerConfig.timezone`, but the UI should not be a bare cron field plus giant timezone dropdown. Provide common cadence presets, readable current-schedule summary, searchable access to all IANA timezones, suggested timezone shortcuts, and a custom cron escape hatch so operators can configure recurring checks without remembering cron syntax.',
-    '- **Admin operation UI:** use eApp `CommonModal` for create, disable, delete, and multi-field confirmation workflows. `CommonModal` is the app-matched wrapper around Nuxt UI modal and follows the `UModal` contract: `v-model:open`, `#header`, `#body`, and `#footer`. Keep the page body as compact summary/actions; do not use raw `UModal`, custom fixed overlays, or large inline confirmation panels for these workflows.',
-    '- **FormEditor is preferred for table-record forms:** when an extension creates or edits a concrete table record such as `cloud_host_settings`, `cloud_project_settings`, `cloud_servers`, or `cloud_projects`, use `FormEditor`/`FormEditorLazy` inside the modal/page instead of hand-building every input. Customize layout with `sections`, `includes`, and `field-map`; reserve custom inputs only for workflow-specific fields that are not table columns.',
+    '- **Admin operation UI:** use eApp `CommonModal` for compact create, disable, delete, and multi-field confirmation workflows. Use `CommonDrawer` for longer setup workflows such as Cloud host settings, host creation, project creation, and provider/package selection. Open the modal/drawer immediately on click, then render loading/error/content inside it; do not wait for async fetches to finish before showing the shell.',
+    '- **FormEditor is preferred for table-record forms:** when an extension creates or edits a concrete table record such as `cloud_host_settings`, `cloud_servers`, or `cloud_projects`, use `FormEditor`/`FormEditorLazy` inside the modal/page when the form is a direct table edit. Customize layout with `sections`, `includes`, and `field-map`; reserve custom inputs only for workflow-specific fields that are not table columns.',
     '- **Modal form layout:** inside `CommonModal`, stack each form control vertically with label text above a full-width input/control. Use a small grid/space stack such as `grid gap-4`, `p.text-sm.font-medium`, then `UInput class="mt-2 w-full"`. Do not place modal labels and inputs side by side unless the user explicitly asks for a dense horizontal form.',
     '- **Confirmation modal flow:** destructive/admin confirmation modals must read top-to-bottom as the operator workflow. For server-hash confirmations, render: tenant/id input first, then a full-width `Request hash` button, then a disabled hash input that is auto-filled by the server response, then the final destructive action in the footer. The final action stays disabled until the typed id matches and the server hash has been requested. Do not ask operators to manually type or edit the hash.',
     '- **Cloud host deletion:** do not delete `cloud_servers` directly from an extension or custom route. Root admin host deletion must be detail-only from `/cloud/hosts/:id`, call `POST /cloud/admin/hosts/delete`, require typed `confirm_host_id`, block when any project is running or attached, return a server-generated `requiredConfirmHash` for an empty host, and require the hash back via `confirmHash` query before triggering `cloud-delete-host`.',
@@ -343,7 +347,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **useMounted:** Mount state helper.',
     '',
     '#### Injected UI Components (auto-resolved):',
-    '- **Common:** `EmptyState`, `LoadingState`, `ErrorState`, `PageHeader`, `FormCard`, `CommonModal`, `Modal`, `Drawer`, `BreadCrumbs`, `ListItem`, `LazyImage`, `GlobalConfirm`, `UploadModal`, `UploadModalLazy`, `AvatarInitials`, `BrandingHeader`, `SettingsCard`, `RouteLoading`',
+    '- **Common:** `EmptyState`, `LoadingState`, `ErrorState`, `PageHeader`, `FormCard`, `CommonModal`, `CommonDrawer`, `Modal`, `Drawer`, `BreadCrumbs`, `ListItem`, `LazyImage`, `GlobalConfirm`, `UploadModal`, `UploadModalLazy`, `AvatarInitials`, `BrandingHeader`, `SettingsCard`, `RouteLoading`',
     '- **Data Table:** `DataTable`, `DataTableLazy`, `ColumnSelector`',
     '- **Form:** `FormEditor`, `FormEditorLazy` (same API, lazy-loaded), `FilterEditor`, `FilterHistory`, `FieldSelector`',
     '- **File Manager:** `FileManager`, `FileView`, `FileGridCard`, `CreateFolderModal`',
@@ -370,6 +374,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Search first with `search_npm`** if unsure of exact package name.',
     '- **Server** packages → available as `$ctx.$pkgs.packageName` in handlers/hooks.',
     '- **App** packages → available via `getPackages([\'dayjs\'])` in extensions (call in `onMounted`).',
+    '- **Extension package imports:** Do not write static imports like `import { CalendarDate } from "@internationalized/date"` inside `extension_definition.code`; the extension builder does not resolve app packages that way. Install the package as type `App`, then load it inside the extension with `const pkgs = await getPackages(["@internationalized/date"]); const { CalendarDate } = pkgs["@internationalized/date"];`.',
     '- **Do NOT use `create_record` on `package_definition` directly** — use `install_package` instead.',
     '',
     '#### Important patterns:',
@@ -377,7 +382,7 @@ export function buildMcpServerInstructions(apiBaseUrl) {
     '- **Header actions:** `useHeaderActionRegistry([{ id: \'refresh\', label: \'Refresh\', onClick: fn, color: \'primary\', icon: \'lucide:refresh\', order: 0 }])`',
     '- **Schema:** Call `fetchSchema()` first, then use `definition.value`, `editableFields.value`, `getField(\'fieldName\')`.',
     '- **Permissions:** Use `checkPermissionCondition({ or: [{ route: \'/posts\', methods: [\'GET\'] }] })` for complex rules. In templates, wrap sensitive controls with `<PermissionGate :condition="{ and: [{ route: \'/admin/action\', methods: [\'POST\'] }] }">...</PermissionGate>` instead of only disabling them visually.',
-    '- **After create/update:** Tell user to refresh (F5). Changes may not appear until reload.',
+    '- **After menu/extension create/update:** open eApp tabs should update through the `$system:reload` contract. Do not tell the user to press F5 unless you have verified the natural reload event failed or the server/eApp version does not support menu/extension reload yet.',
     '',
     '#### Minimal example:',
     '`<template><div class="p-6"><h1 class="text-2xl font-bold">{{ title }}</h1><UButton @click="handleClick">Click</UButton></div></template><script setup>const title = ref(\'My Extension\'); const toast = useToast(); const handleClick = () => toast.add({ title: \'Clicked\', color: \'green\' });</script>`',

package/src/mcp-server-entry.mjs

@@ -11,18 +11,17 @@ import { z } from 'zod';
 
 // Configuration
 const ENFYRA_API_URL = process.env.ENFYRA_API_URL || 'http://localhost:3000/api';
-const ENFYRA_EMAIL = process.env.ENFYRA_EMAIL || '';
-const ENFYRA_PASSWORD = process.env.ENFYRA_PASSWORD || '';
+const ENFYRA_API_TOKEN = process.env.ENFYRA_API_TOKEN || '';
 
 // Import modules
-import { login, refreshAccessToken, getValidToken, resetTokens, getTokenExpiry, initAuth } from './lib/auth.js';
+import { exchangeApiToken, refreshAccessToken, getValidToken, resetTokens, getTokenExpiry, initAuth } from './lib/auth.js';
 import { fetchAPI, validateFilter, validateTableName } from './lib/fetch.js';
 import { buildMcpServerInstructions, buildGraphqlUrls } from './lib/mcp-instructions.js';
 import { getExamples, listExampleCategories } from './lib/mcp-examples.js';
 import { registerTableTools } from './lib/table-tools.js';
 
 // Initialize auth module
-initAuth(ENFYRA_API_URL, ENFYRA_EMAIL, ENFYRA_PASSWORD);
+initAuth(ENFYRA_API_URL, ENFYRA_API_TOKEN);
 
 const CAPABILITY_AREAS = [
   {
@@ -37,8 +36,8 @@ const CAPABILITY_AREAS = [
   },
   {
     area: 'Auth, roles, sessions, OAuth',
-    tables: ['user_definition', 'role_definition', 'session_definition', 'oauth_config_definition', 'oauth_account_definition'],
-    workflow: 'Email/password login is /auth/login. OAuth is browser redirect based. session_definition is internal/no-route.',
+    tables: ['user_definition', 'role_definition', 'api_token_definition', 'session_definition', 'oauth_config_definition', 'oauth_account_definition'],
+    workflow: 'MCP auth exchanges ENFYRA_API_TOKEN through /auth/token/exchange. Configure an API token from eApp /me.',
   },
   {
     area: 'Guards and permissions',
@@ -1691,15 +1690,17 @@ server.tool('get_all_roles', 'Get all role definitions', {}, async () => {
   return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
 });
 
-server.tool('login', 'Force login to Enfyra and get new tokens', {
-  email: z.string().email().optional().describe('Admin email'),
-  password: z.string().optional().describe('Password'),
-}, async ({ email, password }) => {
-  const loginEmail = email || ENFYRA_EMAIL;
-  const loginPassword = password || ENFYRA_PASSWORD;
-  if (!loginEmail || !loginPassword) throw new Error('Email and password required');
-  await login(ENFYRA_API_URL, loginEmail, loginPassword);
-  return { content: [{ type: 'text', text: `Logged in successfully!\nToken expires: ${new Date(getTokenExpiry()).toISOString()}` }] };
+server.tool('login', 'Force authentication to Enfyra and get a new access token', {
+  apiToken: z.string().optional().describe('API token; preferred for MCP and automation'),
+}, async ({ apiToken }) => {
+  const token = apiToken || ENFYRA_API_TOKEN;
+  if (token) {
+    await exchangeApiToken(ENFYRA_API_URL, token);
+    const expiry = getTokenExpiry();
+    const expiryLabel = expiry === Infinity ? 'no expiration' : new Date(expiry).toISOString();
+    return { content: [{ type: 'text', text: `Authenticated with API token.\nToken expires: ${expiryLabel}` }] };
+  }
+  throw new Error('ENFYRA_API_TOKEN required');
 });
 
 // ============================================================================
@@ -1831,7 +1832,7 @@ server.tool(
   'create_extension',
   [
     'Create an extension (Vue SFC page or widget). Code must be Vue SFC: <template>...</template> + <script setup>...</script> — NO imports, use globals (ref, useToast, useApi, UButton, etc).',
-    'For type=page: create menu first (create_menu), get id, then pass menuId. For type=widget no menu needed. Server auto-compiles; tell user to refresh (F5) after create. See extension rules in MCP instructions.',
+    'For type=page: create menu first (create_menu), get id, then pass menuId. For type=widget no menu needed. Server auto-compiles and should emit realtime reload to open eApp tabs. See extension rules in MCP instructions.',
   ].join(' '),
   {
     name: z.string().describe('Extension name (unique)'),
@@ -1849,7 +1850,7 @@ server.tool(
       delete body.menuId;
     }
     const result = await fetchAPI(ENFYRA_API_URL, '/extension_definition', { method: 'POST', body: JSON.stringify(body) });
-    return { content: [{ type: 'text', text: `Extension created (ID: ${result.id}). Tell user to refresh (F5) to see it.\n${JSON.stringify(result, null, 2)}` }] };
+    return { content: [{ type: 'text', text: `Extension created (ID: ${result.id}). Open eApp tabs should update through the realtime reload contract.\n${JSON.stringify(result, null, 2)}` }] };
   },
 );
 
@@ -1860,7 +1861,7 @@ server.tool(
 async function main() {
   console.error('Starting Enfyra MCP Server...');
   console.error(`API URL: ${ENFYRA_API_URL}`);
-  console.error(`Auth: ${ENFYRA_EMAIL ? `Configured (${ENFYRA_EMAIL})` : 'Not configured'}`);
+  console.error(`Auth: ${ENFYRA_API_TOKEN ? 'API token configured' : 'Not configured'}`);
 
   const transport = new StdioServerTransport();
   await server.connect(transport);