@agent-native/core 0.18.1 → 0.19.1

package/dist/mcp/org-directory.js

@@ -0,0 +1,201 @@
+/**
+ * Org-directory discovery for the generic cross-app MCP verbs
+ * (`list_apps` / `ask_app` in `builtin-tools.ts`).
+ *
+ * Phase 3b of cross-app auto-wiring. Today the cross-app verbs resolve sibling
+ * apps from *local workspace* info only (`workspace-resolve.ts`), so the mail
+ * agent can only reach the calendar agent in a local dev workspace. When the
+ * deployment runs against an org directory (Dispatch is also the identity hub
+ * for the org), this module discovers the org's *deployed* sibling apps so the
+ * same verbs work cross-app in production with ZERO manual setup.
+ *
+ * ## The directory request
+ *
+ *   GET  <directoryOrigin>/_agent-native/org/apps
+ *   Auth Authorization: Bearer <org A2A token>   (same signed token A2A peers
+ *        already mint — reuses `resolveA2ACallerAuth()`; the org A2A secret /
+ *        global `A2A_SECRET` is loaded exactly how outgoing A2A calls load it)
+ *   ⇒    { org, apps: [ { id, name, url, a2aUrl, capabilities? } ] }
+ *        (allow-listed first-party apps only, prod URLs — enforced by the
+ *         authority side, Phase 3a, on Dispatch)
+ *
+ * ## Resolution + safety model
+ *
+ *   - The directory origin is read from env: `AGENT_NATIVE_ORG_DIRECTORY_URL`
+ *     (dedicated) or `AGENT_NATIVE_IDENTITY_HUB_URL` (Dispatch is also the
+ *     identity hub). When *neither* is set the feature is simply inactive —
+ *     `fetchOrgApps()` returns `[]` and nothing changes anywhere (asserted by
+ *     a test). This makes the whole feature opt-in and back-compat.
+ *   - On ANY error (no env, unreachable, 401, non-2xx, bad JSON, no signed
+ *     token) `fetchOrgApps()` returns `[]` and NEVER throws — the cross-app
+ *     verbs degrade silently to their exact current local-only behavior.
+ *   - A short in-memory TTL cache (default 60s) keyed by directory origin and
+ *     caller identity/org scope so sibling app lists never cross tenants.
+ *     Empty authenticated results are cached too (with a shorter TTL) so a
+ *     transient failure doesn't hammer the directory on every call.
+ *   - No secrets are ever logged.
+ *
+ * Bundled alongside `mountMCP` (no Node-only top-level imports). The A2A
+ * caller-auth + a2a client are dynamically imported inside `fetchOrgApps()`.
+ */
+/** Default cache TTL for a successful directory fetch. */
+const SUCCESS_TTL_MS = 60_000;
+/** Shorter TTL for an empty/failed fetch so transient errors recover fast. */
+const EMPTY_TTL_MS = 10_000;
+/** In-memory cache keyed by resolved directory origin (+ identity scope). */
+const cache = new Map();
+/**
+ * Resolve the org-directory origin from env. Returns `null` when neither env
+ * var is set — the caller treats `null` as "feature inactive".
+ *
+ * `env` is injectable for tests; defaults to `process.env`.
+ */
+export function resolveOrgDirectoryOrigin(env = process.env) {
+    const raw = env.AGENT_NATIVE_ORG_DIRECTORY_URL || env.AGENT_NATIVE_IDENTITY_HUB_URL;
+    if (!raw || typeof raw !== "string")
+        return null;
+    const trimmed = raw.trim().replace(/\/+$/, "");
+    if (!trimmed)
+        return null;
+    try {
+        // Validate it's an absolute http(s) URL; reject anything else.
+        const u = new URL(trimmed);
+        if (u.protocol !== "http:" && u.protocol !== "https:")
+            return null;
+        return trimmed;
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeApp(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    const id = typeof r.id === "string" ? r.id.trim().toLowerCase() : "";
+    const url = typeof r.url === "string" ? r.url.trim() : "";
+    if (!id || !url)
+        return null;
+    // Only accept absolute http(s) URLs from the directory.
+    try {
+        const u = new URL(url);
+        if (u.protocol !== "http:" && u.protocol !== "https:")
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const name = typeof r.name === "string" && r.name.trim() ? r.name.trim() : id;
+    const a2aUrl = typeof r.a2aUrl === "string" && r.a2aUrl.trim() ? r.a2aUrl.trim() : url;
+    const capabilities = Array.isArray(r.capabilities)
+        ? r.capabilities.filter((c) => typeof c === "string")
+        : undefined;
+    return {
+        id,
+        name,
+        url: url.replace(/\/+$/, ""),
+        a2aUrl: a2aUrl.replace(/\/+$/, ""),
+        ...(capabilities && capabilities.length ? { capabilities } : {}),
+    };
+}
+/** Compare two origins by host (ignores trailing slash / protocol noise). */
+function sameOrigin(a, b) {
+    try {
+        const ua = new URL(a);
+        const ub = new URL(b);
+        return ua.host === ub.host && ua.protocol === ub.protocol;
+    }
+    catch {
+        return a.replace(/\/+$/, "") === b.replace(/\/+$/, "");
+    }
+}
+function scopedCacheKey(origin, auth) {
+    return [
+        origin,
+        `user:${auth.userEmail ?? ""}`,
+        `org:${auth.orgId ?? auth.orgDomain ?? ""}`,
+    ].join("|");
+}
+/**
+ * Fetch the org's first-party sibling apps from the org directory.
+ *
+ * - Returns `[]` (never throws) on ANY failure or when the directory env is
+ *   unset — the cross-app verbs then keep their exact local-only behavior.
+ * - Short in-memory TTL cache so it isn't fetched on every tool call.
+ * - Strips the current app from the result (compared by id and by origin) so
+ *   `list_apps` / `ask_app` never offer to route to themselves.
+ *
+ * @param opts.selfId      Current app id (so it's stripped from the result).
+ * @param opts.selfOrigin  Current app origin (so it's stripped by origin too).
+ * @param opts.env         Injectable env (tests). Defaults to `process.env`.
+ */
+export async function fetchOrgApps(opts) {
+    const env = opts?.env ?? process.env;
+    const origin = resolveOrgDirectoryOrigin(env);
+    // Feature inactive: no directory configured ⇒ behave exactly as before.
+    if (!origin)
+        return [];
+    const selfId = (opts?.selfId ?? "").trim().toLowerCase();
+    const selfOrigin = (opts?.selfOrigin ?? "").trim();
+    const stripSelf = (apps) => apps.filter((a) => {
+        if (selfId && a.id === selfId)
+            return false;
+        if (selfOrigin && sameOrigin(a.url, selfOrigin))
+            return false;
+        return true;
+    });
+    let cacheKey = null;
+    let apps = [];
+    let ttl = EMPTY_TTL_MS;
+    try {
+        // Reuse the existing A2A caller-auth: it reads userEmail + orgId from the
+        // request context, loads the org A2A secret via getOrgA2ASecret (falling
+        // back to the global A2A_SECRET env), and signs the same bearer JWT A2A
+        // peers already use. No new secret loading is invented here.
+        const { resolveA2ACallerAuth } = await import("../a2a/caller-auth.js");
+        const auth = await resolveA2ACallerAuth();
+        if (!auth.apiKey) {
+            // No signed token available (no A2A secret / no caller identity) — the
+            // directory requires the org bearer, so degrade silently to local-only.
+            return [];
+        }
+        const now = Date.now();
+        cacheKey = scopedCacheKey(origin, auth);
+        const cached = cache.get(cacheKey);
+        if (cached && cached.expiresAt > now) {
+            return stripSelf(cached.apps);
+        }
+        const res = await fetch(`${origin}/_agent-native/org/apps`, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${auth.apiKey}`,
+                Accept: "application/json",
+            },
+            signal: AbortSignal.timeout(4000),
+        });
+        if (res.ok) {
+            const json = (await res.json());
+            const list = Array.isArray(json?.apps) ? json.apps : [];
+            apps = list.map(normalizeApp).filter((a) => a !== null);
+            ttl = SUCCESS_TTL_MS;
+        }
+        // Non-2xx ⇒ leave apps=[] with the short EMPTY_TTL (silent degrade).
+    }
+    catch {
+        // Unreachable / parse error / abort ⇒ silent degrade to local-only.
+        apps = [];
+        ttl = EMPTY_TTL_MS;
+    }
+    if (cacheKey) {
+        cache.set(cacheKey, {
+            apps,
+            expiresAt: Date.now() + ttl,
+        });
+    }
+    return stripSelf(apps);
+}
+/** Test-only: clear the in-memory cache between cases. */
+export function _resetOrgDirectoryCache() {
+    cache.clear();
+}
+//# sourceMappingURL=org-directory.js.map

package/dist/mcp/org-directory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"org-directory.js","sourceRoot":"","sources":["../../src/mcp/org-directory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAkBH,0DAA0D;AAC1D,MAAM,cAAc,GAAG,MAAM,CAAC;AAC9B,8EAA8E;AAC9E,MAAM,YAAY,GAAG,MAAM,CAAC;AAO5B,6EAA6E;AAC7E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,GAAG,GACP,GAAG,CAAC,8BAA8B,IAAI,GAAG,CAAC,6BAA6B,CAAC;IAC1E,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC/C,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,CAAC;QACH,+DAA+D;QAC/D,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3B,IAAI,CAAC,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACnE,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,GAAY;IAChC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACrE,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,IAAI,CAAC,EAAE,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAC7B,wDAAwD;IACxD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,MAAM,MAAM,GACV,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IAC1E,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC;QAChD,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;QAClE,CAAC,CAAC,SAAS,CAAC;IACd,OAAO;QACL,EAAE;QACF,IAAI;QACJ,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QAC5B,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QAClC,GAAG,CAAC,YAAY,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjE,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,SAAS,UAAU,CAAC,CAAS,EAAE,CAAS;IACtC,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;QACtB,OAAO,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,QAAQ,KAAK,EAAE,CAAC,QAAQ,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzD,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CACrB,MAAc,EACd,IAIC;IAED,OAAO;QACL,MAAM;QACN,QAAQ,IAAI,CAAC,SAAS,IAAI,EAAE,EAAE;QAC9B,OAAO,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,SAAS,IAAI,EAAE,EAAE;KAC5C,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAIlC;IACC,MAAM,GAAG,GAAG,IAAI,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACrC,MAAM,MAAM,GAAG,yBAAyB,CAAC,GAAG,CAAC,CAAC;IAC9C,wEAAwE;IACxE,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACzD,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAEnD,MAAM,SAAS,GAAG,CAAC,IAAc,EAAY,EAAE,CAC7C,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QAChB,IAAI,MAAM,IAAI,CAAC,CAAC,EAAE,KAAK,MAAM;YAAE,OAAO,KAAK,CAAC;QAC5C,IAAI,UAAU,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC;YAAE,OAAO,KAAK,CAAC;QAC9D,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IAEL,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,IAAI,IAAI,GAAa,EAAE,CAAC;IACxB,IAAI,GAAG,GAAG,YAAY,CAAC;IACvB,IAAI,CAAC;QACH,0EAA0E;QAC1E,yEAAyE;QACzE,wEAAwE;QACxE,6DAA6D;QAC7D,MAAM,EAAE,oBAAoB,EAAE,GAAG,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;QACvE,MAAM,IAAI,GAAG,MAAM,oBAAoB,EAAE,CAAC;QAC1C,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,uEAAuE;YACvE,wEAAwE;YACxE,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,QAAQ,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC;YACrC,OAAO,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,MAAM,yBAAyB,EAAE;YAC1D,MAAM,EAAE,KAAK;YACb,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;gBACtC,MAAM,EAAE,kBAAkB;aAC3B;YACD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC;SAClC,CAAC,CAAC;QACH,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;YACX,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuB,CAAC;YACtD,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;YACrE,GAAG,GAAG,cAAc,CAAC;QACvB,CAAC;QACD,qEAAqE;IACvE,CAAC;IAAC,MAAM,CAAC;QACP,oEAAoE;QACpE,IAAI,GAAG,EAAE,CAAC;QACV,GAAG,GAAG,YAAY,CAAC;IACrB,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE;YAClB,IAAI;YACJ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG;SAC5B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,uBAAuB;IACrC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC","sourcesContent":["/**\n * Org-directory discovery for the generic cross-app MCP verbs\n * (`list_apps` / `ask_app` in `builtin-tools.ts`).\n *\n * Phase 3b of cross-app auto-wiring. Today the cross-app verbs resolve sibling\n * apps from *local workspace* info only (`workspace-resolve.ts`), so the mail\n * agent can only reach the calendar agent in a local dev workspace. When the\n * deployment runs against an org directory (Dispatch is also the identity hub\n * for the org), this module discovers the org's *deployed* sibling apps so the\n * same verbs work cross-app in production with ZERO manual setup.\n *\n * ## The directory request\n *\n *   GET  <directoryOrigin>/_agent-native/org/apps\n *   Auth Authorization: Bearer <org A2A token>   (same signed token A2A peers\n *        already mint — reuses `resolveA2ACallerAuth()`; the org A2A secret /\n *        global `A2A_SECRET` is loaded exactly how outgoing A2A calls load it)\n *   ⇒    { org, apps: [ { id, name, url, a2aUrl, capabilities? } ] }\n *        (allow-listed first-party apps only, prod URLs — enforced by the\n *         authority side, Phase 3a, on Dispatch)\n *\n * ## Resolution + safety model\n *\n *   - The directory origin is read from env: `AGENT_NATIVE_ORG_DIRECTORY_URL`\n *     (dedicated) or `AGENT_NATIVE_IDENTITY_HUB_URL` (Dispatch is also the\n *     identity hub). When *neither* is set the feature is simply inactive —\n *     `fetchOrgApps()` returns `[]` and nothing changes anywhere (asserted by\n *     a test). This makes the whole feature opt-in and back-compat.\n *   - On ANY error (no env, unreachable, 401, non-2xx, bad JSON, no signed\n *     token) `fetchOrgApps()` returns `[]` and NEVER throws — the cross-app\n *     verbs degrade silently to their exact current local-only behavior.\n *   - A short in-memory TTL cache (default 60s) keyed by directory origin and\n *     caller identity/org scope so sibling app lists never cross tenants.\n *     Empty authenticated results are cached too (with a shorter TTL) so a\n *     transient failure doesn't hammer the directory on every call.\n *   - No secrets are ever logged.\n *\n * Bundled alongside `mountMCP` (no Node-only top-level imports). The A2A\n * caller-auth + a2a client are dynamically imported inside `fetchOrgApps()`.\n */\n\nexport interface OrgApp {\n  /** Canonical app id, e.g. `calendar`. */\n  id: string;\n  /** Human-readable name, e.g. `Calendar`. */\n  name: string;\n  /** Deployed app origin/URL, e.g. `https://calendar.acme.com`. */\n  url: string;\n  /**\n   * A2A endpoint to route `ask_app` to. The authority side returns this; we\n   * fall back to the app `url` (the A2A client appends `/_agent-native/a2a`).\n   */\n  a2aUrl: string;\n  /** Optional capability hints the authority side may include. */\n  capabilities?: string[];\n}\n\n/** Default cache TTL for a successful directory fetch. */\nconst SUCCESS_TTL_MS = 60_000;\n/** Shorter TTL for an empty/failed fetch so transient errors recover fast. */\nconst EMPTY_TTL_MS = 10_000;\n\ninterface CacheEntry {\n  apps: OrgApp[];\n  expiresAt: number;\n}\n\n/** In-memory cache keyed by resolved directory origin (+ identity scope). */\nconst cache = new Map<string, CacheEntry>();\n\n/**\n * Resolve the org-directory origin from env. Returns `null` when neither env\n * var is set — the caller treats `null` as \"feature inactive\".\n *\n * `env` is injectable for tests; defaults to `process.env`.\n */\nexport function resolveOrgDirectoryOrigin(\n  env: NodeJS.ProcessEnv = process.env,\n): string | null {\n  const raw =\n    env.AGENT_NATIVE_ORG_DIRECTORY_URL || env.AGENT_NATIVE_IDENTITY_HUB_URL;\n  if (!raw || typeof raw !== \"string\") return null;\n  const trimmed = raw.trim().replace(/\\/+$/, \"\");\n  if (!trimmed) return null;\n  try {\n    // Validate it's an absolute http(s) URL; reject anything else.\n    const u = new URL(trimmed);\n    if (u.protocol !== \"http:\" && u.protocol !== \"https:\") return null;\n    return trimmed;\n  } catch {\n    return null;\n  }\n}\n\nfunction normalizeApp(raw: unknown): OrgApp | null {\n  if (!raw || typeof raw !== \"object\") return null;\n  const r = raw as Record<string, unknown>;\n  const id = typeof r.id === \"string\" ? r.id.trim().toLowerCase() : \"\";\n  const url = typeof r.url === \"string\" ? r.url.trim() : \"\";\n  if (!id || !url) return null;\n  // Only accept absolute http(s) URLs from the directory.\n  try {\n    const u = new URL(url);\n    if (u.protocol !== \"http:\" && u.protocol !== \"https:\") return null;\n  } catch {\n    return null;\n  }\n  const name = typeof r.name === \"string\" && r.name.trim() ? r.name.trim() : id;\n  const a2aUrl =\n    typeof r.a2aUrl === \"string\" && r.a2aUrl.trim() ? r.a2aUrl.trim() : url;\n  const capabilities = Array.isArray(r.capabilities)\n    ? r.capabilities.filter((c): c is string => typeof c === \"string\")\n    : undefined;\n  return {\n    id,\n    name,\n    url: url.replace(/\\/+$/, \"\"),\n    a2aUrl: a2aUrl.replace(/\\/+$/, \"\"),\n    ...(capabilities && capabilities.length ? { capabilities } : {}),\n  };\n}\n\n/** Compare two origins by host (ignores trailing slash / protocol noise). */\nfunction sameOrigin(a: string, b: string): boolean {\n  try {\n    const ua = new URL(a);\n    const ub = new URL(b);\n    return ua.host === ub.host && ua.protocol === ub.protocol;\n  } catch {\n    return a.replace(/\\/+$/, \"\") === b.replace(/\\/+$/, \"\");\n  }\n}\n\nfunction scopedCacheKey(\n  origin: string,\n  auth: {\n    userEmail?: string;\n    orgId?: string;\n    orgDomain?: string;\n  },\n): string {\n  return [\n    origin,\n    `user:${auth.userEmail ?? \"\"}`,\n    `org:${auth.orgId ?? auth.orgDomain ?? \"\"}`,\n  ].join(\"|\");\n}\n\n/**\n * Fetch the org's first-party sibling apps from the org directory.\n *\n * - Returns `[]` (never throws) on ANY failure or when the directory env is\n *   unset — the cross-app verbs then keep their exact local-only behavior.\n * - Short in-memory TTL cache so it isn't fetched on every tool call.\n * - Strips the current app from the result (compared by id and by origin) so\n *   `list_apps` / `ask_app` never offer to route to themselves.\n *\n * @param opts.selfId      Current app id (so it's stripped from the result).\n * @param opts.selfOrigin  Current app origin (so it's stripped by origin too).\n * @param opts.env         Injectable env (tests). Defaults to `process.env`.\n */\nexport async function fetchOrgApps(opts?: {\n  selfId?: string;\n  selfOrigin?: string;\n  env?: NodeJS.ProcessEnv;\n}): Promise<OrgApp[]> {\n  const env = opts?.env ?? process.env;\n  const origin = resolveOrgDirectoryOrigin(env);\n  // Feature inactive: no directory configured ⇒ behave exactly as before.\n  if (!origin) return [];\n\n  const selfId = (opts?.selfId ?? \"\").trim().toLowerCase();\n  const selfOrigin = (opts?.selfOrigin ?? \"\").trim();\n\n  const stripSelf = (apps: OrgApp[]): OrgApp[] =>\n    apps.filter((a) => {\n      if (selfId && a.id === selfId) return false;\n      if (selfOrigin && sameOrigin(a.url, selfOrigin)) return false;\n      return true;\n    });\n\n  let cacheKey: string | null = null;\n  let apps: OrgApp[] = [];\n  let ttl = EMPTY_TTL_MS;\n  try {\n    // Reuse the existing A2A caller-auth: it reads userEmail + orgId from the\n    // request context, loads the org A2A secret via getOrgA2ASecret (falling\n    // back to the global A2A_SECRET env), and signs the same bearer JWT A2A\n    // peers already use. No new secret loading is invented here.\n    const { resolveA2ACallerAuth } = await import(\"../a2a/caller-auth.js\");\n    const auth = await resolveA2ACallerAuth();\n    if (!auth.apiKey) {\n      // No signed token available (no A2A secret / no caller identity) — the\n      // directory requires the org bearer, so degrade silently to local-only.\n      return [];\n    }\n\n    const now = Date.now();\n    cacheKey = scopedCacheKey(origin, auth);\n    const cached = cache.get(cacheKey);\n    if (cached && cached.expiresAt > now) {\n      return stripSelf(cached.apps);\n    }\n\n    const res = await fetch(`${origin}/_agent-native/org/apps`, {\n      method: \"GET\",\n      headers: {\n        Authorization: `Bearer ${auth.apiKey}`,\n        Accept: \"application/json\",\n      },\n      signal: AbortSignal.timeout(4000),\n    });\n    if (res.ok) {\n      const json = (await res.json()) as { apps?: unknown };\n      const list = Array.isArray(json?.apps) ? json.apps : [];\n      apps = list.map(normalizeApp).filter((a): a is OrgApp => a !== null);\n      ttl = SUCCESS_TTL_MS;\n    }\n    // Non-2xx ⇒ leave apps=[] with the short EMPTY_TTL (silent degrade).\n  } catch {\n    // Unreachable / parse error / abort ⇒ silent degrade to local-only.\n    apps = [];\n    ttl = EMPTY_TTL_MS;\n  }\n\n  if (cacheKey) {\n    cache.set(cacheKey, {\n      apps,\n      expiresAt: Date.now() + ttl,\n    });\n  }\n  return stripSelf(apps);\n}\n\n/** Test-only: clear the in-memory cache between cases. */\nexport function _resetOrgDirectoryCache(): void {\n  cache.clear();\n}\n"]}

package/dist/mcp/server.d.ts

@@ -1,13 +1,50 @@
+import type { H3Event } from "h3";
 import { createMCPServerForRequest, verifyAuth, getAccessTokens, resolveOrgIdFromDomain, buildLinkArtifacts, type MCPConfig, type MCPCallerIdentity, type MCPRequestMeta } from "./build-server.js";
 export { createMCPServerForRequest, verifyAuth, getAccessTokens, resolveOrgIdFromDomain, buildLinkArtifacts, };
 export type { MCPConfig, MCPCallerIdentity, MCPRequestMeta };
+/**
+ * Handle a single `{routePrefix}/mcp` request on either runtime.
+ *
+ * - **Node fast-path** (real Node HTTP server): unchanged — delegate to the
+ *   SDK's `StreamableHTTPServerTransport.handleRequest(nodeReq, nodeRes,
+ *   body)`, which writes directly to the Node response (full protocol incl.
+ *   SSE).
+ * - **Web-standard fallback** (Nitro 3 / Netlify web runtime, Cloudflare,
+ *   Deno, Bun — where there is no Node req/res): build the SAME MCP `Server`
+ *   from the SAME config + identity, drive it through the SDK's
+ *   `WebStandardStreamableHTTPServerTransport` (which the Node transport is
+ *   itself just a thin wrapper around), and return the resulting Web
+ *   `Response` as a normal h3 return value.
+ *
+ * Auth, the `runWithRequestContext` identity wrap, the deep-link `_meta` /
+ * markdown append, `requestMeta` origin/target derivation and the stateless
+ * semantics are IDENTICAL on both paths because both build the same server
+ * via `createMCPServerForRequest` and both transports funnel into the same
+ * `WebStandardStreamableHTTPServerTransport.handleRequest(webRequest, {
+ * parsedBody })` with the same options.
+ *
+ * Returns:
+ *   - `undefined` when the request targets a sub-route (so management/status
+ *     routes mounted under `/_agent-native/mcp/*` handle it themselves) — the
+ *     h3 mount falls through to the next handler.
+ *   - a Web `Response` (web fallback) or a string/object (Node path /
+ *     auth-error path) otherwise. The Node path also sets `_handled` so h3
+ *     doesn't double-write.
+ */
+export declare function handleMcpRequest(event: H3Event, config: MCPConfig): Promise<Response | string | {
+    error: string;
+} | undefined>;
 /**
  * Mount an MCP remote server on an H3/Nitro app.
  *
  * Endpoint: `{routePrefix}/mcp` (default `/_agent-native/mcp`)
  *
  * Uses stateless Streamable HTTP transport — no in-memory sessions,
- * compatible with serverless deployments.
+ * compatible with serverless deployments. Runtime-agnostic: a real Node
+ * server uses the SDK's Node transport; the web-standard runtime (Nitro 3 /
+ * Netlify web runtime, Cloudflare, Deno, Bun) uses the SDK's web-standard
+ * transport. Both build the same server and produce identical JSON-RPC
+ * output.
  *
  * Auth: Bearer token matching ACCESS_TOKEN/ACCESS_TOKENS or JWT via A2A_SECRET.
  * No auth required when neither is configured (dev mode).

package/dist/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,yBAAyB,EACzB,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EACL,yBAAyB,EACzB,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,GACnB,CAAC;AACF,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC;AAM7D;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,GAAG,EACb,MAAM,EAAE,SAAS,EACjB,WAAW,SAAmB,GAC7B,IAAI,CAwHN"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AASlC,OAAO,EACL,yBAAyB,EACzB,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EACL,yBAAyB,EACzB,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,GACnB,CAAC;AACF,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC;AA2G7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,QAAQ,GAAG,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAgH5D;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,GAAG,EACb,MAAM,EAAE,SAAS,EACjB,WAAW,SAAmB,GAC7B,IAAI,CAYN"}

package/dist/mcp/server.js

@@ -7,98 +7,182 @@ import { createMCPServerForRequest, verifyAuth, getAccessTokens, resolveOrgIdFro
 // against `./server.js` exactly as before this refactor.
 export { createMCPServerForRequest, verifyAuth, getAccessTokens, resolveOrgIdFromDomain, buildLinkArtifacts, };
 // ---------------------------------------------------------------------------
-// mountMCP — register MCP Streamable HTTP endpoint on H3/Nitro
+// Runtime detection — Node fast-path vs. web-standard fallback
 // ---------------------------------------------------------------------------
 /**
- * Mount an MCP remote server on an H3/Nitro app.
+ * Resolve the underlying Node `http` req/res pair if (and only if) we're
+ * running on a real Node HTTP server (local dev, `node` Nitro preset). On the
+ * web-standard runtime (Nitro 3 / Netlify web runtime, Cloudflare, Deno, Bun)
+ * BOTH of these are undefined — that's the signal to take the web fallback
+ * instead of returning 501.
+ */
+function getNodeReqRes(event) {
+    const e = event;
+    const nodeReq = e.node?.req ?? e.req?.runtime?.node?.req;
+    const nodeRes = e.node?.res ?? e.req?.runtime?.node?.res;
+    return { nodeReq, nodeRes };
+}
+/**
+ * Derive the request origin + the markdown deep-link target from the inbound
+ * headers. Identical logic for both the Node and web paths so the absolute
+ * deep-link URLs in tool results are computed the same way regardless of
+ * runtime.
+ */
+function deriveRequestMeta(event) {
+    const forwardedProto = getRequestHeader(event, "x-forwarded-proto");
+    const host = getRequestHeader(event, "host");
+    const proto = forwardedProto?.split(",")[0]?.trim() ||
+        (host && /^(localhost|127\.0\.0\.1)(:|$)/.test(host) ? "http" : "https");
+    const origin = host ? `${proto}://${host}` : undefined;
+    const targetHeader = getRequestHeader(event, "x-agent-native-open-target")?.toLowerCase();
+    const target = targetHeader === "desktop" ||
+        targetHeader === "terminal" ||
+        targetHeader === "browser"
+        ? targetHeader
+        : undefined;
+    return { origin, target };
+}
+/**
+ * Reconstruct a Web Standard `Request` for the web-standard MCP transport.
  *
- * Endpoint: `{routePrefix}/mcp` (default `/_agent-native/mcp`)
+ * On the web runtime h3 v2 exposes the real web `Request` as `event.req`; we
+ * prefer it (its `method` / `headers` are exactly what the client sent). But
+ * the framework middleware rewrites `event.req.url` when it strips a mount
+ * prefix, and the transport reads `req.method` + `req.headers` (never the
+ * body — we pass that via `parsedBody`), so we always synthesize a clean
+ * `Request` with the verified method + a fresh `Headers` copy. The URL is
+ * cosmetic for the SDK (it only does `new URL(req.url)` for `requestInfo`),
+ * so a best-effort absolute URL derived from the inbound host is sufficient
+ * and never throws.
+ */
+function buildWebRequest(event, method) {
+    const src = event.req;
+    const headers = new Headers();
+    if (src?.headers && typeof src.headers.forEach === "function") {
+        src.headers.forEach((value, key) => headers.set(key, value));
+    }
+    else {
+        const rawHeaders = event.node?.req?.headers;
+        if (rawHeaders) {
+            for (const [key, value] of Object.entries(rawHeaders)) {
+                if (value == null)
+                    continue;
+                headers.set(key, Array.isArray(value) ? value.join(", ") : value);
+            }
+        }
+    }
+    // The SDK requires Accept + Content-Type to advertise both JSON and SSE on
+    // a POST. Real MCP clients (Claude Code, `agent-native connect`) always
+    // send these; we never inject/alter them — if they're absent the SDK
+    // returns its spec-mandated 406/415, identical to the Node path.
+    const host = headers.get("host") || "localhost";
+    const forwardedProto = headers.get("x-forwarded-proto");
+    const proto = forwardedProto?.split(",")[0]?.trim() ||
+        (/^(localhost|127\.0\.0\.1)(:|$)/.test(host) ? "http" : "https");
+    let url = `${proto}://${host}/_agent-native/mcp`;
+    try {
+        if (src?.url)
+            url = new URL(src.url).href;
+    }
+    catch {
+        // keep the synthesized URL
+    }
+    // No body here on purpose: the JSON-RPC payload is forwarded via the
+    // transport's `parsedBody` option (the same mechanism the Node transport
+    // uses), so the request stream is never read twice.
+    return new Request(url, { method, headers });
+}
+// ---------------------------------------------------------------------------
+// handleMcpRequest — runtime-agnostic MCP request handler
+// ---------------------------------------------------------------------------
+/**
+ * Handle a single `{routePrefix}/mcp` request on either runtime.
  *
- * Uses stateless Streamable HTTP transport — no in-memory sessions,
- * compatible with serverless deployments.
+ * - **Node fast-path** (real Node HTTP server): unchanged — delegate to the
+ *   SDK's `StreamableHTTPServerTransport.handleRequest(nodeReq, nodeRes,
+ *   body)`, which writes directly to the Node response (full protocol incl.
+ *   SSE).
+ * - **Web-standard fallback** (Nitro 3 / Netlify web runtime, Cloudflare,
+ *   Deno, Bun — where there is no Node req/res): build the SAME MCP `Server`
+ *   from the SAME config + identity, drive it through the SDK's
+ *   `WebStandardStreamableHTTPServerTransport` (which the Node transport is
+ *   itself just a thin wrapper around), and return the resulting Web
+ *   `Response` as a normal h3 return value.
  *
- * Auth: Bearer token matching ACCESS_TOKEN/ACCESS_TOKENS or JWT via A2A_SECRET.
- * No auth required when neither is configured (dev mode).
+ * Auth, the `runWithRequestContext` identity wrap, the deep-link `_meta` /
+ * markdown append, `requestMeta` origin/target derivation and the stateless
+ * semantics are IDENTICAL on both paths because both build the same server
+ * via `createMCPServerForRequest` and both transports funnel into the same
+ * `WebStandardStreamableHTTPServerTransport.handleRequest(webRequest, {
+ * parsedBody })` with the same options.
+ *
+ * Returns:
+ *   - `undefined` when the request targets a sub-route (so management/status
+ *     routes mounted under `/_agent-native/mcp/*` handle it themselves) — the
+ *     h3 mount falls through to the next handler.
+ *   - a Web `Response` (web fallback) or a string/object (Node path /
+ *     auth-error path) otherwise. The Node path also sets `_handled` so h3
+ *     doesn't double-write.
  */
-export function mountMCP(nitroApp, config, routePrefix = "/_agent-native") {
-    getH3App(nitroApp).use(`${routePrefix}/mcp`, defineEventHandler(async (event) => {
-        const pathname = event.url?.pathname || "/";
-        const subpath = pathname.replace(/^\/+/, "").replace(/\/+$/, "");
-        if (subpath) {
-            // Let management/status routes mounted under /_agent-native/mcp/*
-            // handle their own requests instead of treating them as MCP protocol
-            // traffic.
-            return;
-        }
-        const method = getMethod(event);
-        // Auth check — extracts the caller's identity from the JWT (`sub`),
-        // or, on the static-token / dev-open path, from the forwarded
-        // `X-Agent-Native-Owner-Email` hint the stdio proxy sends (the
-        // `agent-native mcp install` flow). Without this the install flow
-        // would run every tool unscoped (userEmail === undefined).
-        const authHeader = getRequestHeader(event, "authorization");
-        const ownerEmailHeader = getRequestHeader(event, "x-agent-native-owner-email");
-        const authResult = await verifyAuth(authHeader, ownerEmailHeader);
-        if (!authResult.authed) {
-            setResponseStatus(event, 401);
-            return { error: "Unauthorized" };
-        }
-        // Stateless mode: only POST is meaningful
-        if (method === "DELETE") {
-            setResponseStatus(event, 204);
-            return "";
-        }
-        if (method === "GET") {
-            // SSE stream endpoint — not used in stateless mode but the SDK
-            // handles it gracefully. Let it through for protocol compliance.
-        }
-        if (method !== "POST" && method !== "GET") {
-            setResponseStatus(event, 405);
-            return { error: "Method not allowed" };
-        }
-        // Read body for POST (GET has no body)
-        const body = method === "POST" ? await readBody(event) : undefined;
-        // Create per-request stateless transport + server
+export async function handleMcpRequest(event, config) {
+    const pathname = event.url?.pathname || "/";
+    const subpath = pathname.replace(/^\/+/, "").replace(/\/+$/, "");
+    if (subpath) {
+        // Let management/status routes mounted under /_agent-native/mcp/* handle
+        // their own requests instead of treating them as MCP protocol traffic.
+        return undefined;
+    }
+    const method = getMethod(event);
+    // Auth check — extracts the caller's identity from the JWT (`sub`), or, on
+    // the static-token / dev-open path, from the forwarded
+    // `X-Agent-Native-Owner-Email` hint the stdio proxy sends (the
+    // `agent-native mcp install` flow). Without this the install flow would run
+    // every tool unscoped (userEmail === undefined).
+    const authHeader = getRequestHeader(event, "authorization");
+    const ownerEmailHeader = getRequestHeader(event, "x-agent-native-owner-email");
+    const authResult = await verifyAuth(authHeader, ownerEmailHeader);
+    if (!authResult.authed) {
+        setResponseStatus(event, 401);
+        return { error: "Unauthorized" };
+    }
+    // Stateless mode: only POST is meaningful
+    if (method === "DELETE") {
+        setResponseStatus(event, 204);
+        return "";
+    }
+    if (method !== "POST" && method !== "GET") {
+        setResponseStatus(event, 405);
+        return { error: "Method not allowed" };
+    }
+    // Read body for POST (GET has no body). Read it via the h3 helper exactly
+    // once; both transports accept it as a pre-parsed body so the request
+    // stream is never consumed twice.
+    const body = method === "POST" ? await readBody(event) : undefined;
+    // Per-request stateless transport + server. Both runtimes build the SAME
+    // server from the SAME config + verified identity + request meta, so
+    // tools/list, tools/call, and the deep-link `_meta` are identical.
+    const requestMeta = deriveRequestMeta(event);
+    const server = await createMCPServerForRequest(config, authResult.identity, requestMeta);
+    const { nodeReq, nodeRes } = getNodeReqRes(event);
+    if (nodeReq && nodeRes) {
+        // ---- Node fast-path (UNCHANGED behavior) --------------------------------
         const { StreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/streamableHttp.js");
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: undefined, // stateless
         });
-        // Derive the running app's origin so relative deep links become
-        // absolute URLs the external agent can open (same approach as A2A).
-        const forwardedProto = getRequestHeader(event, "x-forwarded-proto");
-        const host = getRequestHeader(event, "host");
-        const proto = forwardedProto?.split(",")[0]?.trim() ||
-            (host && /^(localhost|127\.0\.0\.1)(:|$)/.test(host)
-                ? "http"
-                : "https");
-        const origin = host ? `${proto}://${host}` : undefined;
-        const targetHeader = getRequestHeader(event, "x-agent-native-open-target")?.toLowerCase();
-        const target = targetHeader === "desktop" ||
-            targetHeader === "terminal" ||
-            targetHeader === "browser"
-            ? targetHeader
-            : undefined;
-        const server = await createMCPServerForRequest(config, authResult.identity, { origin, target });
         await server.connect(transport);
-        // Delegate to the transport — it writes directly to the Node response.
-        // MCP's HTTP transport requires Node streams; this route is Node-only.
-        const nodeReq = event.node?.req ?? event.req?.runtime?.node?.req;
-        const nodeRes = event.node?.res ?? event.req?.runtime?.node?.res;
-        if (!nodeReq || !nodeRes) {
-            setResponseStatus(event, 501);
-            return { error: "MCP requires Node runtime" };
-        }
         try {
+            // The SDK transport writes directly to the Node response. Node-only by
+            // construction; we only reach here when real Node req/res exist.
             await transport.handleRequest(nodeReq, nodeRes, body);
         }
         catch (err) {
-            // The SDK transport writes directly to the Node response. If the
-            // socket is already closed/ended (client disconnected, or the host
-            // stream layer also flushed), Node throws ERR_STREAM_WRITE_AFTER_END
-            // *after* the MCP payload was already delivered correctly. Swallow
-            // that benign post-flush write so an external agent disconnecting
-            // mid-stream can never take down the server process; rethrow
-            // anything else.
+            // The SDK transport writes directly to the Node response. If the socket
+            // is already closed/ended (client disconnected, or the host stream
+            // layer also flushed), Node throws ERR_STREAM_WRITE_AFTER_END *after*
+            // the MCP payload was already delivered correctly. Swallow that benign
+            // post-flush write so an external agent disconnecting mid-stream can
+            // never take down the server process; rethrow anything else.
             if (err?.code !== "ERR_STREAM_WRITE_AFTER_END")
                 throw err;
             if (process.env.DEBUG)
@@ -106,6 +190,53 @@ export function mountMCP(nitroApp, config, routePrefix = "/_agent-native") {
         }
         // Prevent H3 from double-writing the response
         event._handled = true;
+        return undefined;
+    }
+    // ---- Web-standard fallback (Nitro 3 / Netlify web runtime, CF, Deno,
+    // Bun) ---------------------------------------------------------------------
+    //
+    // `StreamableHTTPServerTransport` is itself just a thin wrapper that
+    // converts the Node req/res to a web Request/Response and delegates to
+    // `WebStandardStreamableHTTPServerTransport.handleRequest(webRequest, {
+    // parsedBody })`. Using the web transport directly with the SAME options +
+    // the same pre-read `parsedBody` produces byte-identical protocol output
+    // (including the deep-link `_meta` built inside createMCPServerForRequest),
+    // and works on every web runtime because it returns a Web `Response`
+    // (JSON for request/response, or an SSE `ReadableStream` body which h3
+    // streams natively).
+    const { WebStandardStreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js");
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined, // stateless — same as the Node path
+    });
+    await server.connect(transport);
+    const webRequest = buildWebRequest(event, method);
+    // `parsedBody: undefined` would make the SDK try to read `req.json()`; our
+    // synthesized request has no body, so only pass the option for POST (where
+    // we actually have a parsed body). For GET the transport reads no body.
+    const response = await transport.handleRequest(webRequest, method === "POST" ? { parsedBody: body } : undefined);
+    return response;
+}
+// ---------------------------------------------------------------------------
+// mountMCP — register MCP Streamable HTTP endpoint on H3/Nitro
+// ---------------------------------------------------------------------------
+/**
+ * Mount an MCP remote server on an H3/Nitro app.
+ *
+ * Endpoint: `{routePrefix}/mcp` (default `/_agent-native/mcp`)
+ *
+ * Uses stateless Streamable HTTP transport — no in-memory sessions,
+ * compatible with serverless deployments. Runtime-agnostic: a real Node
+ * server uses the SDK's Node transport; the web-standard runtime (Nitro 3 /
+ * Netlify web runtime, Cloudflare, Deno, Bun) uses the SDK's web-standard
+ * transport. Both build the same server and produce identical JSON-RPC
+ * output.
+ *
+ * Auth: Bearer token matching ACCESS_TOKEN/ACCESS_TOKENS or JWT via A2A_SECRET.
+ * No auth required when neither is configured (dev mode).
+ */
+export function mountMCP(nitroApp, config, routePrefix = "/_agent-native") {
+    getH3App(nitroApp).use(`${routePrefix}/mcp`, defineEventHandler(async (event) => {
+        return handleMcpRequest(event, config);
     }));
     if (process.env.DEBUG)
         console.log(`[mcp] Mounted MCP server at ${routePrefix}/mcp (${Object.keys(config.actions).length} tools${config.askAgent ? " + ask-agent" : ""})`);