@enfyra/mcp-server 0.0.44 → 0.0.46

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,11 +1,14 @@
 {
   "name": "@enfyra/mcp-server",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "description": "MCP server for Enfyra - manage your Enfyra instance via Claude Code",
   "type": "module",
   "license": "MIT",
   "main": "src/index.mjs",
-  "bin": "src/index.mjs",
+  "bin": {
+    "mcp-server": "src/index.mjs",
+    "enfyra-mcp-server": "src/index.mjs"
+  },
   "files": [
     "src",
     ".codex/skills"

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-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):**',

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');
 });
 
 // ============================================================================
@@ -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);