@agent-native/core 0.21.0 → 0.22.1

package/dist/cli/connect.d.ts

@@ -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]
@@ -82,6 +83,7 @@ export interface ConnectHostedAppsPromptContext {
     apps: HostedApp[];
     initialApps: string[];
 }
+export declare function supportsRemoteMcpOAuth(client: ClientId): boolean;
 /** Injectable hooks so the poll state machine is unit-testable. */
 export interface ConnectDeps {
     /** Defaults to global fetch. */

package/dist/cli/connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/cli/connect.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/cli/connect.ts"],"names":[],"mappings":"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"}

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]
@@ -35,6 +36,7 @@ import { CLIENTS, configPathFor, writeCodexBlock, writeHttpEntryForClient, write
 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;
@@ -51,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`);
 }
@@ -306,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 {
@@ -377,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.
@@ -956,9 +1023,20 @@ async function connectProdProfile(parsed, clients, deps) {
 // 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;
@@ -966,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;
@@ -980,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
@@ -1049,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