@agent-native/core 0.98.17 → 0.99.0

package/corpus/core/src/a2a/client.ts

@@ -540,6 +540,8 @@ export async function callAgent(
     userEmail?: string;
     orgDomain?: string;
     orgSecret?: string;
+    /** Origin used to build links back to the receiving app. */
+    requestOrigin?: string;
     /**
      * Use async/poll instead of a single blocking POST. Recommended for
      * cross-app calls that may exceed a synchronous serverless request budget.
@@ -571,6 +573,7 @@ export async function callAgent(
   const metadata: Record<string, unknown> = {};
   if (opts?.userEmail) metadata.userEmail = opts.userEmail;
   if (opts?.orgDomain) metadata.orgDomain = opts.orgDomain;
+  if (opts?.requestOrigin) metadata.requestOrigin = opts.requestOrigin;
 
   // Default to async + poll. The receiving A2A server's `_process-task` route
   // runs the handler in a fresh function execution (cross-platform queue

package/corpus/core/src/a2a/handlers.ts

@@ -8,6 +8,7 @@ import {
   resolveAgentChatProcessRunDispatchPath,
 } from "../agent/durable-background.js";
 import { withConfiguredAppBasePath } from "../server/app-base-path.js";
+import { getOrigin, isConfiguredAppOrigin } from "../server/google-oauth.js";
 import { fireInternalDispatch } from "../server/self-dispatch.js";
 import { agentChat } from "../shared/agent-chat.js";
 import {
@@ -46,6 +47,70 @@ const A2A_QUEUED_DISPATCH_STUCK_AFTER_MS = 10_000;
 const A2A_PROCESSING_STUCK_AFTER_MS = 5 * 60 * 1000;
 const A2A_PROCESSING_HEARTBEAT_MS = 30_000;
 
+/**
+ * Request origin is routing/link context, not an identity signal. Accept only
+ * an absolute HTTP(S) origin from caller metadata so queued runs can preserve
+ * custom-domain/workspace links without allowing arbitrary values to leak
+ * into browser or artifact URLs.
+ */
+function requestOriginFromMetadata(
+  metadata: Record<string, unknown> | undefined,
+): string | undefined {
+  const raw = metadata?.requestOrigin;
+  if (typeof raw !== "string" || !raw.trim()) return undefined;
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
+    return url.origin;
+  } catch {
+    return undefined;
+  }
+}
+
+function requestOriginFromEvent(event: any | undefined): string | undefined {
+  if (!event) return undefined;
+  try {
+    return requestOriginFromMetadata({
+      requestOrigin: getOrigin(event as any),
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Prefer the origin resolved from the receiving request. A distinct public
+ * browser origin is allowed only when the receiver configured it explicitly;
+ * arbitrary caller metadata must not steer links or service-token URLs.
+ */
+function requestOriginForContext(
+  metadata: Record<string, unknown> | undefined,
+  event: any | undefined,
+): string | undefined {
+  if (!event) return undefined;
+  const receiverOrigin = requestOriginFromEvent(event);
+  const metadataOrigin = requestOriginFromMetadata(metadata);
+  if (
+    metadataOrigin &&
+    (metadataOrigin === receiverOrigin || isConfiguredAppOrigin(metadataOrigin))
+  ) {
+    return metadataOrigin;
+  }
+  return receiverOrigin;
+}
+
+function trustedA2AMetadata(
+  metadata: Record<string, unknown> | undefined,
+  event: any | undefined,
+): Record<string, unknown> | undefined {
+  if (!metadata) return undefined;
+  const trusted = { ...metadata };
+  const requestOrigin = requestOriginForContext(metadata, event);
+  if (requestOrigin) trusted.requestOrigin = requestOrigin;
+  else delete trusted.requestOrigin;
+  return trusted;
+}
+
 /**
  * Hard cap on how long a task may sit in submitted/working (never reaching
  * `processing`) before the dispatch-retry loop in
@@ -172,6 +237,12 @@ export async function processA2ATaskFromQueue(
   const processorMeta = (meta.__a2a_processor ?? {}) as Record<string, unknown>;
   const verifiedEmail = processorMeta.verifiedEmail as string | undefined;
   const orgDomainHint = processorMeta.orgDomainHint as string | undefined;
+  // The processor metadata was created by the authenticated inbound handler
+  // from that request's resolved origin. Prefer it over the processor event,
+  // whose host may be an internal worker/dispatch origin. Legacy tasks that
+  // predate this metadata fall back to the processor event.
+  const requestOrigin =
+    requestOriginFromMetadata(processorMeta) ?? requestOriginFromEvent(event);
   const contextId =
     (processorMeta.contextId as string | null | undefined) ?? undefined;
   const callerMetadata =
@@ -197,7 +268,11 @@ export async function processA2ATaskFromQueue(
   ).unref?.();
   try {
     await runWithRequestContext(
-      { userEmail: verifiedEmail, orgId: resolvedOrgId },
+      {
+        userEmail: verifiedEmail,
+        orgId: resolvedOrgId,
+        ...(requestOrigin ? { requestOrigin } : {}),
+      },
       () =>
         runHandlerAndPersist(
           taskId,
@@ -349,7 +424,7 @@ function makeHandlerContext(
  * inside `runWithRequestContext` so downstream actions see the org.
  */
 async function withA2ARequestContext<T>(
-  _metadata: Record<string, unknown> | undefined,
+  metadata: Record<string, unknown> | undefined,
   event: any | undefined,
   fn: () => Promise<T>,
 ): Promise<T> {
@@ -366,9 +441,14 @@ async function withA2ARequestContext<T>(
     (event?.context?.__a2aOrgDomain as string | undefined) ?? undefined;
 
   const resolvedOrgId = await resolveVerifiedA2AOrgId(verifiedEmail, orgDomain);
+  const requestOrigin = requestOriginForContext(metadata, event);
 
   return runWithRequestContext(
-    { userEmail: verifiedEmail, orgId: resolvedOrgId },
+    {
+      userEmail: verifiedEmail,
+      orgId: resolvedOrgId,
+      ...(requestOrigin ? { requestOrigin } : {}),
+    },
     fn,
   ) as Promise<T>;
 }
@@ -528,14 +608,17 @@ async function handleSend(
     // to metadata.orgDomain which is caller-supplied and unverified.
     const orgDomainHint =
       (event?.context?.__a2aOrgDomain as string | undefined) ?? undefined;
+    const requestOrigin = requestOriginForContext(metadata, event);
+    const safeMetadata = trustedA2AMetadata(metadata, event);
 
     const taskMetadata: Record<string, unknown> = {
-      ...(metadata ?? {}),
+      ...(safeMetadata ?? {}),
       __a2a_processor: {
         verifiedEmail,
         orgDomainHint,
+        ...(requestOrigin ? { requestOrigin } : {}),
         contextId: contextId ?? null,
-        callerMetadata: metadata ?? null,
+        callerMetadata: safeMetadata ?? null,
       },
     };
     const task = await createTask(
@@ -571,7 +654,12 @@ async function handleSend(
     );
     await updateTask(task.id, { state: "working" });
 
-    const ctx = makeHandlerContext(task.id, contextId, metadata, event);
+    const ctx = makeHandlerContext(
+      task.id,
+      contextId,
+      trustedA2AMetadata(metadata, event),
+      event,
+    );
 
     try {
       const result = getHandler(config)(message, ctx.context);
@@ -653,7 +741,7 @@ async function handleStream(
     const { context, artifacts } = makeHandlerContext(
       task.id,
       contextId,
-      metadata,
+      trustedA2AMetadata(metadata, event),
       event,
     );
 

package/corpus/core/src/cli/connect.ts

@@ -15,11 +15,11 @@
  *   agent-native connect --all  [--client ...]   (separate first-party app MCP resources)
  *
  * Server contract (implemented by another agent on `<url>`):
- *   POST <url>/_agent-native/mcp/connect/device/start  (no auth)
+ *   POST <url>/mcp/connect/device/start  (no auth)
  *     body { client?, app? }
  *     → { device_code, user_code, verification_uri,
  *         verification_uri_complete, interval, expires_in }
- *   POST <url>/_agent-native/mcp/connect/device/poll   (no auth)
+ *   POST <url>/mcp/connect/device/poll   (no auth)
  *     body { device_code }
  *     → { status: "pending" }
  *     | { status: "approved", token, mcpUrl, serverName, mcpServerEntry }
@@ -35,6 +35,10 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+import {
+  MCP_LEGACY_ROUTE_PREFIX,
+  MCP_PUBLIC_ROUTE_PREFIX,
+} from "../mcp/route-paths.js";
 import { findWorkspaceRoot } from "../mcp/workspace-resolve.js";
 import {
   CLIENTS,
@@ -52,9 +56,10 @@ import {
 } from "./plan-publish-store.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 DEVICE_START_PATH = `${MCP_PUBLIC_ROUTE_PREFIX}/connect/device/start`;
+const DEVICE_POLL_PATH = `${MCP_PUBLIC_ROUTE_PREFIX}/connect/device/poll`;
+const MCP_PATH = MCP_PUBLIC_ROUTE_PREFIX;
+const LEGACY_MCP_PATH = MCP_LEGACY_ROUTE_PREFIX;
 const SERVER_NAME_PREFIX = "agent-native";
 const CONNECT_PREFERENCES_VERSION = 1;
 
@@ -64,16 +69,15 @@ const CONNECT_PREFERENCES_VERSION = 1;
  * cannot import from there — it imports connect.ts, which would be circular).
  */
 const CANONICAL_SERVER_NAME_BY_MCP_URL: Readonly<Record<string, string>> = {
-  "https://plan.agent-native.com/_agent-native/mcp": "plan",
-  "https://assets.agent-native.com/_agent-native/mcp": "agent-native-assets",
-  "https://design.agent-native.com/_agent-native/mcp": "agent-native-design",
-  "https://context-xray.agent-native.com/_agent-native/mcp":
-    "agent-native-context-xray",
+  "https://plan.agent-native.com/mcp": "plan",
+  "https://assets.agent-native.com/mcp": "agent-native-assets",
+  "https://design.agent-native.com/mcp": "agent-native-design",
+  "https://context-xray.agent-native.com/mcp": "agent-native-context-xray",
 };
 const LEGACY_SERVER_NAMES_BY_MCP_URL: Readonly<
   Record<string, readonly string[]>
 > = {
-  "https://plan.agent-native.com/_agent-native/mcp": [
+  "https://plan.agent-native.com/mcp": [
     "agent-native-plan",
     "agent-native-plans",
     "agent-native-visual-plans",
@@ -759,8 +763,9 @@ function responseMessage(json: any, fallback: string): string {
 function stripMcpPath(baseUrl: string): string {
   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) || "/";
+  const suffix = mcpPathSuffix(pathname);
+  if (suffix) {
+    parsed.pathname = pathname.slice(0, -suffix.length) || "/";
     parsed.search = "";
     parsed.hash = "";
     return `${parsed.origin}${parsed.pathname}`.replace(/\/+$/, "");
@@ -771,8 +776,9 @@ function stripMcpPath(baseUrl: string): string {
 function mcpUrlForBaseUrl(baseUrl: string): string {
   const parsed = new URL(baseUrl);
   const pathname = parsed.pathname.replace(/\/+$/, "");
-  if (pathname === MCP_PATH || pathname.endsWith(MCP_PATH)) {
-    parsed.pathname = pathname;
+  const suffix = mcpPathSuffix(pathname);
+  if (suffix) {
+    parsed.pathname = `${pathname.slice(0, -suffix.length)}${MCP_PATH}`;
     parsed.search = "";
     parsed.hash = "";
     return `${parsed.origin}${parsed.pathname}`;
@@ -805,7 +811,10 @@ async function validateOAuthMcpServer(
         const metadata = (await response.json().catch(() => null)) as {
           resource?: unknown;
         } | null;
-        if (metadata?.resource !== mcpUrl) {
+        if (
+          canonicalMcpUrl(String(metadata?.resource ?? "")) !==
+          canonicalMcpUrl(mcpUrl)
+        ) {
           logErr(
             `  ${metadataUrl} did not advertise the expected MCP resource ` +
               `${mcpUrl}.`,
@@ -980,7 +989,7 @@ export async function runDeviceFlow(
     if (poll.status === "approved") {
       if (isTTY) process.stdout.write("\r\x1b[K");
       const token = poll.token ?? "";
-      const mcpUrl = poll.mcpUrl ?? `${baseUrl}/_agent-native/mcp`;
+      const mcpUrl = mcpUrlForBaseUrl(poll.mcpUrl ?? baseUrl);
       const serverName = poll.serverName ?? `${SERVER_NAME_PREFIX}-${appSlug}`;
       const headers =
         poll.mcpServerEntry &&
@@ -990,7 +999,12 @@ export async function runDeviceFlow(
           ? (poll.mcpServerEntry.headers as Record<string, string>)
           : undefined;
       logOut("  Approved.");
-      return { token: token || undefined, mcpUrl, serverName, headers };
+      return {
+        token: token || undefined,
+        mcpUrl,
+        serverName,
+        ...(headers ? { headers } : {}),
+      };
     }
     if (poll.status === "expired") {
       if (isTTY) process.stdout.write("\r\x1b[K");
@@ -1383,12 +1397,25 @@ function canonicalMcpUrl(value: string | undefined): string | undefined {
   try {
     const url = new URL(value);
     url.hash = "";
+    const pathname = url.pathname.replace(/\/+$/, "");
+    if (pathname === LEGACY_MCP_PATH || pathname.endsWith(LEGACY_MCP_PATH)) {
+      url.pathname = `${pathname.slice(0, -LEGACY_MCP_PATH.length)}${MCP_PATH}`;
+    }
     return url.toString().replace(/\/+$/, "");
   } catch {
     return undefined;
   }
 }
 
+function mcpPathSuffix(pathname: string): string | undefined {
+  const normalized = pathname.replace(/\/+$/, "");
+  if (normalized === LEGACY_MCP_PATH || normalized.endsWith(LEGACY_MCP_PATH)) {
+    return LEGACY_MCP_PATH;
+  }
+  if (normalized === MCP_PATH || normalized.endsWith(MCP_PATH)) return MCP_PATH;
+  return undefined;
+}
+
 function sameMcpUrl(a: string | undefined, b: string | undefined): boolean {
   const left = canonicalMcpUrl(a);
   const right = canonicalMcpUrl(b);
@@ -1663,7 +1690,7 @@ function devMcpUrl(
   gatewayUrls: Map<string, string>,
 ): string {
   const base = gatewayUrls.get(app.name) ?? `${gatewayUrl}/${app.name}`;
-  return `${base.replace(/\/+$/, "")}/_agent-native/mcp`;
+  return `${base.replace(/\/+$/, "")}${MCP_PATH}`;
 }
 
 function serverNameForApp(app: ConnectableApp): string {
@@ -1856,14 +1883,13 @@ function preferredReconnectEntry(
 
 /**
  * Return true when `url` is an agent-native MCP endpoint.
- * Matches any URL whose path ends with `/_agent-native/mcp` (after stripping
- * trailing slashes), regardless of the MCP server's name in the config.
+ * Matches either the public `/mcp` path or the legacy `/_agent-native/mcp`
+ * path, regardless of the MCP server's name in the config.
  */
 function isAgentNativeMcpUrl(url: string | undefined): boolean {
   if (!url) return false;
   try {
-    const pathname = new URL(url).pathname.replace(/\/+$/, "");
-    return pathname === MCP_PATH || pathname.endsWith(MCP_PATH);
+    return Boolean(mcpPathSuffix(new URL(url).pathname));
   } catch {
     return false;
   }
@@ -2036,7 +2062,7 @@ async function resolveReconnectTarget(
   logErr("  Re-run with a URL or --name <serverName>. For example:");
   for (const u of urlList) {
     // Strip the MCP path suffix for a cleaner reconnect URL suggestion.
-    const baseUrl = u.replace(/\/_agent-native\/mcp$/, "");
+    const baseUrl = stripMcpPath(u);
     logErr(`    npx -y @agent-native/core@latest reconnect ${baseUrl}`);
   }
   return null;

package/corpus/core/src/cli/mcp-config-writers.ts

@@ -27,6 +27,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+const MCP_LEGACY_ROUTE_PREFIX = "/_agent-native/mcp";
+const MCP_PUBLIC_ROUTE_PREFIX = "/mcp";
+
 export type ClientId =
   | "claude-code"
   | "claude-code-cli"
@@ -671,6 +674,13 @@ export function canonicalUrl(value: string | undefined): string | undefined {
     const u = new URL(value);
     u.hash = "";
     u.search = "";
+    const pathname = u.pathname.replace(/\/+$/, "");
+    if (
+      pathname === MCP_LEGACY_ROUTE_PREFIX ||
+      pathname.endsWith(MCP_LEGACY_ROUTE_PREFIX)
+    ) {
+      u.pathname = `${pathname.slice(0, -MCP_LEGACY_ROUTE_PREFIX.length)}${MCP_PUBLIC_ROUTE_PREFIX}`;
+    }
     return u.toString().replace(/\/+$/, "");
   } catch {
     return undefined;

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

@@ -17,6 +17,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 
+import { MCP_PUBLIC_ROUTE_PREFIX } from "../mcp/route-paths.js";
 import { runScreenMemoryMCPStdio } from "../mcp/screen-memory-stdio.js";
 import { runMCPStdio } from "../mcp/stdio.js";
 import {
@@ -178,7 +179,7 @@ function ensureLocalToken(
 /**
  * Detect a hosted deployment URL. When the workspace .env points at a hosted
  * origin (APP_URL / BETTER_AUTH_URL with a non-localhost host) we write an
- * `http` client entry pointing at `<origin>/_agent-native/mcp` with a JWT
+ * `http` client entry pointing at `<origin>/mcp` with a JWT
  * bearer instead of a stdio entry.
  */
 function detectHostedUrl(cwd: string): string | undefined {
@@ -193,7 +194,8 @@ function detectHostedUrl(cwd: string): string | undefined {
     try {
       const u = new URL(v);
       if (!/^(localhost|127\.0\.0\.1|\[::1\])$/.test(u.hostname)) {
-        return `${u.origin}/_agent-native/mcp`;
+        const appPath = u.pathname.replace(/\/+$/, "");
+        return `${u.origin}${appPath === "/" ? "" : appPath}${MCP_PUBLIC_ROUTE_PREFIX}`;
       }
     } catch {
       // not a URL — skip
@@ -501,9 +503,7 @@ async function cmdStatus(): Promise<void> {
   logOut(
     hostedUrl
       ? `  MCP URL:    ${hostedUrl} (hosted)`
-      : `  MCP URL:    ${origin}/_agent-native/mcp${
-          port ? ` (port ${port})` : ""
-        }`,
+      : `  MCP URL:    ${origin}/mcp${port ? ` (port ${port})` : ""}`,
   );
   logOut(`  ACCESS_TOKEN: ${hasToken ? "set" : "not set"} (.env)`);
   logOut(`  A2A_SECRET:   ${hasA2A ? "set" : "not set"}`);

package/corpus/core/src/cli/skills-content/assets-skill.ts

@@ -55,7 +55,7 @@ of using a generic image generator.
 
 ## Cross-App Use
 
-- Hosted default: connect \`https://assets.agent-native.com/_agent-native/mcp\`.
+- Hosted default: connect \`https://assets.agent-native.com/mcp\`.
   Do not put shared secrets in skill files.
 - For CLI/code-editor clients, keep any \`npx @agent-native/core@latest connect\` command
   running until browser authorization finishes. Stopping it early can leave the

package/corpus/core/src/cli/skills-content/design-exploration-skill.ts

@@ -92,7 +92,7 @@ separate those jobs; use it, and hold this bar:
 
 ## Cross-App Use
 
-- Hosted default: connect \`https://design.agent-native.com/_agent-native/mcp\`.
+- Hosted default: connect \`https://design.agent-native.com/mcp\`.
   Do not put shared secrets in skill files.
 - For CLI/code-editor clients, keep any \`npx @agent-native/core@latest connect\` command
   running until browser authorization finishes. Stopping it early can leave the

package/corpus/core/src/cli/skills-content/help.ts

@@ -48,7 +48,7 @@ register MCP where possible without authenticating (leave auth to the host or ru
 "npx @agent-native/core@latest connect" later). Pass --mcp-url to register that connector against
 a custom origin (an ngrok tunnel, a local dev server, or a self-hosted
 deployment) instead of the built-in hosted default — a bare origin gets the
-standard /_agent-native/mcp path appended. Use app-skill pack for marketplace
+standard /mcp path appended. Use app-skill pack for marketplace
 bundles and custom adapter output.
 
 When installing visual-plan, visual-recap, or visualize-repo interactively, the

package/corpus/core/src/cli/skills-content/plan-setup-auth.ts

@@ -76,5 +76,5 @@ client. Reconnect re-authenticates WITHOUT reinstalling and finds the entry by
 URL regardless of connector name. Never reinstall from scratch just to fix auth.
 Continue once the connector is available.
 
-Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`. Do
+Hosted default: connect \`https://plan.agent-native.com/mcp\`. Do
 not put shared secrets in skill files.`;

package/corpus/core/src/cli/skills-content/visual-plan-skill.ts

@@ -465,6 +465,6 @@ If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminate
 not keep retrying it — stop and give the user the per-client reconnect step from
 \`references/connection.md\`, then continue once the connector is available.
 
-Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`. Do
+Hosted default: connect \`https://plan.agent-native.com/mcp\`. Do
 not put shared secrets in skill files.
 `;

package/corpus/core/src/cli/skills-content/visual-recap-skill.ts

@@ -270,7 +270,7 @@ Resolve the URL in this order:
    the plan.
 2. Use a \`localhost\`/dev origin ONLY when the recap was created through a Plan
    MCP bound to that same origin — i.e. that MCP's url is
-   \`http://localhost:<port>/_agent-native/mcp\`. Creating through the hosted MCP
+   \`http://localhost:<port>/mcp\`. Creating through the hosted MCP
    and linking to localhost is the exact mismatch that 404s.
 3. If only a plan id is available, build the MCP origin's absolute URL
    (hosted: \`https://plan.agent-native.com/plans/<id>\`) and say it was inferred.
@@ -278,7 +278,7 @@ Resolve the URL in this order:
 If the user wants to review on localhost but the recap was created through the
 hosted MCP, say so plainly: the local dev server cannot see it. To view a recap
 on localhost (e.g. to exercise un-deployed local renderer changes), they must
-connect a LOCAL Plan MCP (\`http://localhost:<port>/_agent-native/mcp\`) and
+connect a LOCAL Plan MCP (\`http://localhost:<port>/mcp\`) and
 re-create the recap through it so it lands in the local database; offer to do
 that rather than handing over a localhost URL that will not resolve.
 

package/corpus/core/src/cli/skills.ts

@@ -11,6 +11,10 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import {
+  MCP_LEGACY_ROUTE_PREFIX,
+  MCP_PUBLIC_ROUTE_PREFIX,
+} from "../mcp/route-paths.js";
 import {
   buildAppSkillPack,
   ensureAppSkill,
@@ -72,7 +76,7 @@ export const BUILT_IN_APP_SKILLS = {
         "Create, search, select, and export brand image and video assets from the Assets app.",
       hosted: {
         url: "https://assets.agent-native.com",
-        mcpUrl: "https://assets.agent-native.com/_agent-native/mcp",
+        mcpUrl: "https://assets.agent-native.com/mcp",
       },
       mcp: { serverName: "agent-native-assets" },
       auth: {
@@ -118,7 +122,7 @@ export const BUILT_IN_APP_SKILLS = {
         "Edit docs, blogs, resources, and MDX content through the Content app, including repo-backed Local File Mode.",
       hosted: {
         url: "https://content.agent-native.com",
-        mcpUrl: "https://content.agent-native.com/_agent-native/mcp",
+        mcpUrl: "https://content.agent-native.com/mcp",
       },
       mcp: { serverName: "agent-native-content" },
       auth: {
@@ -170,7 +174,7 @@ export const BUILT_IN_APP_SKILLS = {
         "Explore, compare, iterate, and export interactive UI design prototypes from the Design app.",
       hosted: {
         url: "https://design.agent-native.com",
-        mcpUrl: "https://design.agent-native.com/_agent-native/mcp",
+        mcpUrl: "https://design.agent-native.com/mcp",
       },
       mcp: { serverName: "agent-native-design" },
       auth: {
@@ -247,7 +251,7 @@ export const BUILT_IN_APP_SKILLS = {
         "Create rich interactive visual plans, recaps, and repo-native visual docs with diagrams, file maps, annotated code and diffs, API/schema summaries, feedback, and HTML export.",
       hosted: {
         url: "https://plan.agent-native.com",
-        mcpUrl: "https://plan.agent-native.com/_agent-native/mcp",
+        mcpUrl: "https://plan.agent-native.com/mcp",
       },
       mcp: { serverName: "plan", aliases: ["agent-native-plans"] },
       auth: {
@@ -317,7 +321,7 @@ export const BUILT_IN_APP_SKILLS = {
         "Visualize local Codex and Claude Code context usage with warnings and optimization tips.",
       hosted: {
         url: "https://context-xray.agent-native.com",
-        mcpUrl: "https://context-xray.agent-native.com/_agent-native/mcp",
+        mcpUrl: "https://context-xray.agent-native.com/mcp",
       },
       mcp: { serverName: "agent-native-context-xray" },
       auth: { mode: "none" },
@@ -2771,8 +2775,11 @@ function preserveMcpUrlAppPathOverride(
     return target;
   }
   const trimmedPath = parsed.pathname.replace(/\/+$/, "");
-  const appPath = trimmedPath.endsWith("/_agent-native/mcp")
-    ? trimmedPath.slice(0, -"/_agent-native/mcp".length).replace(/\/+$/, "")
+  const mcpSuffix = [MCP_LEGACY_ROUTE_PREFIX, MCP_PUBLIC_ROUTE_PREFIX].find(
+    (suffix) => trimmedPath === suffix || trimmedPath.endsWith(suffix),
+  );
+  const appPath = mcpSuffix
+    ? trimmedPath.slice(0, -mcpSuffix.length).replace(/\/+$/, "")
     : trimmedPath;
   if (!appPath) return target;
   const url = `${parsed.origin}${appPath}`;
@@ -2782,7 +2789,7 @@ function preserveMcpUrlAppPathOverride(
       ...target.loaded,
       manifest: {
         ...target.loaded.manifest,
-        hosted: { url, mcpUrl: `${url}/_agent-native/mcp` },
+        hosted: { url, mcpUrl: `${url}${MCP_PUBLIC_ROUTE_PREFIX}` },
       },
     },
   };
@@ -2870,7 +2877,8 @@ async function runCommand(
 /**
  * Resolve a `--mcp-url` override into the `{ url, mcpUrl }` pair the manifest
  * expects. Accepts a bare origin (`https://x.ngrok-free.dev`) — appending the
- * standard `/_agent-native/mcp` path — or a full MCP URL already ending in it.
+ * standard `/mcp` path — or a full MCP URL already ending in `/mcp` or the
+ * legacy `/_agent-native/mcp` path.
  */
 function resolveMcpUrlOverride(input: string): { url: string; mcpUrl: string } {
   let parsed: URL;
@@ -2884,9 +2892,12 @@ function resolveMcpUrlOverride(input: string): { url: string; mcpUrl: string } {
   }
   const origin = parsed.origin;
   const trimmedPath = parsed.pathname.replace(/\/+$/, "");
-  const mcpUrl = trimmedPath.endsWith("/_agent-native/mcp")
-    ? `${origin}${trimmedPath}`
-    : `${origin}/_agent-native/mcp`;
+  const mcpSuffix = [MCP_LEGACY_ROUTE_PREFIX, MCP_PUBLIC_ROUTE_PREFIX].find(
+    (suffix) => trimmedPath === suffix || trimmedPath.endsWith(suffix),
+  );
+  const mcpUrl = mcpSuffix
+    ? `${origin}${trimmedPath.slice(0, -mcpSuffix.length)}${MCP_PUBLIC_ROUTE_PREFIX}`
+    : `${origin}${MCP_PUBLIC_ROUTE_PREFIX}`;
   return { url: origin, mcpUrl };
 }
 

package/corpus/core/src/client/resources/McpIntegrationDialog.tsx

@@ -447,6 +447,11 @@ export function McpIntegrationDialog({
             <div className="min-h-0 flex-1 overflow-y-auto px-7 py-5">
               <div className="space-y-3">
                 {renderScopeSelector()}
+                {selected?.setupNoteKey && (
+                  <div className="rounded-md border border-amber-500/20 bg-amber-500/5 px-3 py-2 text-[11px] leading-relaxed text-amber-700 dark:text-amber-300">
+                    {t(selected.setupNoteKey)}
+                  </div>
+                )}
                 {selected?.authMode === "oauth" && (
                   <div className="rounded-md border border-blue-500/20 bg-blue-500/5 px-3 py-2 text-[11px] leading-relaxed text-blue-700 dark:text-blue-300">
                     {t("mcpIntegrations.oauthNotice")}

package/corpus/core/src/client/resources/mcp-integration-catalog.ts

@@ -21,6 +21,7 @@ export interface DefaultMcpIntegration {
   url: string;
   authMode: McpIntegrationAuthMode;
   docsUrl?: string;
+  setupNoteKey?: string;
   headerPlaceholder?: string;
   keywords: string[];
 }
@@ -99,6 +100,22 @@ export const DEFAULT_MCP_INTEGRATIONS: DefaultMcpIntegration[] = [
     docsUrl: "https://www.builder.io/c/docs/fusion-connect-to-linear",
     keywords: ["issues", "tickets", "planning", "project management"],
   },
+  {
+    id: "atlassian",
+    name: "Atlassian",
+    provider: "atlassian",
+    description: "Read and write Jira issues and Confluence content.",
+    descriptionKey: "mcpIntegrations.catalog.atlassian.description",
+    useCase:
+      "project management, issue tracking, documentation, team collaboration",
+    useCaseKey: "mcpIntegrations.catalog.atlassian.useCase",
+    url: "https://mcp.atlassian.com/v1/mcp/authv2",
+    authMode: "oauth",
+    docsUrl:
+      "https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/",
+    setupNoteKey: "mcpIntegrations.catalog.atlassian.setupNote",
+    keywords: ["atlassian", "jira", "confluence", "issues", "tickets"],
+  },
   {
     id: "supabase",
     name: "Supabase",