@agent-native/core 0.98.17 → 0.99.1

package/corpus/core/src/mcp/builtin-tools.ts

@@ -88,14 +88,23 @@ const ASK_APP_TERMINAL_STATES = new Set<string>([
   "completed",
   "failed",
   "canceled",
+  "input-required",
 ]);
 
+class AskAppInlineDeadlineError extends Error {
+  constructor() {
+    super("ask_app inline wait deadline reached");
+    this.name = "AskAppInlineDeadlineError";
+  }
+}
+
 type AskAppRequestMeta = { origin?: string; basePath?: string };
 
 interface AskAppRoute {
   app: string;
   origin: string;
   routedVia: "local" | "a2a";
+  requestOrigin?: string;
   note?: string;
 }
 
@@ -106,7 +115,9 @@ interface AskAppTaskResult {
   status: string;
   response?: string;
   error?: string;
+  inputRequired?: string;
   note?: string;
+  pollAfterMs?: number;
   poll?: {
     tool: "ask_app_status";
     arguments: { app: string; taskId: string };
@@ -236,8 +247,20 @@ function askAppTaskResult(route: AskAppRoute, task: Task): AskAppTaskResult {
     };
   }
 
+  if (status === "input-required") {
+    const inputRequired =
+      response || "The agent needs additional input before it can continue.";
+    return {
+      ...base,
+      response: inputRequired,
+      inputRequired,
+      message: inputRequired,
+    };
+  }
+
   return {
     ...base,
+    pollAfterMs: ASK_APP_POLL_INTERVAL_MS,
     poll: {
       tool: "ask_app_status",
       arguments: { app: route.app, taskId: task.id },
@@ -248,7 +271,57 @@ function askAppTaskResult(route: AskAppRoute, task: Task): AskAppTaskResult {
   };
 }
 
-async function createA2AClientForAskApp(origin: string): Promise<{
+/**
+ * Same shape as `askAppTaskResult`, but built from an in-process
+ * `ask-app-inline-tasks.ts` snapshot instead of an A2A `Task` — used by the
+ * no-origin fallback (no A2A task exists to describe). Kept field-for-field
+ * identical so `ask_app` / `ask_app_status` callers can't tell which backing
+ * store answered.
+ */
+function askAppInlineTaskResult(
+  selfId: string,
+  taskId: string,
+  inline: {
+    status: "working" | "completed" | "failed";
+    response?: string;
+    error?: string;
+  },
+  note?: string,
+): AskAppTaskResult {
+  const base = {
+    app: selfId,
+    routedVia: "local" as const,
+    taskId,
+    status: inline.status,
+    ...(note ? { note } : {}),
+  };
+
+  if (inline.status === "completed") {
+    return { ...base, response: inline.response || "(no response)" };
+  }
+
+  if (inline.status === "failed") {
+    return { ...base, error: inline.error || "ask_app task failed." };
+  }
+
+  return {
+    ...base,
+    pollAfterMs: ASK_APP_POLL_INTERVAL_MS,
+    poll: {
+      tool: "ask_app_status",
+      arguments: { app: selfId, taskId },
+    },
+    message:
+      `ask_app is still ${inline.status}. Call ask_app_status with ` +
+      `taskId "${taskId}" to retrieve the final response.`,
+  };
+}
+
+async function createA2AClientForAskApp(
+  origin: string,
+  requestOrigin?: string,
+  deadline?: number,
+): Promise<{
   client: import("../a2a/client.js").A2AClient;
   metadata: Record<string, unknown>;
 }> {
@@ -258,9 +331,14 @@ async function createA2AClientForAskApp(origin: string): Promise<{
   const metadata: Record<string, unknown> = {};
   if (auth.userEmail) metadata.userEmail = auth.userEmail;
   if (auth.orgDomain) metadata.orgDomain = auth.orgDomain;
+  if (requestOrigin) metadata.requestOrigin = requestOrigin;
+  const remainingMs = deadline == null ? null : deadline - Date.now();
   return {
     client: new A2AClient(origin, auth.apiKey, {
-      requestTimeoutMs: ASK_APP_A2A_REQUEST_TIMEOUT_MS,
+      requestTimeoutMs:
+        remainingMs == null
+          ? ASK_APP_A2A_REQUEST_TIMEOUT_MS
+          : Math.max(1, Math.min(ASK_APP_A2A_REQUEST_TIMEOUT_MS, remainingMs)),
       ...(auth.apiKeyFallbacks
         ? { fallbackApiKeys: auth.apiKeyFallbacks }
         : {}),
@@ -269,13 +347,35 @@ async function createA2AClientForAskApp(origin: string): Promise<{
   };
 }
 
+async function runBeforeAskAppDeadline<T>(
+  operation: () => Promise<T>,
+  deadline: number,
+): Promise<T> {
+  const remainingMs = deadline - Date.now();
+  if (remainingMs <= 0) throw new AskAppInlineDeadlineError();
+
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      operation(),
+      new Promise<T>((_resolve, reject) => {
+        timeout = setTimeout(
+          () => reject(new AskAppInlineDeadlineError()),
+          remainingMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
 async function waitForA2ATask(
   client: import("../a2a/client.js").A2AClient,
   initialTask: Task,
-  maxWaitMs: number,
+  deadline: number | undefined,
 ): Promise<Task> {
-  if (maxWaitMs <= 0 || isTerminalTask(initialTask)) return initialTask;
-  const deadline = Date.now() + maxWaitMs;
+  if (deadline == null || isTerminalTask(initialTask)) return initialTask;
   let current = initialTask;
 
   while (!isTerminalTask(current)) {
@@ -284,13 +384,16 @@ async function waitForA2ATask(
     await new Promise((resolve) =>
       setTimeout(resolve, Math.min(ASK_APP_POLL_INTERVAL_MS, remaining)),
     );
+    if (Date.now() >= deadline) return current;
     try {
-      current = await client.getTask(initialTask.id);
-    } catch {
-      // Transient status fetch failures should not turn a successfully
-      // submitted durable task into a failed MCP call.
+      current = await runBeforeAskAppDeadline(
+        () => client.getTask(initialTask.id),
+        deadline,
+      );
+    } catch (err) {
+      if (err instanceof AskAppInlineDeadlineError) return current;
+      if (!isTransientAskAppStatusError(err)) throw err;
       if (Date.now() >= deadline) return current;
-      continue;
     }
   }
 
@@ -302,7 +405,12 @@ async function submitAskAppA2ATask(
   message: string,
   maxWaitMs: number,
 ): Promise<AskAppTaskResult> {
-  const { client, metadata } = await createA2AClientForAskApp(route.origin);
+  const deadline = maxWaitMs > 0 ? Date.now() + maxWaitMs : undefined;
+  const { client, metadata } = await createA2AClientForAskApp(
+    route.origin,
+    route.requestOrigin,
+    deadline,
+  );
   const task = await client.send(
     {
       role: "user",
@@ -313,7 +421,7 @@ async function submitAskAppA2ATask(
       metadata,
     },
   );
-  const finalOrRunning = await waitForA2ATask(client, task, maxWaitMs);
+  const finalOrRunning = await waitForA2ATask(client, task, deadline);
   return askAppTaskResult(route, finalOrRunning);
 }
 
@@ -778,13 +886,22 @@ async function routeAskOverA2A(
   origin: string,
   id: string,
   message: string,
-  options?: { durable?: boolean; maxWaitMs?: number },
+  options?: {
+    durable?: boolean;
+    maxWaitMs?: number;
+    requestOrigin?: string;
+  },
 ): Promise<
   { app: string; routedVia: "a2a"; response: string } | AskAppTaskResult
 > {
   if (options?.durable) {
     return submitAskAppA2ATask(
-      { app: id, origin: agentNativeA2AEndpoint(origin), routedVia: "a2a" },
+      {
+        app: id,
+        origin: agentNativeA2AEndpoint(origin),
+        routedVia: "a2a",
+        requestOrigin: options.requestOrigin ?? origin,
+      },
       message,
       options.maxWaitMs ?? ASK_APP_DEFAULT_INLINE_WAIT_MS,
     );
@@ -801,6 +918,7 @@ async function routeAskOverA2A(
     userEmail: auth.userEmail,
     orgDomain: auth.orgDomain,
     orgSecret: auth.orgSecret,
+    requestOrigin: options?.requestOrigin,
     // Bound the wait — cross-app A2A polls async by default.
     timeoutMs: 5 * 60_000,
   });
@@ -822,7 +940,12 @@ async function resolveAskAppStatusRoute(
         "ask_app_status requires a running app origin for local tasks.",
       );
     }
-    return { app: selfId, origin: selfEndpointUrl, routedVia: "local" };
+    return {
+      app: selfId,
+      origin: selfEndpointUrl,
+      routedVia: "local",
+      requestOrigin: requestMeta?.origin,
+    };
   }
 
   const targetApp = await resolveTargetAppOrigin(config, requestedApp);
@@ -831,6 +954,7 @@ async function resolveAskAppStatusRoute(
       app: targetApp.id,
       origin: agentNativeA2AEndpoint(targetApp.origin),
       routedVia: "a2a",
+      requestOrigin: targetApp.origin,
     };
   }
 
@@ -841,6 +965,7 @@ async function resolveAskAppStatusRoute(
       app: dirMatch.id,
       origin: agentNativeA2AEndpoint(dirMatch.a2aUrl),
       routedVia: "a2a",
+      requestOrigin: dirMatch.url,
     };
   }
 
@@ -914,6 +1039,7 @@ function askAppTool(
             {
               durable: useDurableA2A,
               maxWaitMs,
+              requestOrigin: targetApp.origin,
             },
           );
         } catch (err: any) {
@@ -947,6 +1073,7 @@ function askAppTool(
               {
                 durable: useDurableA2A,
                 maxWaitMs,
+                requestOrigin: dirMatch.url,
               },
             );
           } catch (err: any) {
@@ -988,6 +1115,7 @@ function askAppTool(
             app: selfId,
             origin: localA2AEndpointUrl,
             routedVia: "local",
+            requestOrigin: requestMeta?.origin,
             ...(note ? { note } : {}),
           },
           message,
@@ -995,13 +1123,35 @@ function askAppTool(
         );
       }
 
-      const response = await config.askAgent(message);
-      return {
-        app: selfId,
-        routedVia: "local",
-        ...(note ? { note } : {}),
-        response,
-      };
+      // No derivable app origin at all (e.g. stdio / no request context) —
+      // there is no `/_agent-native/a2a` endpoint to submit a durable task
+      // to either. Bound the wait against a process-local task map instead
+      // of awaiting config.askAgent() unbounded, so a slow agent run can't
+      // hold this MCP call open indefinitely. Settling in time keeps the
+      // original response shape; timing out returns the same still-working
+      // poll payload the A2A path would, using the same taskId contract
+      // (see ask-app-inline-tasks.ts).
+      const { startAskAppInlineTask } =
+        await import("./ask-app-inline-tasks.js");
+      const inline = await startAskAppInlineTask(
+        config.askAgent,
+        message,
+        maxWaitMs,
+      );
+      if (inline.status === "completed") {
+        return {
+          app: selfId,
+          routedVia: "local",
+          ...(note ? { note } : {}),
+          response: inline.response || "(no response)",
+        };
+      }
+      if (inline.status === "failed") {
+        // Settled with an error inside the bounded wait — surface it the
+        // same way the old unbounded `await config.askAgent(message)` did.
+        throw new Error(inline.error || "ask_app task failed.");
+      }
+      return askAppInlineTaskResult(selfId, inline.taskId, inline, note);
     },
   };
 }
@@ -1031,6 +1181,20 @@ function askAppStatusTool(
     run: async (args: Record<string, any>) => {
       const taskId = String(args.taskId ?? "").trim();
       if (!taskId) throw new Error("ask_app_status requires 'taskId'.");
+
+      // The no-derivable-origin ask_app fallback tracks its tasks in a
+      // process-local map, not the durable A2A store. Check it FIRST —
+      // before any origin requirement — so a taskId minted by that fallback
+      // never has to satisfy `resolveAskAppStatusRoute`'s "running app
+      // origin" check. Falls through to the normal A2A route when the id
+      // isn't one of these (never started here, evicted, or an ordinary A2A
+      // task id).
+      const { getAskAppInlineTask } = await import("./ask-app-inline-tasks.js");
+      const inline = getAskAppInlineTask(taskId);
+      if (inline) {
+        return askAppInlineTaskResult(currentAppId(config), taskId, inline);
+      }
+
       const requestedApp = String(args.app ?? "").trim();
       const route = await resolveAskAppStatusRoute(
         config,

package/corpus/core/src/mcp/connect-route.ts

@@ -1,20 +1,21 @@
 /**
- * `/_agent-native/mcp/connect` — frictionless external-agent connection.
+ * `/mcp/connect` — frictionless external-agent connection. The legacy
+ * `/_agent-native/mcp/connect` alias is mounted by the core route plugin.
  *
  * A logged-in user on a deployed agent-native app (e.g. mail.agent-native.com)
  * mints a per-user, scoped, revocable MCP bearer token WITHOUT ever copying a
  * shared deployment secret. Two surfaces:
  *
- *   1. Browser  — `GET /connect` renders a minimal in-app page (same inline
+ *   1. Browser  — `GET /mcp/connect` renders a minimal in-app page (same inline
  *      HTML approach as the auth pages). The Authorize button POSTs to
  *      `/connect/token`, then shows the ready-to-paste `.mcp.json` entry, the
  *      `agent-native connect <origin>` one-liner, and the user's existing
  *      tokens with Revoke buttons.
  *   2. CLI      — an OAuth-2.0-device-authorization-style flow:
- *        POST /connect/device/start      (unauth)  → device_code + user_code
- *        GET  /connect?user_code=…       (browser) → user signs in & approves
- *        POST /connect/device/authorize  (session) → binds user to the code
- *        POST /connect/device/poll       (unauth)  → mints + returns the token
+ *        POST /mcp/connect/device/start      (unauth)  → device_code + user_code
+ *        GET  /mcp/connect?user_code=…       (browser) → user signs in & approves
+ *        POST /mcp/connect/device/authorize  (session) → binds user to the code
+ *        POST /mcp/connect/device/poll       (unauth)  → mints + returns the token
  *
  * When A2A_SECRET exists, the minted token reuses the existing A2A signer
  * (`signA2AToken`) and adds a random `jti` + `scope: "mcp-connect"` claim so
@@ -64,6 +65,7 @@ import {
   MCP_OAUTH_DEFAULT_SCOPE,
   signMcpOAuthAccessToken,
 } from "./oauth-token.js";
+import { MCP_PUBLIC_ROUTE_PREFIX } from "./route-paths.js";
 
 /** Device-flow poll interval hint (seconds). */
 const DEVICE_POLL_INTERVAL_S = 3;
@@ -383,7 +385,7 @@ function mcpResultPayload(
 }
 
 function mcpResourceUrl(appUrl: string): string {
-  return `${appUrl}/_agent-native/mcp`;
+  return `${appUrl}${MCP_PUBLIC_ROUTE_PREFIX}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -415,7 +417,7 @@ function renderConnectPage(params: {
     params;
   const safeEmail = escapeHtml(email);
   const safeApp = escapeHtml(appName);
-  const mcpUrl = `${appUrl}/_agent-native/mcp`;
+  const mcpUrl = `${appUrl}${MCP_PUBLIC_ROUTE_PREFIX}`;
   const safeMcpUrl = escapeHtml(mcpUrl);
   const safeServerId = escapeHtml(serverId);
   const safeClaudeCodeCmd = escapeHtml(
@@ -948,7 +950,7 @@ function renderConnectPage(params: {
 </div>
 <script>
 (function () {
-  var BASE = ${JSON.stringify(joinAppPath(connectBasePath, "/_agent-native/mcp/connect"))};
+  var BASE = ${JSON.stringify(joinAppPath(connectBasePath, MCP_PUBLIC_ROUTE_PREFIX + "/connect"))};
   var USER_CODE = ${JSON.stringify(safeUserCode || null)};
   var msgEl = document.getElementById("msg");
   var connectionsEl = document.getElementById("connections");
@@ -1182,10 +1184,11 @@ function renderConnectPage(params: {
 // ---------------------------------------------------------------------------
 
 /**
- * Handle a `/_agent-native/mcp/connect[...]` request. `subpath` is the part
- * after `/connect` (empty string = the page itself, otherwise e.g.
- * `/token`, `/device/start`). The core-routes-plugin computes it from the
- * stripped event path so this module stays mount-agnostic.
+ * Handle a `/mcp/connect[...]` request. The legacy
+ * `/_agent-native/mcp/connect` alias is mounted too. `subpath` is the part
+ * after `/connect` (empty string = the page itself, otherwise e.g. `/token`,
+ * `/device/start`). The core-routes-plugin computes it from the stripped event
+ * path so this module stays mount-agnostic.
  */
 export async function handleMcpConnect(
   event: H3Event,
@@ -1291,7 +1294,7 @@ export async function handleMcpConnect(
     if (method !== "POST") return json({ error: "Method not allowed" }, 405);
     try {
       const row = await createDeviceCode();
-      const verificationUri = `${appUrl}/_agent-native/mcp/connect`;
+      const verificationUri = `${appUrl}${MCP_PUBLIC_ROUTE_PREFIX}/connect`;
       return json({
         device_code: row.deviceCode,
         user_code: row.userCode,

package/corpus/core/src/mcp/oauth-route.ts

@@ -3,7 +3,7 @@
  *
  * These routes let MCP hosts such as Claude Code and ChatGPT authenticate
  * through their native remote-MCP OAuth flow instead of pasting bearer tokens.
- * The issued access tokens are audience-bound to `/_agent-native/mcp`, carry
+ * The issued access tokens are audience-bound to `/mcp`, carry
  * the same user/org identity as the existing connect flow, and are mediated by
  * `verifyAuth` before any MCP tool/resource request runs.
  */
@@ -35,6 +35,7 @@ import {
   normalizeOAuthScope,
   signMcpOAuthAccessToken,
 } from "./oauth-token.js";
+import { MCP_PUBLIC_ROUTE_PREFIX, MCP_ROUTE_PREFIXES } from "./route-paths.js";
 
 export interface McpOAuthRouteOptions {
   appId?: string;
@@ -172,7 +173,16 @@ export function getMcpOAuthIssuer(event: H3Event): string | undefined {
 export function getMcpOAuthResource(event: H3Event): string | undefined {
   const issuer = getMcpOAuthIssuer(event);
   if (!issuer) return undefined;
-  return `${issuer}/_agent-native/mcp`;
+  return `${issuer}${MCP_PUBLIC_ROUTE_PREFIX}`;
+}
+
+function mcpResourcesForIssuer(issuer: string): string[] {
+  return [
+    MCP_PUBLIC_ROUTE_PREFIX,
+    ...MCP_ROUTE_PREFIXES.filter(
+      (prefix) => prefix !== MCP_PUBLIC_ROUTE_PREFIX,
+    ),
+  ].map((prefix) => `${issuer}${prefix}`);
 }
 
 /**
@@ -185,18 +195,21 @@ export function getMcpOAuthResource(event: H3Event): string | undefined {
  * accepts either without issuing a 401.
  */
 export function getMcpOAuthAudiences(event: H3Event): string[] {
-  const derived = getMcpOAuthResource(event);
-  const configured = (() => {
+  const configuredIssuer = (() => {
     const base = configuredPublicBaseUrl();
     if (!base) return undefined;
     // Re-apply base path if present so the configured resource is also
     // base-path-aware, consistent with how getMcpOAuthResource computes it.
-    const withPath = appendConfiguredBasePath(base);
-    return `${withPath}/_agent-native/mcp`;
+    return appendConfiguredBasePath(base);
   })();
   const seen = new Set<string>();
   const out: string[] = [];
-  for (const r of [derived, configured]) {
+  for (const r of [
+    ...(getMcpOAuthIssuer(event)
+      ? mcpResourcesForIssuer(getMcpOAuthIssuer(event) as string)
+      : []),
+    ...(configuredIssuer ? mcpResourcesForIssuer(configuredIssuer) : []),
+  ]) {
     const n = r?.replace(/\/+$/, "");
     if (n && !seen.has(n)) {
       seen.add(n);
@@ -224,17 +237,21 @@ export function buildMcpOAuthChallenge(event: H3Event): string {
 
 function authorizationEndpoint(event: H3Event): string | undefined {
   const issuer = getMcpOAuthIssuer(event);
-  return issuer ? `${issuer}/_agent-native/mcp/oauth/authorize` : undefined;
+  return issuer
+    ? `${issuer}${MCP_PUBLIC_ROUTE_PREFIX}/oauth/authorize`
+    : undefined;
 }
 
 function tokenEndpoint(event: H3Event): string | undefined {
   const issuer = getMcpOAuthIssuer(event);
-  return issuer ? `${issuer}/_agent-native/mcp/oauth/token` : undefined;
+  return issuer ? `${issuer}${MCP_PUBLIC_ROUTE_PREFIX}/oauth/token` : undefined;
 }
 
 function registrationEndpoint(event: H3Event): string | undefined {
   const issuer = getMcpOAuthIssuer(event);
-  return issuer ? `${issuer}/_agent-native/mcp/oauth/register` : undefined;
+  return issuer
+    ? `${issuer}${MCP_PUBLIC_ROUTE_PREFIX}/oauth/register`
+    : undefined;
 }
 
 export function handleMcpOAuthProtectedResourceMetadata(
@@ -707,8 +724,11 @@ async function handleAuthorize(
   const state = params.state;
   const clientId = params.client_id;
   const redirectUri = params.redirect_uri;
-  const resource = params.resource || getMcpOAuthResource(event);
-  const expectedResource = getMcpOAuthResource(event);
+  const resource = (params.resource || getMcpOAuthResource(event))?.replace(
+    /\/+$/,
+    "",
+  );
+  const expectedResources = getMcpOAuthAudiences(event);
 
   if (params.response_type !== "code") {
     return oauthError(
@@ -716,7 +736,12 @@ async function handleAuthorize(
       "response_type must be code",
     );
   }
-  if (!clientId || !redirectUri || !resource || resource !== expectedResource) {
+  if (
+    !clientId ||
+    !redirectUri ||
+    !resource ||
+    !expectedResources.includes(resource)
+  ) {
     return oauthError("invalid_request", "Invalid OAuth authorization request");
   }
   if (params.code_challenge_method !== "S256" || !params.code_challenge) {

package/corpus/core/src/mcp/route-paths.ts

@@ -0,0 +1,34 @@
+/**
+ * MCP's public protocol path and the framework path kept for compatibility.
+ *
+ * Only the protocol and its OAuth/connect companions use the public alias.
+ * Other framework-owned MCP management routes remain under `/_agent-native`.
+ */
+export const MCP_PUBLIC_ROUTE_PREFIX = "/mcp";
+export const MCP_LEGACY_ROUTE_PREFIX = "/_agent-native/mcp";
+
+export const MCP_ROUTE_PREFIXES = [
+  MCP_LEGACY_ROUTE_PREFIX,
+  MCP_PUBLIC_ROUTE_PREFIX,
+] as const;
+
+export function joinMcpRoute(prefix: string, suffix: string): string {
+  const normalizedSuffix = suffix.startsWith("/") ? suffix : `/${suffix}`;
+  return `${prefix}${normalizedSuffix}` || normalizedSuffix;
+}
+
+export function isMcpPublicPath(pathname: string): boolean {
+  return (
+    pathname === MCP_PUBLIC_ROUTE_PREFIX ||
+    pathname.startsWith(`${MCP_PUBLIC_ROUTE_PREFIX}/`)
+  );
+}
+
+export function isMcpProtocolPath(pathname: string): boolean {
+  return (
+    pathname === MCP_PUBLIC_ROUTE_PREFIX ||
+    pathname === MCP_LEGACY_ROUTE_PREFIX ||
+    pathname === `${MCP_PUBLIC_ROUTE_PREFIX}/` ||
+    pathname === `${MCP_LEGACY_ROUTE_PREFIX}/`
+  );
+}

package/corpus/core/src/mcp/server.ts

@@ -28,6 +28,11 @@ import {
   getMcpOAuthProtectedResourceMetadataUrl,
   getMcpOAuthResource,
 } from "./oauth-route.js";
+import {
+  MCP_PUBLIC_ROUTE_PREFIX,
+  MCP_ROUTE_PREFIXES,
+  joinMcpRoute,
+} from "./route-paths.js";
 
 // Re-export the shared MCP server builder + types so the stdio transport and
 // any (future) external importer of `@agent-native/core/mcp` keep resolving
@@ -183,7 +188,7 @@ function buildWebRequest(event: H3Event, method: string): Request {
     forwardedProto?.split(",")[0]?.trim() ||
     (/^(localhost|127\.0\.0\.1)(:|$)/.test(host) ? "http" : "https");
   const basePath = getConfiguredAppBasePath();
-  const url = `${proto}://${host}${basePath}/_agent-native/mcp`;
+  const url = `${proto}://${host}${basePath}${MCP_PUBLIC_ROUTE_PREFIX}`;
 
   // No body here on purpose: the JSON-RPC payload is forwarded via the
   // transport's `parsedBody` option (the same mechanism the Node transport
@@ -220,7 +225,7 @@ function buildUnauthorizedBody(event: H3Event): {
     ? `npx @agent-native/core@latest connect ${issuer}`
     : undefined;
   const authorizeUrl = issuer
-    ? `${issuer}/_agent-native/mcp/oauth/authorize`
+    ? `${issuer}${MCP_PUBLIC_ROUTE_PREFIX}/oauth/authorize`
     : undefined;
   const message = command
     ? `Authentication required. Run \`${command}\` to re-authenticate this ` +
@@ -454,7 +459,8 @@ export async function handleMcpRequest(
 /**
  * Mount an MCP remote server on an H3/Nitro app.
  *
- * Endpoint: `{routePrefix}/mcp` (default `/_agent-native/mcp`)
+ * Endpoints: `/mcp` (public) and `/_agent-native/mcp` (compatibility).
+ * A custom route prefix only mounts that custom endpoint.
  *
  * Uses stateless Streamable HTTP transport — no in-memory sessions, JSON
  * request/response (no SSE), and no standalone GET stream, so it survives
@@ -473,15 +479,20 @@ export function mountMCP(
   config: MCPConfig,
   routePrefix = "/_agent-native",
 ): void {
-  getH3App(nitroApp).use(
-    `${routePrefix}/mcp`,
-    defineEventHandler(async (event) => {
-      return handleMcpRequest(event as H3Event, config);
-    }),
-  );
+  const routePaths =
+    routePrefix === "/_agent-native"
+      ? [...MCP_ROUTE_PREFIXES]
+      : [joinMcpRoute(routePrefix, "/mcp")];
+  const handler = defineEventHandler(async (event) => {
+    return handleMcpRequest(event as H3Event, config);
+  });
+
+  for (const routePath of routePaths) {
+    getH3App(nitroApp).use(routePath, handler);
+  }
 
   if (process.env.DEBUG)
     console.log(
-      `[mcp] Mounted MCP server at ${routePrefix}/mcp (${Object.keys(config.actions).length} tools${config.askAgent ? " + ask-agent" : ""})`,
+      `[mcp] Mounted MCP server at ${routePaths.join(" and ")} (${Object.keys(config.actions).length} tools${config.askAgent ? " + ask-agent" : ""})`,
     );
 }