@agent-native/core 0.20.9 → 0.22.0

package/dist/cli/connect.js

@@ -1,8 +1,9 @@
 /**
  * `agent-native connect <url>` — wire your local Claude Code / Codex / Cowork
- * to a DEPLOYED agent-native app using a browser device-code flow. No token
- * copying: open the verification URL, approve in the browser, and the minted
- * HTTP MCP server entry is written into your client config(s) idempotently.
+ * to a DEPLOYED agent-native app. OAuth-capable clients receive a standard
+ * remote MCP URL entry and authenticate in the host. Fallback clients use the
+ * browser device-code flow: open the verification URL, approve in the browser,
+ * and the minted HTTP MCP server entry is written idempotently.
  *
  *   agent-native connect <url> [--client all|claude-code|claude-code-cli|
  *                               codex|cowork] [--scope user|project]
@@ -31,12 +32,15 @@ import os from "node:os";
 import { spawn } from "node:child_process";
 import path from "node:path";
 import { findWorkspaceRoot } from "../mcp/workspace-resolve.js";
-import { CLIENTS, writeHttpEntryForClient, } from "./mcp-config-writers.js";
-import { visibleTemplates } from "./templates-meta.js";
+import { CLIENTS, configPathFor, writeCodexBlock, writeHttpEntryForClient, writeJsonMcpEntry, } from "./mcp-config-writers.js";
+import { TEMPLATES, visibleTemplates } from "./templates-meta.js";
 const DEVICE_START_PATH = "/_agent-native/mcp/connect/device/start";
 const DEVICE_POLL_PATH = "/_agent-native/mcp/connect/device/poll";
+const MCP_PATH = "/_agent-native/mcp";
 const SERVER_NAME_PREFIX = "agent-native";
 const CONNECT_PREFERENCES_VERSION = 1;
+const CONNECT_PROFILES_VERSION = 1;
+const DEFAULT_DEV_GATEWAY = "http://127.0.0.1:8080";
 const CLIENT_LABELS = {
     "claude-code": "Claude Code",
     "claude-code-cli": "Claude Code CLI",
@@ -49,6 +53,10 @@ const CLIENT_HINTS = {
     codex: "~/.codex/config.toml",
     cowork: "~/.cowork/mcp.json",
 };
+const REMOTE_MCP_OAUTH_CLIENTS = new Set([
+    "claude-code",
+    "claude-code-cli",
+]);
 function logOut(msg) {
     process.stdout.write(`${msg}\n`);
 }
@@ -74,6 +82,16 @@ export function parseConnectArgs(argv) {
         let v;
         if (a === "--all")
             out.all = true;
+        else if ((v = eat("--apps")) !== undefined)
+            out.apps = v;
+        else if ((v = eat("--gateway")) !== undefined)
+            out.gateway = v;
+        else if ((v = eat("--gateway-url")) !== undefined)
+            out.gateway = v;
+        else if ((v = eat("--port")) !== undefined)
+            out.port = Number(v);
+        else if ((v = eat("--owner-email")) !== undefined)
+            out.ownerEmail = v;
         else if ((v = eat("--client")) !== undefined) {
             out.client = v;
             out.clientExplicit = true;
@@ -84,8 +102,12 @@ export function parseConnectArgs(argv) {
             out.name = v;
         else if ((v = eat("--token")) !== undefined)
             out.token = v;
-        else if (!a.startsWith("-") && !out.url)
-            out.url = a;
+        else if (!a.startsWith("-") && !out.url) {
+            if (!out.mode && (a === "dev" || a === "prod"))
+                out.mode = a;
+            else
+                out.url = a;
+        }
     }
     return out;
 }
@@ -290,6 +312,12 @@ async function resolveHostedAppsFromPrompt(deps) {
 function clientArgForDeviceFlow(clients) {
     return clients.length === 1 ? clients[0] : "all";
 }
+export function supportsRemoteMcpOAuth(client) {
+    return REMOTE_MCP_OAUTH_CLIENTS.has(client);
+}
+function clientLabelList(clients) {
+    return clients.map((client) => CLIENT_LABELS[client]).join(", ");
+}
 /** Derive an app slug from a deployed origin, e.g. mail.agent-native.com → mail. */
 function appSlugFromUrl(url) {
     try {
@@ -361,6 +389,61 @@ function responseMessage(json, fallback) {
             : "";
     return message.trim() || fallback;
 }
+function stripMcpPath(baseUrl) {
+    const parsed = new URL(baseUrl);
+    const pathname = parsed.pathname.replace(/\/+$/, "");
+    if (pathname === MCP_PATH || pathname.endsWith(MCP_PATH)) {
+        parsed.pathname = pathname.slice(0, -MCP_PATH.length) || "/";
+        parsed.search = "";
+        parsed.hash = "";
+        return `${parsed.origin}${parsed.pathname}`.replace(/\/+$/, "");
+    }
+    return baseUrl;
+}
+function mcpUrlForBaseUrl(baseUrl) {
+    const parsed = new URL(baseUrl);
+    const pathname = parsed.pathname.replace(/\/+$/, "");
+    if (pathname === MCP_PATH || pathname.endsWith(MCP_PATH)) {
+        parsed.pathname = pathname;
+        parsed.search = "";
+        parsed.hash = "";
+        return `${parsed.origin}${parsed.pathname}`;
+    }
+    return `${baseUrl.replace(/\/+$/, "")}${MCP_PATH}`;
+}
+async function validateOAuthMcpServer(baseUrl, mcpUrl, deps) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const metadataUrl = `${baseUrl}/.well-known/oauth-protected-resource`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 15_000);
+    try {
+        const response = await fetchImpl(metadataUrl, {
+            method: "GET",
+            headers: { accept: "application/json" },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            logErr(`  Could not validate OAuth MCP support at ${metadataUrl} ` +
+                `(HTTP ${response.status}).`);
+            return false;
+        }
+        const metadata = (await response.json().catch(() => null));
+        if (metadata?.resource !== mcpUrl) {
+            logErr(`  ${metadataUrl} did not advertise the expected MCP resource ` +
+                `${mcpUrl}.`);
+            return false;
+        }
+        return true;
+    }
+    catch (err) {
+        logErr(`  Could not reach ${metadataUrl} (${err?.message ?? err}). ` +
+            `Check the URL and your network.`);
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
 const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 /**
  * Run the device-code flow against `baseUrl` and return the approved grant.
@@ -483,13 +566,477 @@ export function writeConfigs(clients, serverName, mcpUrl, token, scope, baseDir
     }
     return written;
 }
+export function connectProfilesPath() {
+    return path.join(os.homedir(), ".agent-native", "connect-profiles.json");
+}
+function readConnectProfiles(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        if (parsed && typeof parsed === "object") {
+            return {
+                version: Number(parsed.version) || CONNECT_PROFILES_VERSION,
+                updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : undefined,
+                prodEntries: parsed.prodEntries && typeof parsed.prodEntries === "object"
+                    ? parsed.prodEntries
+                    : {},
+            };
+        }
+    }
+    catch {
+        // no saved profiles yet
+    }
+    return { version: CONNECT_PROFILES_VERSION, prodEntries: {} };
+}
+function writeConnectProfiles(file, profiles) {
+    profiles.version = CONNECT_PROFILES_VERSION;
+    profiles.updatedAt = new Date().toISOString();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(profiles, null, 2) + "\n", "utf-8");
+}
+function savedProfileEntry(profiles, serverName, client, file) {
+    return profiles.prodEntries?.[serverName]?.[client]?.[file];
+}
+function setSavedProfileEntry(profiles, serverName, client, file, entry) {
+    profiles.prodEntries ??= {};
+    profiles.prodEntries[serverName] ??= {};
+    profiles.prodEntries[serverName][client] ??= {};
+    profiles.prodEntries[serverName][client][file] = entry;
+}
+function readJsonMcpServerEntry(file, serverName) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        const entry = parsed?.mcpServers?.[serverName];
+        return entry && typeof entry === "object" ? entry : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function tomlQuoteForRead(s) {
+    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function codexHeadersForRead(name) {
+    const headers = [`[mcp_servers.${tomlQuoteForRead(name)}]`];
+    if (/^[A-Za-z0-9_-]+$/.test(name))
+        headers.push(`[mcp_servers.${name}]`);
+    return headers;
+}
+function readCodexMcpBlock(file, serverName) {
+    let content = "";
+    try {
+        content = fs.readFileSync(file, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+    const headers = new Set(codexHeadersForRead(serverName));
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        if (!headers.has(lines[i].trim()))
+            continue;
+        const block = [lines[i]];
+        i++;
+        while (i < lines.length && !/^\s*\[/.test(lines[i])) {
+            block.push(lines[i]);
+            i++;
+        }
+        return block.join("\n").replace(/\n*$/, "") + "\n";
+    }
+    return undefined;
+}
+function readCurrentMcpEntry(client, serverName, baseDir, scope) {
+    const file = configPathFor(client, baseDir, scope);
+    if (client === "codex") {
+        const block = readCodexMcpBlock(file, serverName);
+        return {
+            file,
+            saved: block
+                ? { kind: "codex", block, savedAt: new Date().toISOString() }
+                : undefined,
+        };
+    }
+    const entry = readJsonMcpServerEntry(file, serverName);
+    return {
+        file,
+        saved: entry
+            ? { kind: "json", entry, savedAt: new Date().toISOString() }
+            : undefined,
+    };
+}
+function writeSavedMcpEntry(client, file, serverName, saved) {
+    if (client === "codex") {
+        if (saved.kind !== "codex")
+            return;
+        writeCodexBlock(file, serverName, saved.block);
+        return;
+    }
+    if (saved.kind !== "json")
+        return;
+    writeJsonMcpEntry(file, serverName, saved.entry);
+}
+function unescapeTomlString(value) {
+    return value.replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+}
+function parseCodexHeaders(block) {
+    const line = block
+        .split(/\r?\n/)
+        .find((candidate) => /^\s*http_headers\s*=/.test(candidate));
+    if (!line)
+        return {};
+    const match = line.match(/\{(.*)\}/);
+    if (!match)
+        return {};
+    const headers = {};
+    const pairRe = /"((?:\\.|[^"])*)"\s*=\s*"((?:\\.|[^"])*)"/g;
+    let pair;
+    while ((pair = pairRe.exec(match[1]))) {
+        headers[unescapeTomlString(pair[1])] = unescapeTomlString(pair[2]);
+    }
+    return headers;
+}
+function savedEntryUrl(saved) {
+    if (!saved)
+        return undefined;
+    if (saved.kind === "json") {
+        return typeof saved.entry.url === "string" ? saved.entry.url : undefined;
+    }
+    const match = saved.block.match(/^\s*url\s*=\s*"((?:\\.|[^"])*)"/m);
+    return match ? unescapeTomlString(match[1]) : undefined;
+}
+function savedEntryHeaders(saved) {
+    if (!saved)
+        return {};
+    if (saved.kind === "json") {
+        const headers = saved.entry.headers;
+        return headers && typeof headers === "object"
+            ? Object.fromEntries(Object.entries(headers)
+                .filter((entry) => {
+                return typeof entry[1] === "string";
+            })
+                .map(([key, value]) => [key, value]))
+            : {};
+    }
+    return parseCodexHeaders(saved.block);
+}
+function isLoopbackMcpUrl(value) {
+    if (!value)
+        return false;
+    try {
+        const url = new URL(value);
+        return (url.hostname === "localhost" ||
+            url.hostname === "127.0.0.1" ||
+            url.hostname === "::1" ||
+            url.hostname.startsWith("127."));
+    }
+    catch {
+        return false;
+    }
+}
+function decodeJwtSub(authHeader) {
+    if (!authHeader?.startsWith("Bearer "))
+        return undefined;
+    const token = authHeader.slice("Bearer ".length);
+    const [, payload] = token.split(".");
+    if (!payload)
+        return undefined;
+    try {
+        const normalized = payload.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = normalized.padEnd(normalized.length + ((4 - (normalized.length % 4)) % 4), "=");
+        const parsed = JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+        return typeof parsed.sub === "string" && parsed.sub.includes("@")
+            ? parsed.sub
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function ownerEmailFromEntry(saved) {
+    const headers = savedEntryHeaders(saved);
+    return (headers["X-Agent-Native-Owner-Email"] || decodeJwtSub(headers.Authorization));
+}
+function readEnvFile(file) {
+    try {
+        return fs.readFileSync(file, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+function readEnvValue(content, key) {
+    let found;
+    for (const line of content.split(/\r?\n/)) {
+        const match = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/i);
+        if (match?.[1] === key) {
+            found = match[2].replace(/^["']|["']$/g, "");
+        }
+    }
+    return found;
+}
+function workspaceEnvContent(baseDir) {
+    return (readEnvFile(path.join(baseDir, ".env.local")) +
+        "\n" +
+        readEnvFile(path.join(baseDir, ".env")));
+}
+function localAccessToken(baseDir) {
+    const content = workspaceEnvContent(baseDir);
+    const single = readEnvValue(content, "ACCESS_TOKEN");
+    if (single)
+        return single;
+    const multi = readEnvValue(content, "ACCESS_TOKENS");
+    return multi
+        ?.split(",")
+        .map((token) => token.trim())
+        .find(Boolean);
+}
+function localA2ASecret(baseDir) {
+    return (process.env.A2A_SECRET ||
+        readEnvValue(workspaceEnvContent(baseDir), "A2A_SECRET"));
+}
+async function mintLocalA2AToken(ownerEmail, baseDir) {
+    const secret = ownerEmail ? localA2ASecret(baseDir) : undefined;
+    if (!secret)
+        return undefined;
+    const jose = await import("jose");
+    return new jose.SignJWT({ sub: ownerEmail })
+        .setProtectedHeader({ alg: "HS256" })
+        .setIssuer("agent-native-connect-dev")
+        .setIssuedAt()
+        .setExpirationTime("30d")
+        .sign(new TextEncoder().encode(secret));
+}
+async function devHeadersForApp(params) {
+    const ownerEmail = params.ownerEmail ||
+        process.env.AGENT_NATIVE_OWNER_EMAIL ||
+        ownerEmailFromEntry(params.sourceEntry);
+    const headers = {};
+    const accessToken = localAccessToken(params.baseDir);
+    const a2aToken = accessToken
+        ? undefined
+        : await mintLocalA2AToken(ownerEmail, params.baseDir);
+    if (accessToken || a2aToken) {
+        headers.Authorization = `Bearer ${accessToken || a2aToken}`;
+    }
+    if (ownerEmail) {
+        headers["X-Agent-Native-Owner-Email"] = ownerEmail;
+    }
+    return Object.keys(headers).length ? headers : undefined;
+}
+function connectableApps(includeHidden = false) {
+    const source = includeHidden ? TEMPLATES : visibleTemplates();
+    return source
+        .filter((template) => typeof template.prodUrl === "string")
+        .map((template) => ({
+        name: template.name,
+        label: template.label,
+        url: template.prodUrl,
+        core: !!template.core,
+    }));
+}
+function profileDefaultApps() {
+    const core = connectableApps(false).filter((app) => app.core);
+    return core.length ? core : connectableApps(false);
+}
+function parseAppsList(value) {
+    return (value ?? "")
+        .split(",")
+        .map((app) => app.trim())
+        .filter(Boolean);
+}
+async function resolveProfileApps(parsed, deps) {
+    const allVisible = connectableApps(false);
+    const allIncludingHidden = connectableApps(true);
+    if (parsed.apps) {
+        const requested = parseAppsList(parsed.apps);
+        if (requested.includes("all"))
+            return allVisible;
+        const byName = new Map(allIncludingHidden.map((app) => [app.name, app]));
+        const unknown = requested.filter((name) => !byName.has(name));
+        if (unknown.length) {
+            throw new Error(`Unknown app(s): ${unknown.join(", ")}. Known apps: ${allIncludingHidden
+                .map((app) => app.name)
+                .join(", ")}`);
+        }
+        return requested.map((name) => byName.get(name));
+    }
+    if (parsed.all)
+        return allVisible;
+    if (shouldPrompt(deps)) {
+        const prompt = deps.promptHostedApps ?? promptForHostedApps;
+        const initialApps = profileDefaultApps().map((app) => app.name);
+        const selectedNames = normalizeHostedAppNames(await prompt({ apps: allVisible, initialApps }), allVisible);
+        if (selectedNames.length === 0)
+            return [];
+        const selected = new Set(selectedNames);
+        return allVisible.filter((app) => selected.has(app.name));
+    }
+    return profileDefaultApps();
+}
+function defaultDevGateway() {
+    if (process.env.WORKSPACE_GATEWAY_URL)
+        return process.env.WORKSPACE_GATEWAY_URL;
+    const port = process.env.WORKSPACE_PORT || process.env.PORT;
+    return port ? `http://127.0.0.1:${port}` : DEFAULT_DEV_GATEWAY;
+}
+function normalizeDevGateway(parsed) {
+    const raw = parsed.gateway ||
+        (Number.isFinite(parsed.port) && parsed.port
+            ? `http://127.0.0.1:${parsed.port}`
+            : defaultDevGateway());
+    const normalized = normalizeUrl(raw);
+    return normalized.replace(/\/+$/, "");
+}
+async function gatewayAppUrls(gatewayUrl, deps) {
+    const out = new Map();
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    try {
+        const response = await fetchImpl(`${gatewayUrl}/_workspace/apps`, {
+            signal: AbortSignal.timeout(1200),
+        });
+        if (!response.ok)
+            return out;
+        const apps = (await response.json());
+        if (!Array.isArray(apps))
+            return out;
+        for (const app of apps) {
+            if (!app || typeof app !== "object")
+                continue;
+            const id = app.id;
+            const url = app.url;
+            if (typeof id === "string" && typeof url === "string") {
+                out.set(id, normalizeUrl(url));
+            }
+        }
+    }
+    catch {
+        // The gateway may not be running yet; still write deterministic dev URLs.
+    }
+    return out;
+}
+function devMcpUrl(app, gatewayUrl, gatewayUrls) {
+    const base = gatewayUrls.get(app.name) ?? `${gatewayUrl}/${app.name}`;
+    return `${base.replace(/\/+$/, "")}/_agent-native/mcp`;
+}
+function serverNameForApp(app) {
+    return `${SERVER_NAME_PREFIX}-${app.name}`;
+}
+async function connectDevProfile(parsed, clients, deps) {
+    const apps = await resolveProfileApps(parsed, deps);
+    if (!apps || apps.length === 0)
+        return true;
+    const baseDir = projectBaseDir();
+    const scope = parsed.scope === "project" ? "project" : "user";
+    const gatewayUrl = normalizeDevGateway(parsed);
+    const gatewayUrls = await gatewayAppUrls(gatewayUrl, deps);
+    const profilesFile = deps.profilesFile ?? connectProfilesPath();
+    const profiles = readConnectProfiles(profilesFile);
+    const rows = [];
+    const ownerWarnings = new Set();
+    for (const app of apps) {
+        const serverName = serverNameForApp(app);
+        const mcpUrl = devMcpUrl(app, gatewayUrl, gatewayUrls);
+        for (const client of clients) {
+            const current = readCurrentMcpEntry(client, serverName, baseDir, scope);
+            const backup = savedProfileEntry(profiles, serverName, client, current.file);
+            if (current.saved && !isLoopbackMcpUrl(savedEntryUrl(current.saved))) {
+                setSavedProfileEntry(profiles, serverName, client, current.file, current.saved);
+            }
+            const sourceEntry = current.saved && !isLoopbackMcpUrl(savedEntryUrl(current.saved))
+                ? current.saved
+                : backup;
+            const headers = await devHeadersForApp({
+                ownerEmail: parsed.ownerEmail,
+                sourceEntry,
+                baseDir,
+            });
+            if (!headers?.["X-Agent-Native-Owner-Email"]) {
+                ownerWarnings.add(app.name);
+            }
+            const file = writeHttpEntryForClient(client, serverName, mcpUrl, undefined, baseDir, scope, headers);
+            rows.push({
+                app: app.name,
+                client,
+                status: "dev",
+                file,
+            });
+        }
+    }
+    writeConnectProfiles(profilesFile, profiles);
+    logOut("");
+    logOut(`  Switched ${apps.length} app(s) to dev via ${gatewayUrl}`);
+    for (const row of rows) {
+        logOut(`    ${row.app.padEnd(12)} ${row.client.padEnd(18)} ${row.file}`);
+    }
+    if (ownerWarnings.size) {
+        logOut("");
+        logOut(`  Tip: pass --owner-email <you@example.com> if local tools look sparse ` +
+            `for ${Array.from(ownerWarnings).join(", ")}.`);
+    }
+    logOut("");
+    logOut("  Restart your coding agent to pick up the dev MCP servers.");
+    return true;
+}
+async function connectProdProfile(parsed, clients, deps) {
+    const apps = await resolveProfileApps(parsed, deps);
+    if (!apps || apps.length === 0)
+        return true;
+    const baseDir = projectBaseDir();
+    const scope = parsed.scope === "project" ? "project" : "user";
+    const profilesFile = deps.profilesFile ?? connectProfilesPath();
+    const profiles = readConnectProfiles(profilesFile);
+    const restored = [];
+    const missing = [];
+    for (const app of apps) {
+        const serverName = serverNameForApp(app);
+        for (const client of clients) {
+            const file = configPathFor(client, baseDir, scope);
+            const saved = savedProfileEntry(profiles, serverName, client, file);
+            if (!saved) {
+                missing.push({ app: app.name, client });
+                continue;
+            }
+            writeSavedMcpEntry(client, file, serverName, saved);
+            restored.push({ app: app.name, client, file });
+        }
+    }
+    logOut("");
+    if (restored.length) {
+        logOut(`  Restored ${restored.length} production MCP entr${restored.length === 1 ? "y" : "ies"}.`);
+        for (const row of restored) {
+            logOut(`    ${row.app.padEnd(12)} ${row.client.padEnd(18)} ${row.file}`);
+        }
+    }
+    if (missing.length) {
+        logOut("");
+        logOut("  No saved production entry for:");
+        for (const row of missing) {
+            const app = apps.find((candidate) => candidate.name === row.app);
+            logOut(`    ${row.app.padEnd(12)} ${row.client.padEnd(18)} ` +
+                `run: agent-native connect ${app?.url ?? "<url>"} --client ${row.client}`);
+        }
+    }
+    logOut("");
+    logOut("  Restart your coding agent to pick up the production MCP servers.");
+    return missing.length === 0;
+}
 // ---------------------------------------------------------------------------
 // Single-app connect
 // ---------------------------------------------------------------------------
 async function connectOne(rawUrl, parsed, clients, deps) {
-    const baseUrl = normalizeUrl(rawUrl);
+    const normalizedUrl = normalizeUrl(rawUrl);
+    const baseUrl = stripMcpPath(normalizedUrl);
+    const normalizedMcpUrl = mcpUrlForBaseUrl(normalizedUrl);
     const appSlug = appSlugFromUrl(baseUrl);
     const scope = parsed.scope === "user" ? "user" : "project";
+    const baseDir = projectBaseDir();
+    const allWritten = [];
+    const oauthClients = parsed.token
+        ? []
+        : clients.filter((client) => supportsRemoteMcpOAuth(client));
+    const deviceFlowClients = parsed.token
+        ? clients
+        : clients.filter((client) => !supportsRemoteMcpOAuth(client));
+    const oauthMigrations = [];
     let token;
     let mcpUrl;
     let serverName;
@@ -497,13 +1044,18 @@ async function connectOne(rawUrl, parsed, clients, deps) {
     if (parsed.token) {
         // No-browser fallback: skip the device flow entirely.
         token = parsed.token;
-        mcpUrl = `${baseUrl}/_agent-native/mcp`;
+        mcpUrl = normalizedMcpUrl;
         serverName = parsed.name ?? defaultServerName(baseUrl);
         logOut("");
         logOut(`  Using supplied --token for ${baseUrl} (skipping browser flow).`);
     }
+    else if (deviceFlowClients.length === 0) {
+        token = undefined;
+        mcpUrl = normalizedMcpUrl;
+        serverName = parsed.name ?? defaultServerName(baseUrl);
+    }
     else {
-        const grant = await runDeviceFlow(baseUrl, appSlug, clientArgForDeviceFlow(clients), deps);
+        const grant = await runDeviceFlow(baseUrl, appSlug, clientArgForDeviceFlow(deviceFlowClients), deps);
         if (!grant)
             return { ok: false };
         token = grant.token;
@@ -511,15 +1063,40 @@ async function connectOne(rawUrl, parsed, clients, deps) {
         serverName = parsed.name ?? grant.serverName ?? defaultServerName(baseUrl);
         headers = grant.headers;
     }
-    const written = writeConfigs(clients, serverName, mcpUrl, token, scope, undefined, headers);
+    if (oauthClients.length > 0 && !parsed.token) {
+        if (!(await validateOAuthMcpServer(baseUrl, mcpUrl, deps))) {
+            return { ok: false };
+        }
+    }
+    if (deviceFlowClients.length > 0) {
+        allWritten.push(...writeConfigs(deviceFlowClients, serverName, mcpUrl, token, scope, baseDir, headers));
+    }
+    if (oauthClients.length > 0) {
+        for (const client of oauthClients) {
+            const current = readCurrentMcpEntry(client, serverName, baseDir, scope);
+            const currentHeaders = savedEntryHeaders(current.saved);
+            if (typeof currentHeaders.Authorization === "string") {
+                oauthMigrations.push(client);
+            }
+        }
+        allWritten.push(...writeConfigs(oauthClients, serverName, mcpUrl, undefined, scope, baseDir, undefined));
+    }
     logOut("");
-    logOut(`  Connected "${serverName}" → ${mcpUrl}`);
-    for (const w of written) {
+    logOut(`  Configured "${serverName}" → ${mcpUrl}`);
+    for (const w of allWritten) {
         logOut(`    ${w.client.padEnd(18)} ${w.file}`);
     }
+    if (oauthClients.length > 0 && !parsed.token) {
+        logOut("");
+        if (oauthMigrations.length > 0) {
+            logOut(`  Replaced legacy bearer headers for ${clientLabelList(oauthMigrations)}; it will reconnect with standard MCP OAuth.`);
+        }
+        logOut(`  ${clientLabelList(oauthClients)}: wrote URL-only MCP config (no bearer headers).`);
+        logOut("  Next: restart Claude Code, run /mcp, and choose Authenticate.");
+    }
     logOut("");
     logOut("  Restart your coding agent to pick up the new MCP server.");
-    return { ok: true, serverName, files: written.map((w) => w.file) };
+    return { ok: true, serverName, files: allWritten.map((w) => w.file) };
 }
 // ---------------------------------------------------------------------------
 // --all : connect every first-party hosted app
@@ -580,11 +1157,15 @@ Usage:
       (mail.agent-native.com, calendar.agent-native.com, and friends).
 
   agent-native connect <url> [--client <c>] [--scope user|project] [--name <n>]
-      Browser device-code flow. Prints a code, opens the verification URL,
-      polls until approved, then writes the HTTP MCP entry into your
-      selected client config(s). With no --client, opens a brief picker
-      preselected from ~/.agent-native/connect.json, or all clients on first
-      run. Idempotent — re-running replaces the same entry.
+      Writes the HTTP MCP entry into your selected client config(s). Claude
+      Code / Claude Code CLI use standard remote MCP OAuth: restart Claude,
+      run /mcp, and choose Authenticate. Codex / Cowork use the browser
+      device-code fallback: the command prints a code, opens the verification
+      URL, polls until approved, then writes bearer headers. With no --client,
+      opens a brief picker preselected from ~/.agent-native/connect.json, or
+      all clients on first run. Idempotent — re-running replaces the same entry.
+      Re-running over an older Claude bearer entry upgrades it to URL-only
+      OAuth config and prompts you to authenticate with /mcp.
 
   agent-native connect <url> --token <token>
       No-browser fallback. Skip the device flow and write the entry with
@@ -593,6 +1174,14 @@ Usage:
   agent-native connect --all [--client <c>] [--scope user|project]
       Connect every first-party hosted app at once.
 
+Developer:
+  agent-native connect dev [--apps mail,calendar] [--client <c>]
+      Switch selected first-party MCP entries to a local dev-lazy gateway.
+      Defaults to ${DEFAULT_DEV_GATEWAY}; override with --gateway or --port.
+
+  agent-native connect prod [--apps mail,calendar] [--client <c>]
+      Restore production MCP entries saved before the dev switch.
+
 Clients:  all (default), claude-code, claude-code-cli, codex, cowork
 Scope:    user (default, ~/.claude.json) or project (.mcp.json)`;
 /**
@@ -610,6 +1199,17 @@ export async function runConnect(args, deps = {}) {
     }
     const parsed = parseConnectArgs(args);
     try {
+        if (parsed.mode) {
+            const clients = await resolveConnectClients(parsed, deps);
+            if (!clients)
+                return;
+            const ok = parsed.mode === "dev"
+                ? await connectDevProfile(parsed, clients, deps)
+                : await connectProdProfile(parsed, clients, deps);
+            if (!ok)
+                process.exitCode = 1;
+            return;
+        }
         if (parsed.all) {
             const clients = await resolveConnectClients(parsed, deps);
             if (!clients)