From d41e4e1dd7185ba6f0a0b3b78da4b98072da7578 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Mon, 24 Aug 2026 00:59:02 -0400
Subject: [PATCH 01/14] fix(auth): don't answer token_expired from an
 unknowable local expiry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`checkAuthChallengeSatisfied` answered a `token_expired` challenge with
`isAccessTokenUsable`, which treats "we cannot tell" as "still valid":
`isJwtExpired` returns false whenever the token is not a JWT or carries no
`exp`, and storage never records an absolute expiry (`expires_in` is relative
to an issuance instant that is never persisted).

So for an opaque access token — Doorkeeper, Keycloak in opaque mode,
GitHub-style `gho_…` — the local guess outvoted the resource server's
explicit verdict. Callers short-circuited re-authorization and reconnected
with the same dead credential, looping with no redirect and no ReAuthBanner.
A bare 401 also maps to `token_expired`, so this was not limited to servers
sending `error="invalid_token"`.

Adds `isAccessTokenProvablyUnexpired` beside `isAccessTokenUsable` in
`core/auth/connection-state.ts`: true only for a JWT whose `exp` is still in
the future (same 60s skew). `checkAuthChallengeSatisfied` uses it for the
`token_expired` branch, so absence of local evidence no longer beats the
server, while a provably live JWT keeps its cheap short-circuit.

`isAccessTokenUsable` stays optimistic — it is the right default for
displaying authorization state, and flipping it would show every
opaque-token server as unauthorized.

Closes #2051

Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../test/core/auth/connection-state.test.ts   | 72 +++++++++++++++++++
 .../src/test/core/mcp/oauthManager.test.ts    | 43 ++++++++++-
 core/auth/connection-state.ts                 | 32 ++++++++-
 core/mcp/oauthManager.ts                      | 14 ++--
 4 files changed, 152 insertions(+), 9 deletions(-)

diff --git a/clients/web/src/test/core/auth/connection-state.test.ts b/clients/web/src/test/core/auth/connection-state.test.ts
index cb5f351b..8898b263 100644
--- a/clients/web/src/test/core/auth/connection-state.test.ts
+++ b/clients/web/src/test/core/auth/connection-state.test.ts
@@ -2,6 +2,8 @@ import { describe, it, expect, vi } from "vitest";
 import {
   buildOAuthConnectionState,
   hasPersistedOAuthServerState,
+  isAccessTokenProvablyUnexpired,
+  isAccessTokenUsable,
   isServerOAuthConfigured,
   protocolFromOAuthConfig,
 } from "@inspector/core/auth/connection-state.js";
@@ -257,3 +259,73 @@ describe("buildOAuthConnectionState", () => {
     expect(state.ema).not.toHaveProperty("idToken");
   });
 });
+
+/** Minimal unsigned JWT carrying only `exp` (epoch seconds). */
+function jwtWithExp(expSec: number): string {
+  const payload = btoa(JSON.stringify({ exp: expSec }))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return `header.${payload}.sig`;
+}
+
+const nowSec = () => Math.floor(Date.now() / 1000);
+
+describe("isAccessTokenProvablyUnexpired", () => {
+  it("is true for a JWT whose exp is in the future", () => {
+    expect(
+      isAccessTokenProvablyUnexpired({
+        access_token: jwtWithExp(nowSec() + 3600),
+        token_type: "Bearer",
+      }),
+    ).toBe(true);
+  });
+
+  it("is false for a JWT whose exp has passed", () => {
+    expect(
+      isAccessTokenProvablyUnexpired({
+        access_token: jwtWithExp(nowSec() - 60),
+        token_type: "Bearer",
+      }),
+    ).toBe(false);
+  });
+
+  it("is false inside the 60s expiry skew window", () => {
+    expect(
+      isAccessTokenProvablyUnexpired({
+        access_token: jwtWithExp(nowSec() + 30),
+        token_type: "Bearer",
+      }),
+    ).toBe(false);
+  });
+
+  it("is false for an opaque token, where isAccessTokenUsable is true", () => {
+    // The #2051 regression: no local expiry evidence must not read as "valid".
+    const tokens = { access_token: "opaque-tok", token_type: "Bearer" };
+    expect(isAccessTokenProvablyUnexpired(tokens)).toBe(false);
+    expect(isAccessTokenUsable(tokens)).toBe(true);
+  });
+
+  it("is false for a JWT carrying no exp claim", () => {
+    const payload = btoa(JSON.stringify({ sub: "user" }))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+    expect(
+      isAccessTokenProvablyUnexpired({
+        access_token: `header.${payload}.sig`,
+        token_type: "Bearer",
+      }),
+    ).toBe(false);
+  });
+
+  it("is false when there is no access token", () => {
+    expect(isAccessTokenProvablyUnexpired(undefined)).toBe(false);
+    expect(
+      isAccessTokenProvablyUnexpired({
+        access_token: "",
+        token_type: "Bearer",
+      }),
+    ).toBe(false);
+  });
+});
diff --git a/clients/web/src/test/core/mcp/oauthManager.test.ts b/clients/web/src/test/core/mcp/oauthManager.test.ts
index 1fbdf8e9..59ba1bfb 100644
--- a/clients/web/src/test/core/mcp/oauthManager.test.ts
+++ b/clients/web/src/test/core/mcp/oauthManager.test.ts
@@ -27,6 +27,15 @@ const mockedMcpAuth = vi.mocked(mcpAuth);
 
 const SERVER_URL = "https://example.com/mcp";
 
+/** Minimal unsigned JWT carrying only `exp` (epoch seconds). */
+function jwtWithExp(expSec: number): string {
+  const payload = btoa(JSON.stringify({ exp: expSec }))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return `header.${payload}.sig`;
+}
+
 function createMockParams(
   overrides?: Partial<OAuthManagerParams>,
 ): OAuthManagerParams {
@@ -988,10 +997,10 @@ describe("OAuthManager", () => {
       ).toBe(false);
     });
 
-    it("returns true for token_expired when a usable access token exists", async () => {
+    it("returns true for token_expired when a provably unexpired JWT exists", async () => {
       const params = createMockParams();
       storageOf(params).getTokens.mockResolvedValue({
-        access_token: "tok",
+        access_token: jwtWithExp(Math.floor(Date.now() / 1000) + 3600),
         token_type: "Bearer",
       });
       const manager = new OAuthManager(params);
@@ -1001,6 +1010,36 @@ describe("OAuthManager", () => {
       ).toBe(true);
     });
 
+    it("returns false for token_expired when the stored JWT has expired", async () => {
+      const params = createMockParams();
+      storageOf(params).getTokens.mockResolvedValue({
+        access_token: jwtWithExp(Math.floor(Date.now() / 1000) - 60),
+        token_type: "Bearer",
+      });
+      const manager = new OAuthManager(params);
+
+      expect(
+        await manager.checkAuthChallengeSatisfied({ reason: "token_expired" }),
+      ).toBe(false);
+    });
+
+    it("returns false for token_expired when the stored token is opaque", async () => {
+      // Regression guard for #2051: an opaque token has no local expiry
+      // evidence, so it must not outvote the resource server's verdict and
+      // short-circuit re-authorization into replaying a dead credential.
+      const params = createMockParams();
+      storageOf(params).getTokens.mockResolvedValue({
+        access_token: "opaque-tok",
+        token_type: "Bearer",
+        expires_in: 900,
+      });
+      const manager = new OAuthManager(params);
+
+      expect(
+        await manager.checkAuthChallengeSatisfied({ reason: "token_expired" }),
+      ).toBe(false);
+    });
+
     it("returns false for invalid_token even when a locally valid token exists", async () => {
       const params = createMockParams();
       storageOf(params).getTokens.mockResolvedValue({
diff --git a/core/auth/connection-state.ts b/core/auth/connection-state.ts
index 8d20d7e2..58f8c0df 100644
--- a/core/auth/connection-state.ts
+++ b/core/auth/connection-state.ts
@@ -5,7 +5,7 @@ import type {
 import type { EnterpriseManagedAuthIdpConfig } from "../client/types.js";
 import { getEmaIdpLoginState, normalizeIdpIssuer } from "./ema/idpSession.js";
 import { idpOAuthStorageKey } from "./ema/storage.js";
-import { isJwtExpired } from "./ema/jwt.js";
+import { isJwtExpired, jwtExpiresAtMs } from "./ema/jwt.js";
 import type { OAuthStorage } from "./storage.js";
 import type {
   AuthProtocol,
@@ -24,12 +24,40 @@ export interface BuildOAuthConnectionStateParams {
   flowState?: OAuthFlowState;
 }
 
-/** True when persisted tokens include a non-expired access token (JWT exp when parseable). */
+/**
+ * True when persisted tokens include a non-expired access token (JWT exp when parseable).
+ *
+ * Optimistic: an access token whose expiry cannot be determined locally — an
+ * opaque token, or a JWT with no `exp` — counts as usable. Storage keeps no
+ * absolute expiry for those, because `expires_in` is relative to an issuance
+ * instant that is never recorded. That is the right default for *displaying*
+ * authorization state (an opaque-token server would otherwise always read as
+ * unauthorized), and the wrong one once a resource server has actually rejected
+ * the credential — see {@link isAccessTokenProvablyUnexpired}.
+ */
 export function isAccessTokenUsable(tokens: OAuthTokens | undefined): boolean {
   if (!tokens?.access_token) return false;
   return !isJwtExpired(tokens.access_token);
 }
 
+/**
+ * Pessimistic counterpart to {@link isAccessTokenUsable}: true only when the
+ * access token is a JWT carrying an `exp` that is still in the future (same 60s
+ * skew as {@link isJwtExpired}).
+ *
+ * Absence of local expiry evidence returns `false` rather than `true`, so it
+ * cannot outvote a resource server that has explicitly said the token is
+ * expired. Use this — not `isAccessTokenUsable` — to decide whether a
+ * `token_expired` challenge is already satisfied.
+ */
+export function isAccessTokenProvablyUnexpired(
+  tokens: OAuthTokens | undefined,
+): boolean {
+  if (!tokens?.access_token) return false;
+  if (jwtExpiresAtMs(tokens.access_token) === undefined) return false;
+  return !isJwtExpired(tokens.access_token);
+}
+
 function resolveClient(
   preregistered: OAuthClientInformation | undefined,
   dynamic: OAuthClientInformation | undefined,
diff --git a/core/mcp/oauthManager.ts b/core/mcp/oauthManager.ts
index 59846e2a..732f03d1 100644
--- a/core/mcp/oauthManager.ts
+++ b/core/mcp/oauthManager.ts
@@ -26,7 +26,7 @@ import {
 import {
   buildOAuthConnectionState,
   hasPersistedOAuthServerState,
-  isAccessTokenUsable,
+  isAccessTokenProvablyUnexpired,
   isServerOAuthConfigured,
   protocolFromOAuthConfig,
 } from "../auth/connection-state.js";
@@ -494,9 +494,12 @@ export class OAuthManager {
    * satisfied without an authorization-server round-trip.
    *
    * Returns `true` for `insufficient_scope` when stored + token scope cover the
-   * SEP-2350 union. For `token_expired`, returns `true` when a usable access
-   * token is already in storage. `invalid_token` and `unauthorized` always
-   * return `false` — the resource server explicitly rejected the credential.
+   * SEP-2350 union. For `token_expired`, returns `true` only when storage holds
+   * a *provably* unexpired token — a JWT whose `exp` is still in the future. An
+   * opaque token carries no local expiry evidence, so the resource server's
+   * verdict stands and re-authorization proceeds. `invalid_token` and
+   * `unauthorized` always return `false` — the resource server explicitly
+   * rejected the credential.
    */
   async checkAuthChallengeSatisfied(
     challenge: AuthChallenge,
@@ -514,7 +517,8 @@ export class OAuthManager {
 
     if (challenge.reason !== "insufficient_scope") {
       return (
-        challenge.reason === "token_expired" && isAccessTokenUsable(tokens)
+        challenge.reason === "token_expired" &&
+        isAccessTokenProvablyUnexpired(tokens)
       );
     }
 

From 268bfa108546a646073d1d4879c6ccc91cc2eb29 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Mon, 24 Aug 2026 01:02:02 -0400
Subject: [PATCH 02/14] fix(web): state the expected shape when dropping a CSP
 source (#2064)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`approveCspSources` warned "dropping unsafe CSP source", which states a
security verdict the check never makes: `SAFE_CSP_SOURCE` screens each
entry for injection safety only, and deliberately does not bound how
broad a grant is (`resourceDomains: ["*"]` passes).

The four fields are origin lists, so the real cause of a drop is almost
always that the entry isn't an origin — a CSP keyword such as
`'unsafe-eval'` has no field in the contract to be requested through.
Reading it as a safety verdict is what sent #2012 chasing an XSS
regression that wasn't one.

The message now names the field the entry came from (so an app declaring
several lists can tell which one was bad) and states the shape expected,
with no claim about the value's safety.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UL9retfvAXRgvi6EWk4SY4
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/utils/sandbox-csp.test.ts | 23 +++++++++++++++++++++
 clients/web/src/utils/sandbox-csp.ts      | 25 +++++++++++++++++------
 2 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/clients/web/src/utils/sandbox-csp.test.ts b/clients/web/src/utils/sandbox-csp.test.ts
index 95b2de94..15042e23 100644
--- a/clients/web/src/utils/sandbox-csp.test.ts
+++ b/clients/web/src/utils/sandbox-csp.test.ts
@@ -67,6 +67,29 @@ describe("approveCspSources", () => {
     warn.mockRestore();
   });
 
+  it("names the offending field and states the expected shape, without calling the value unsafe", () => {
+    // #2064: the filter screens for injection safety only, so the message must
+    // not read as a verdict on the value. These four fields are origin lists,
+    // so the real cause is almost always "not an origin" — a CSP keyword has
+    // no field in the contract to be requested through. Naming the key also
+    // tells an app declaring several lists which one the bad entry was in.
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    approveCspSources({
+      connectDomains: ["'unsafe-eval'"],
+      frameDomains: ["<script>"],
+    });
+    const messages = warn.mock.calls.map(([message]) => String(message));
+    expect(messages).toHaveLength(2);
+    expect(messages[0]).toContain('"connectDomains"');
+    expect(messages[1]).toContain('"frameDomains"');
+    for (const message of messages) {
+      expect(message).toContain("expected an origin");
+      expect(message).not.toContain("unsafe");
+    }
+    expect(warn.mock.calls[0]?.[1]).toBe("'unsafe-eval'");
+    warn.mockRestore();
+  });
+
   it("omits a key when every entry is rejected", () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
     expect(approveCspSources({ connectDomains: ['"; x'] })).toEqual({});
diff --git a/clients/web/src/utils/sandbox-csp.ts b/clients/web/src/utils/sandbox-csp.ts
index 83c38845..6a3352cb 100644
--- a/clients/web/src/utils/sandbox-csp.ts
+++ b/clients/web/src/utils/sandbox-csp.ts
@@ -41,11 +41,11 @@ const CSP_KEYS = exhaustiveCspKeys([
 
 /**
  * Filter an app-supplied {@link McpUiResourceCsp} down to the entries the host
- * will actually enforce. Unsafe values are dropped (and warned), and the
- * resulting object contains only keys with at least one accepted source. The
- * return value is what the host echoes back to the view via
- * `hostCapabilities.sandbox.csp` so the app sees what was granted, not what it
- * asked for.
+ * will actually enforce. Entries that don't parse as a source expression are
+ * dropped (and warned), and the resulting object contains only keys with at
+ * least one accepted source. The return value is what the host echoes back to
+ * the view via `hostCapabilities.sandbox.csp` so the app sees what was granted,
+ * not what it asked for.
  *
  * NOTE: this screens each source for *injection safety* only — it does NOT
  * bound the *breadth* of a grant. A bare `*` (and a scheme-wildcard host) is a
@@ -56,6 +56,14 @@ const CSP_KEYS = exhaustiveCspKeys([
  * ambient credentials and nothing to exfiltrate beyond what the app already
  * received; "approved" therefore means "cannot break out of the meta
  * attribute," not "restrictive."
+ *
+ * The drop warning is worded accordingly: it names the field the entry came
+ * from and states the shape expected, and makes no claim about the *safety* of
+ * the value. These four fields are origin lists, so the usual cause of a drop
+ * is an entry that simply isn't an origin — a CSP keyword such as
+ * `'unsafe-eval'` has no field in the contract to be requested through. Saying
+ * "unsafe" instead read as a security verdict this check never makes, and sent
+ * #2012 chasing an XSS regression that wasn't one (#2064).
  */
 export function approveCspSources(
   csp: McpUiResourceCsp | undefined,
@@ -70,7 +78,12 @@ export function approveCspSources(
       if (typeof entry === "string" && SAFE_CSP_SOURCE.test(entry)) {
         accepted.push(entry);
       } else {
-        console.warn("[mcp-app sandbox] dropping unsafe CSP source:", entry);
+        console.warn(
+          `[mcp-app sandbox] dropping "${key}" entry (expected an origin such ` +
+            `as https://example.com or https://*.example.com, a scheme such as ` +
+            `data:, or *):`,
+          entry,
+        );
       }
     }
     if (accepted.length > 0) approved[key] = accepted;

From 99f8ccde18d32be149b3766c5ead1c4a02e9a818 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Mon, 24 Aug 2026 01:20:18 -0400
Subject: [PATCH 03/14] docs(web): describe the accepted subset, not "parses as
 a source expression"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review catch: `'unsafe-eval'` *is* a valid CSP source expression, so saying
the filter drops entries that "don't parse as a source expression" was both
wrong and a rerun of the misconception this PR set out to fix — and it
contradicted the NOTE two paragraphs down.

The doc now names the accepted subset (`scheme://host[:port][/path]`, a bare
or wildcard host, a scheme such as `data:`, and `*`) and says explicitly that
a CSP keyword is a valid source expression these origin-list fields simply
cannot express. The now-duplicated half of the third paragraph is trimmed.

Comment-only; the warning string and tests are unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UL9retfvAXRgvi6EWk4SY4
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/src/utils/sandbox-csp.ts | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/clients/web/src/utils/sandbox-csp.ts b/clients/web/src/utils/sandbox-csp.ts
index 6a3352cb..78d32431 100644
--- a/clients/web/src/utils/sandbox-csp.ts
+++ b/clients/web/src/utils/sandbox-csp.ts
@@ -41,11 +41,15 @@ const CSP_KEYS = exhaustiveCspKeys([
 
 /**
  * Filter an app-supplied {@link McpUiResourceCsp} down to the entries the host
- * will actually enforce. Entries that don't parse as a source expression are
- * dropped (and warned), and the resulting object contains only keys with at
- * least one accepted source. The return value is what the host echoes back to
- * the view via `hostCapabilities.sandbox.csp` so the app sees what was granted,
- * not what it asked for.
+ * will actually enforce. The accepted subset is the origin forms
+ * {@link SAFE_CSP_SOURCE} matches — `scheme://host[:port][/path]`, a bare or
+ * wildcard host, a scheme such as `data:`, and `*`. Anything outside it is
+ * dropped (and warned) — including a CSP keyword like `'unsafe-eval'`, which
+ * is a perfectly valid source expression in CSP but not something these
+ * origin-list fields can express. The resulting object contains only keys with
+ * at least one accepted source, and is what the host echoes back to the view
+ * via `hostCapabilities.sandbox.csp` so the app sees what was granted, not what
+ * it asked for.
  *
  * NOTE: this screens each source for *injection safety* only — it does NOT
  * bound the *breadth* of a grant. A bare `*` (and a scheme-wildcard host) is a
@@ -59,11 +63,9 @@ const CSP_KEYS = exhaustiveCspKeys([
  *
  * The drop warning is worded accordingly: it names the field the entry came
  * from and states the shape expected, and makes no claim about the *safety* of
- * the value. These four fields are origin lists, so the usual cause of a drop
- * is an entry that simply isn't an origin — a CSP keyword such as
- * `'unsafe-eval'` has no field in the contract to be requested through. Saying
- * "unsafe" instead read as a security verdict this check never makes, and sent
- * #2012 chasing an XSS regression that wasn't one (#2064).
+ * the value. Saying "unsafe" instead read as a security verdict this check
+ * never makes, and sent #2012 chasing an XSS regression that wasn't one, when
+ * the entry had merely been the wrong kind of thing for the field (#2064).
  */
 export function approveCspSources(
   csp: McpUiResourceCsp | undefined,

From c20fce9ba28e6b25a2bf5dd2243153244f2e69c4 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Mon, 24 Aug 2026 07:35:40 -0400
Subject: [PATCH 04/14] docs(spec): align mid-session auth spec with the
 token_expired predicate

Copilot review on #2105: specification/v2_auth_mid_session.md still said
checkAuthChallengeSatisfied is satisfied for token_expired / unauthorized by
any valid non-expired token. Only token_expired can short-circuit, and only
for a provably unexpired JWT; invalid_token and unauthorized are always false
(which the code already did before this branch).

Signed-off-by: cliffhall <cliff@futurescale.com>
---
 specification/v2_auth_mid_session.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/specification/v2_auth_mid_session.md b/specification/v2_auth_mid_session.md
index 8c39883e..cf714040 100644
--- a/specification/v2_auth_mid_session.md
+++ b/specification/v2_auth_mid_session.md
@@ -206,7 +206,8 @@ export type AuthChallengeOutcome =
 
 Read-only check against **current storage** (and token expiry helpers). Used before starting visible OAuth — especially when a background browser tab regains focus and another tab may have already re-authenticated. Does **not** call the authorization server.
 
-- **`token_expired` / `unauthorized`:** valid non-expired access token in storage.
+- **`token_expired`:** a **provably** unexpired access token in storage — a JWT whose `exp` is still in the future (60s skew). Storage records no absolute expiry for an opaque token (`expires_in` is relative to an issuance instant that is never persisted), so "expiry unknown" returns **false**: the resource server has said the credential is dead, and no local evidence contradicts it. Otherwise an opaque token would be replayed forever ([#2051](https://github.com/modelcontextprotocol/inspector/issues/2051)).
+- **`invalid_token` / `unauthorized`:** always **false** — the resource server explicitly rejected the credential.
 - **`insufficient_scope`:** stored/token scope is a superset of required / union scopes. Empty scope on an `insufficient_scope` challenge returns **false** (do not short-circuit).
 
 ### Strategy by protocol

From deca2de60443633178efa3f29f7981ec39f67502 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Mon, 24 Aug 2026 07:46:10 -0400
Subject: [PATCH 05/14] fix(auth): require JWT shape before trusting exp as
 proof of validity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copilot review on #2105: jwtExpiresAtMs is lenient — it parses the second of
any two-or-more dot-separated segments — so a structured opaque token such as
`opaque.<base64url({"exp":...})>` returned a parseable exp and could still
short-circuit re-authorization, recreating the replay loop.

isAccessTokenProvablyUnexpired now checks isJwtFormat first. Tests cover a
two-segment and a four-segment token whose payload decodes to a future exp.

Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../test/core/auth/connection-state.test.ts   | 29 +++++++++++++++++++
 core/auth/connection-state.ts                 | 10 ++++++-
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/clients/web/src/test/core/auth/connection-state.test.ts b/clients/web/src/test/core/auth/connection-state.test.ts
index 8898b263..f8235d4a 100644
--- a/clients/web/src/test/core/auth/connection-state.test.ts
+++ b/clients/web/src/test/core/auth/connection-state.test.ts
@@ -319,6 +319,35 @@ describe("isAccessTokenProvablyUnexpired", () => {
     ).toBe(false);
   });
 
+  it("is false for a two-segment token whose payload decodes to an exp", () => {
+    // jwtExpiresAtMs only requires two dot-separated segments, so a structured
+    // opaque token carrying a decodable `{"exp":...}` would otherwise read as
+    // proof of validity. isJwtFormat is what rejects it.
+    const payload = btoa(JSON.stringify({ exp: nowSec() + 3600 }))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+    expect(
+      isAccessTokenProvablyUnexpired({
+        access_token: `opaque.${payload}`,
+        token_type: "Bearer",
+      }),
+    ).toBe(false);
+  });
+
+  it("is false for a four-segment token carrying a decodable exp", () => {
+    const payload = btoa(JSON.stringify({ exp: nowSec() + 3600 }))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+    expect(
+      isAccessTokenProvablyUnexpired({
+        access_token: `header.${payload}.sig.extra`,
+        token_type: "Bearer",
+      }),
+    ).toBe(false);
+  });
+
   it("is false when there is no access token", () => {
     expect(isAccessTokenProvablyUnexpired(undefined)).toBe(false);
     expect(
diff --git a/core/auth/connection-state.ts b/core/auth/connection-state.ts
index 58f8c0df..4ae95d4b 100644
--- a/core/auth/connection-state.ts
+++ b/core/auth/connection-state.ts
@@ -5,7 +5,7 @@ import type {
 import type { EnterpriseManagedAuthIdpConfig } from "../client/types.js";
 import { getEmaIdpLoginState, normalizeIdpIssuer } from "./ema/idpSession.js";
 import { idpOAuthStorageKey } from "./ema/storage.js";
-import { isJwtExpired, jwtExpiresAtMs } from "./ema/jwt.js";
+import { isJwtExpired, isJwtFormat, jwtExpiresAtMs } from "./ema/jwt.js";
 import type { OAuthStorage } from "./storage.js";
 import type {
   AuthProtocol,
@@ -49,11 +49,19 @@ export function isAccessTokenUsable(tokens: OAuthTokens | undefined): boolean {
  * cannot outvote a resource server that has explicitly said the token is
  * expired. Use this — not `isAccessTokenUsable` — to decide whether a
  * `token_expired` challenge is already satisfied.
+ *
+ * The shape is checked with {@link isJwtFormat} before the `exp` is trusted.
+ * {@link jwtExpiresAtMs} is deliberately lenient — it parses the second of any
+ * two-or-more dot-separated segments — so a structured opaque token that merely
+ * happens to carry a decodable `{"exp":…}` segment would otherwise be read as
+ * proof, which is exactly the "guess beats the server" failure this predicate
+ * exists to remove.
  */
 export function isAccessTokenProvablyUnexpired(
   tokens: OAuthTokens | undefined,
 ): boolean {
   if (!tokens?.access_token) return false;
+  if (!isJwtFormat(tokens.access_token)) return false;
   if (jwtExpiresAtMs(tokens.access_token) === undefined) return false;
   return !isJwtExpired(tokens.access_token);
 }

From ec40cf5531f57caf5a0ac1b9a044e2a51e78b94b Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 23:03:55 -0400
Subject: [PATCH 06/14] feat(web): honor _meta.ui.domain with a dedicated app
 origin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An MCP App is rendered by handing its HTML to the sandbox proxy as
`srcdoc`, in a frame sandboxed without `allow-same-origin` — the #1565
isolation model. That gives the app document an opaque origin, so every
request it makes carries `Origin: null` and no CORS / OAuth-callback /
API-key allowlist can admit it. `_meta.ui.domain` is the spec field a
server uses to ask its host for a stable, dedicated origin, and it was
being dropped on the floor.

The field is explicitly host-dependent and the Inspector owns no domain
infrastructure, so it treats any non-empty value as a request rather than
an address, and answers with a real loopback origin on its own listener
(MCP_APP_ORIGIN_PORT, default 6276). One shared origin, path-keyed per
document: that delivers what the field is for without minting a port or
DNS name per app, and is therefore not a per-app isolation boundary.

The inner frame is granted `allow-same-origin` on this path only, which
is what makes the origin real. It is not a #1565 regression: the listener
is on its own port, so the app stays cross-origin to both the proxy and
the Inspector. The proxy refuses the grant if the URL's origin equals its
own, and the grant is never reachable from the server-supplied `sandbox`
string, which is still stripped. The per-app CSP is delivered as a real
response header there rather than only as a <meta>.

Every failure path falls back to the default srcdoc render with a console
warning naming the field, rather than blanking the app.

Also fixes a pre-existing `tsc -b` break on v2/main (useServers.test.tsx
passed `metadata: []` where `RequestMetadata` is expected), which has had
CI red since #2087 and blocks the pre-push gate.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 AGENTS.md                                     |  28 ++
 README.md                                     |   9 +-
 clients/web/README.md                         |  54 ++-
 clients/web/server/app-origin-controller.ts   | 326 +++++++++++++++
 clients/web/server/sandbox-controller.ts      |  16 +-
 clients/web/server/server.ts                  |  15 +
 clients/web/server/vite-hono-plugin.ts        |  15 +
 clients/web/server/web-server-config.ts       |  10 +
 clients/web/src/App.tsx                       |  20 +-
 .../createAppBridgeFactory.test.ts            | 135 +++++++
 .../AppRenderer/createAppBridgeFactory.ts     |  69 +++-
 .../web/src/lib/publishAppDocument.test.ts    | 119 ++++++
 clients/web/src/lib/publishAppDocument.ts     |  67 ++++
 .../mcp/remote/app-document-route.test.ts     | 134 +++++++
 .../server/app-origin-controller.test.ts      | 375 ++++++++++++++++++
 .../server/server-auto-open.test.ts           |   1 +
 .../server/server-token-injection.test.ts     |   1 +
 .../server/web-server-config.test.ts          |  13 +
 clients/web/static/sandbox_proxy.html         | 100 ++++-
 core/mcp/remote/node/server.ts                |  65 +++
 20 files changed, 1554 insertions(+), 18 deletions(-)
 create mode 100644 clients/web/server/app-origin-controller.ts
 create mode 100644 clients/web/src/lib/publishAppDocument.test.ts
 create mode 100644 clients/web/src/lib/publishAppDocument.ts
 create mode 100644 clients/web/src/test/integration/mcp/remote/app-document-route.test.ts
 create mode 100644 clients/web/src/test/integration/server/app-origin-controller.test.ts

diff --git a/AGENTS.md b/AGENTS.md
index e7acd609..0281b69a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,6 +15,34 @@ v2/main/
 │   │   │                               #   start-vite-dev-server.ts (in-process Vite starter for the launcher),
 │   │   │                               #   web-server-config.ts (env parsing + initial-config payload + banner),
 │   │   │                               #   sandbox-controller.ts (MCP Apps sandbox HTTP server),
+│   │                               #   app-origin-controller.ts (the DEDICATED APP ORIGIN for
+│   │                               #     `_meta.ui.domain` — #2056. The default render hands an
+│   │                               #     app's HTML to the proxy as `srcdoc` in a frame with no
+│   │                               #     `allow-same-origin`, so the document has an OPAQUE origin
+│   │                               #     and every request it makes sends `Origin: null`; no CORS /
+│   │                               #     OAuth-callback / API-key allowlist can admit that, which is
+│   │                               #     what the spec field exists to fix. `domain` is explicitly
+│   │                               #     HOST-DEPENDENT and the Inspector owns no domain
+│   │                               #     infrastructure, so it treats any non-empty value as a
+│   │                               #     REQUEST, not an address, and answers with a real loopback
+│   │                               #     origin on its own port (MCP_APP_ORIGIN_PORT, default 6276).
+│   │                               #     ONE SHARED origin, path-keyed per document — a real,
+│   │                               #     allowlistable origin without a port or DNS name per app,
+│   │                               #     and therefore NOT a per-app isolation boundary (two such
+│   │                               #     apps share its localStorage/cookies). The inner frame is
+│   │                               #     granted `allow-same-origin` on THIS path only, which is
+│   │                               #     what makes the origin real; that is not a #1565 regression
+│   │                               #     because the listener is on its own port, so the app stays
+│   │                               #     cross-origin to both the proxy and the Inspector — the
+│   │                               #     proxy refuses the grant if the URL's origin equals its own,
+│   │                               #     and it is never reachable from the server-supplied
+│   │                               #     `sandbox` string, which is still stripped. The browser
+│   │                               #     hands the wrapped bytes back through the authenticated
+│   │                               #     `POST /api/app-document` (core/mcp/remote/node/server.ts)
+│   │                               #     because only it holds the MCP connection. EVERY failure —
+│   │                               #     no listener, port never bound, older backend, network
+│   │                               #     error — falls back to the srcdoc render with a warning
+│   │                               #     rather than blanking the app),
 │   │   │                               #   inject-auth-token.ts (embeds the API token into served index.html),
 │   │   │                               #   vite-base-config.ts (shared optimizeDeps exclusions),
 │   │   │                               #   resolve-bind-host.ts (bind-host POLICY: defaults to
diff --git a/README.md b/README.md
index 51a0a4f7..7594ddfa 100644
--- a/README.md
+++ b/README.md
@@ -466,7 +466,14 @@ docker run --rm -p 127.0.0.1:6274:6274 -p 127.0.0.1:6275:6275 \
   ghcr.io/modelcontextprotocol/inspector
 ```
 
-Publish it on the **same port number** inside and out. The sandbox URL is handed to the browser via `/api/config` as `http://localhost:<container port>/sandbox`, so remapping it (`-p 9000:6275`) advertises a port the browser can't reach; use `-e MCP_SANDBOX_PORT=9000 -p 127.0.0.1:9000:9000` instead.
+**And `6276` if your app declares `_meta.ui.domain`.** That is the spec field a server uses to ask its host for a stable, dedicated origin — without one the app runs at an opaque origin and its requests carry `Origin: null`, which no CORS / OAuth-callback / API-key allowlist can admit. The Inspector answers the request with a real loopback origin on a third listener, `MCP_APP_ORIGIN_PORT` (default `6276`); apps that declare no `domain` never touch it. An app that declares one and can't reach it still renders — at an opaque origin, with a console warning. See [MCP App dedicated origins](./clients/web/README.md#mcp-app-dedicated-origins-metauidomain) for the host-specific contract and its isolation trade-offs.
+
+```bash
+docker run --rm -p 127.0.0.1:6274:6274 -p 127.0.0.1:6275:6275 -p 127.0.0.1:6276:6276 \
+  ghcr.io/modelcontextprotocol/inspector
+```
+
+Publish each on the **same port number** inside and out. The sandbox URL is handed to the browser via `/api/config` as `http://localhost:<container port>/sandbox`, so remapping it (`-p 9000:6275`) advertises a port the browser can't reach; use `-e MCP_SANDBOX_PORT=9000 -p 127.0.0.1:9000:9000` instead. The same holds for the app origin: the URL a published app document is served from is built from the port the container bound, so remap with `-e MCP_APP_ORIGIN_PORT=9001 -p 127.0.0.1:9001:9001` rather than with `-p` alone.
 
 **Keep the `127.0.0.1:` prefix on the published port.** A bare `-p 6274:6274` publishes on **every host interface**, putting the Inspector on your local network. The container's `HOST=0.0.0.0` is a separate concern — it governs the _container's_ interfaces, not the host's — so the `DANGEROUSLY_BIND_ALL_INTERFACES` opt-in that guards a wildcard bind outside a container does not cover this. It matters more here than for an ordinary web app: the backend spawns processes on request, `GET /` embeds the API token into the served HTML, and a request arriving with **no** `Origin` header skips the origin allow-list entirely — so for any non-browser client the API token is the only guard. Publishing wider needs a real access-control boundary in front of the Inspector — a reverse proxy that authenticates, an SSH tunnel, a private network. Setting your own `MCP_INSPECTOR_API_TOKEN` does **not** substitute: `GET /` discloses whatever token is in use, so a custom one is harvested exactly as easily as a generated one.
 
diff --git a/clients/web/README.md b/clients/web/README.md
index fe32c090..f6963294 100644
--- a/clients/web/README.md
+++ b/clients/web/README.md
@@ -19,7 +19,7 @@ The `server/` directory holds the Node-only backend:
 - **`web-server-config.ts`** — env parsing, the `GET /api/config` payload, the startup banner, the default origin allow-list.
 - **`resolve-bind-host.ts`** — the shared bind-host guard (refuses an all-interfaces `HOST` unless `DANGEROUSLY_BIND_ALL_INTERFACES`), used by both bind points (`web-server-config.ts` + `vite.config.ts`); see [Host binding & the origin allow-list](#host-binding--the-origin-allow-list).
 - **`inject-auth-token.ts`** — embeds the API token into the served `index.html` (see [Auth token](#auth-token)).
-- **`sandbox-controller.ts`** — the MCP Apps sandbox HTTP server; **`ensure-web-build.ts`** — builds `dist/` on demand for prod `--web`; **`vite-base-config.ts`** — shared `optimizeDeps` exclusions.
+- **`sandbox-controller.ts`** — the MCP Apps sandbox HTTP server; **`app-origin-controller.ts`** — the dedicated app-origin server for `_meta.ui.domain` (see [MCP App dedicated origins](#mcp-app-dedicated-origins-metauidomain)); **`ensure-web-build.ts`** — builds `dist/` on demand for prod `--web`; **`vite-base-config.ts`** — shared `optimizeDeps` exclusions.
 - **`browser-externalized-builtin-gate.ts`** — Vite-agnostic build-gate logic that fails `vite build` when a Node built-in reaches the browser bundle (#1769); the thin Vite plugin wiring lives in `vite.config.ts`. It sits under `server/` (rather than `src/`) as the home for Node-only, build-time tooling — it's imported by the Vite config, never by the browser — alongside the other `vite-*` config helpers here.
 
 ## Development
@@ -135,6 +135,58 @@ Three further params extend the deep link to pre-select — and optionally auto-
 
 The app-side render lifecycle is observable through the [MCP Apps screen automation contract](#mcp-apps-screen-automation-contract) above (`data-app-status="ready"`), so a driver can `waitForSelector` the whole `connect → open → ready` chain deterministically.
 
+## MCP App dedicated origins (`_meta.ui.domain`)
+
+By default an MCP App is rendered by handing its HTML to the sandbox proxy as
+`srcdoc`, inside an iframe sandboxed **without** `allow-same-origin`. That is
+the isolation model from #1565 and it stays the default — but it gives the app
+document an *opaque* origin, so every request it makes carries `Origin: null`.
+An app whose backend allowlists origins (CORS, an OAuth callback, an API-key
+allowlist) can't work that way, which is what the spec's `_meta.ui.domain`
+exists to solve: a server uses it to ask its host for a stable, dedicated
+origin.
+
+**The Inspector's host-specific contract.** The spec makes `domain`'s format
+host-dependent ("servers MUST consult host-specific documentation"), and the
+Inspector owns no domain infrastructure — it cannot serve
+`my-app.example.com`. So it treats the field as a **request, not an address**:
+
+- Any **non-empty** `domain` string opts the resource in. The value itself is
+  not parsed, matched, or reserved — declare whatever your production host
+  expects.
+- The Inspector answers with a real HTTP origin on loopback:
+  `http://<host>:<MCP_APP_ORIGIN_PORT>`, default **`6276`** (beside the web
+  port `6274` and the sandbox port `6275`, so the three forward together).
+- The app document is served from there under an unguessable path, its
+  per-app CSP delivered as a real response **header** (stronger than the
+  `<meta>` the `srcdoc` path relies on) plus a `frame-ancestors` that admits
+  only the sandbox proxy.
+- The inner iframe is granted `allow-same-origin` on this path **only** —
+  that is what makes the origin real rather than opaque. It is not a
+  weakening of #1565: the listener is on its own port, so the app is
+  cross-origin to both the sandbox proxy and the Inspector, and same-origin
+  policy blocks the reach either way. The proxy refuses the grant outright if
+  the URL's origin equals its own, and the grant is never reachable from the
+  server-supplied `sandbox` string, which is still stripped.
+
+**It is one shared origin, not one per app.** Every domain-declaring app is
+served from the same port, keyed by path. That delivers the property the field
+is *for* — a real, allowlistable origin — without minting a port or a DNS name
+per app, at the cost of not being a per-app isolation boundary: two such apps
+share `localStorage`, `sessionStorage`, and cookies for that origin.
+
+**Every failure falls back rather than blanking the app.** No app-origin
+listener, a port that never bound, an older backend with no
+`POST /api/app-document` route, a network error — each renders the app the
+default (opaque-origin) way and logs a console warning naming `_meta.ui.domain`.
+Losing the real origin degrades what the app can reach; losing the app itself
+would be worse.
+
+**Forward `6276` too** if you need this off loopback (a container, a tunnel).
+As with the sandbox port, a taken port falls back to an OS-assigned one with a
+loud warning — the app still renders, but the origin an app's backend was told
+to allowlist is then wrong, which is what the warning tells you.
+
 ## Theme (`src/theme/`)
 
 Each customized Mantine component has a `Theme<Name>.ts` file (`Button.ts`, `Text.ts`, …, ~21 total) exporting a `Theme<Name>` constant; the barrel `index.ts` re-exports them and `theme.ts` assembles the `MantineProvider` theme. Theme files hold app-wide defaults and **variants** (flat CSS-in-JS); only pseudo-selectors, nested child selectors, keyframes, and native-HTML styling belong in `App.css`. Element components import from `@mantine/core` (never from `theme/`) — the theme layer is applied transparently by the provider.
diff --git a/clients/web/server/app-origin-controller.ts b/clients/web/server/app-origin-controller.ts
new file mode 100644
index 00000000..6f274e31
--- /dev/null
+++ b/clients/web/server/app-origin-controller.ts
@@ -0,0 +1,326 @@
+/**
+ * App-origin server: the dedicated origin an MCP App gets when its UI resource
+ * declares `_meta.ui.domain` (#2056).
+ *
+ * ## Why a third listener exists
+ *
+ * By default the Inspector renders an App by handing its HTML to the sandbox
+ * proxy as `srcdoc`, in an iframe sandboxed **without** `allow-same-origin`.
+ * That is the isolation model #1565 chose, and it is the right default — but it
+ * gives the app document an *opaque* origin, so every request it makes carries
+ * `Origin: null`. An app whose backend allowlists origins (CORS, an OAuth
+ * callback, an API-key allowlist) therefore cannot work, which is exactly what
+ * `_meta.ui.domain` exists to solve: the spec lets a server ask its host for a
+ * stable, dedicated origin.
+ *
+ * `domain` is explicitly **host-dependent** — "the format and validation rules
+ * for this field are determined by each host" — and the Inspector owns no
+ * domain infrastructure. What it *can* provide is a real, stable HTTP origin on
+ * loopback. So a UI resource that declares any non-empty `domain` opts into
+ * being served from this listener instead of `srcdoc`, and its requests carry a
+ * real `Origin: http://<host>:<port>`.
+ *
+ * ## One shared origin, not one per domain
+ *
+ * Every domain-declaring app is served from this single port, path-keyed by an
+ * unguessable document id. That is a deliberate trade: it delivers the property
+ * the spec field is *for* (a real, allowlistable origin) without minting a port
+ * — or a DNS name — per app. The consequence is that this origin is **not** a
+ * per-app isolation boundary: two apps served here share `localStorage`,
+ * `sessionStorage`, and cookies for it. They remain isolated from the sandbox
+ * proxy and from the Inspector itself, which are different origins.
+ *
+ * ## Why granting `allow-same-origin` here is not a regression
+ *
+ * The inner frame is sandboxed with `allow-same-origin` only on this path,
+ * which is what makes the origin real rather than opaque. The #1565 rationale —
+ * "the app cannot touch the proxy's DOM, so it cannot bypass its own CSP by
+ * executing in the parent's realm" — still holds, because this listener is on
+ * its own port and is therefore cross-origin to both the proxy and the app
+ * page. Same-origin policy blocks the reach either way.
+ *
+ * The per-app CSP is additionally delivered as a real response **header** here,
+ * which is stronger than the `<meta>` the `srcdoc` path must rely on: a header
+ * applies to the document before any of its bytes are parsed and cannot be
+ * displaced by anything in the app's own markup.
+ */
+
+import { createServer, type Server } from "node:http";
+import { randomBytes } from "node:crypto";
+import {
+  canonicalUrlHost,
+  isAllInterfacesHost,
+} from "../../../core/node/hostUrl.ts";
+import { DEFAULT_BIND_HOST } from "./resolve-bind-host.js";
+import { frameAncestorsDirective } from "./sandbox-controller.js";
+
+/**
+ * The default app-origin listen port — **fixed**, for the same reason
+ * `DEFAULT_SANDBOX_PORT` is: a port that changes per run can never be named in
+ * a dev container's `forwardPorts`, a `docker run -p`, or an SSH tunnel. `6276`
+ * sits next to the web (`6274`) and sandbox (`6275`) ports so the three forward
+ * together.
+ */
+export const DEFAULT_APP_ORIGIN_PORT = 6276;
+
+/** Documents kept at once. Oldest is evicted past this; see {@link publish}. */
+const MAX_DOCUMENTS = 32;
+
+/**
+ * How long a published document stays fetchable. An iframe fetches its `src`
+ * once, so this only has to outlive the gap between publishing and the frame
+ * loading — but a generous window keeps a reload (React StrictMode, a devtools
+ * "reload frame") working rather than blanking the app.
+ */
+const DOCUMENT_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * The sandbox proxy's origin as a one-entry list for
+ * {@link AppOriginControllerOptions.embedderOrigins}, or `undefined` when the
+ * sandbox never bound (its controller degrades to a null URL). Passing
+ * `undefined` is what makes the app-origin `frame-ancestors` fall back to
+ * loopback rather than to `'none'`, which would block the frame outright.
+ */
+export function sandboxOriginList(
+  sandboxUrl: string | null | undefined,
+): string[] | undefined {
+  if (!sandboxUrl) return undefined;
+  try {
+    return [new URL(sandboxUrl).origin];
+  } catch {
+    /* v8 ignore next -- the sandbox controller only ever emits a URL it built
+       itself; an unparseable value would be a bug there, not input. */
+    return undefined;
+  }
+}
+
+export interface AppOriginControllerOptions {
+  /** Port to bind (0 = dynamic). */
+  port: number;
+  /** Host to bind (default {@link DEFAULT_BIND_HOST}). */
+  host?: string;
+  /**
+   * The origin(s) allowed to frame a published document — in practice the
+   * sandbox proxy's own origin, since the proxy is what embeds the inner
+   * iframe. Malformed entries are dropped and an empty result falls back to
+   * loopback, exactly as the sandbox proxy's own `frame-ancestors` does.
+   */
+  embedderOrigins?: string[];
+}
+
+/** A document handed to {@link AppOriginController.publish}. */
+export interface AppDocument {
+  /** The fully-wrapped HTML the sandbox would otherwise have received. */
+  html: string;
+  /** The per-app CSP policy string, delivered as a response header. */
+  csp?: string;
+}
+
+export interface AppOriginController {
+  start(): Promise<{ port: number; url: string }>;
+  close(): Promise<void>;
+  /** The origin this listener serves on, or null when it never bound. */
+  getOrigin(): string | null;
+  /**
+   * Store a document and return the absolute URL the sandbox proxy should load
+   * it from, or `null` when this listener isn't running (the caller then falls
+   * back to the default `srcdoc` path rather than failing the render).
+   */
+  publish(doc: AppDocument): { url: string } | null;
+}
+
+/**
+ * A usable listen port from a raw env value, or `undefined` if it isn't a plain
+ * integer in `0`–`65535`. Mirrors `sandbox-controller`'s parser: `^\d+$` rejects
+ * `parseInt`'s partial parses (`6276abc`) and the bound keeps an out-of-range
+ * value from reaching `server.listen`, which throws synchronously.
+ */
+function parseListenPort(raw: string | undefined): number | undefined {
+  const v = raw?.trim();
+  if (!v || !/^\d+$/.test(v)) return undefined;
+  const n = parseInt(v, 10);
+  return n <= 65535 ? n : undefined;
+}
+
+/**
+ * Resolve the app-origin port from env: `MCP_APP_ORIGIN_PORT` →
+ * {@link DEFAULT_APP_ORIGIN_PORT}. A set-but-invalid value is warned and falls
+ * through rather than crashing the boot, matching `resolveSandboxPort`.
+ */
+export function resolveAppOriginPort(): number {
+  const parsed = parseListenPort(process.env.MCP_APP_ORIGIN_PORT);
+  if (parsed === undefined && process.env.MCP_APP_ORIGIN_PORT?.trim()) {
+    console.warn(
+      `Ignoring invalid MCP_APP_ORIGIN_PORT="${process.env.MCP_APP_ORIGIN_PORT}" (need an integer 0–65535); falling back.`,
+    );
+  }
+  return parsed ?? DEFAULT_APP_ORIGIN_PORT;
+}
+
+/** The path a published document is served at, given its id. */
+const DOC_PATH_PREFIX = "/app-document/";
+
+/** `/app-document/<id>` → `<id>`, or null for any other request target. */
+export function parseDocumentId(url: string | undefined): string | null {
+  if (!url || !url.startsWith(DOC_PATH_PREFIX)) return null;
+  // Drop a query string: an app's own URL may carry one and it is not part of
+  // the id. Anything with a further path segment is not a document target.
+  const id = url.slice(DOC_PATH_PREFIX.length).split(/[?#]/)[0];
+  return /^[0-9a-f]{32}$/.test(id ?? "") ? (id ?? null) : null;
+}
+
+interface StoredDocument extends AppDocument {
+  expiresAt: number;
+}
+
+export function createAppOriginController(
+  options: AppOriginControllerOptions,
+): AppOriginController {
+  // Same defaulting rationale as the sandbox controller: never the *name*
+  // `localhost`, which resolves to a single address family and would put this
+  // listener on a different family than the web server (#1951).
+  const { port, host = DEFAULT_BIND_HOST, embedderOrigins } = options;
+  let server: Server | null = null;
+  let origin: string | null = null;
+
+  // Insertion-ordered, so the first key is the oldest entry.
+  const documents = new Map<string, StoredDocument>();
+
+  const FRAME_ANCESTORS = frameAncestorsDirective(embedderOrigins);
+
+  /** Drop everything past its TTL. Cheap: the map is bounded by MAX_DOCUMENTS. */
+  function evictExpired(now: number): void {
+    for (const [id, doc] of documents) {
+      if (doc.expiresAt <= now) documents.delete(id);
+    }
+  }
+
+  return {
+    async start(): Promise<{ port: number; url: string }> {
+      if (server && origin) {
+        return { port: parseInt(new URL(origin).port, 10), url: origin };
+      }
+      return new Promise((resolve) => {
+        let settled = false;
+        const settle = (value: { port: number; url: string }) => {
+          /* v8 ignore next -- defensive double-settle guard: `error` and
+             `listening` are mutually exclusive for a TCP listen. */
+          if (settled) return;
+          settled = true;
+          resolve(value);
+        };
+
+        server = createServer((req, res) => {
+          const id = req.method === "GET" ? parseDocumentId(req.url) : null;
+          const doc = id ? documents.get(id) : undefined;
+          if (!doc || doc.expiresAt <= Date.now()) {
+            if (id) documents.delete(id);
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("Not Found");
+            return;
+          }
+          res.writeHead(200, {
+            "Content-Type": "text/html; charset=utf-8",
+            "Cache-Control": "no-store, no-cache, must-revalidate",
+            Pragma: "no-cache",
+            // `nosniff` matters more here than on a page we authored: these
+            // bytes are server-supplied and untrusted.
+            "X-Content-Type-Options": "nosniff",
+            // The per-app policy as a real header. It is the same policy baked
+            // into the document's <meta>; delivering both is deliberate —
+            // multiple policies intersect, and two copies of one policy
+            // intersect to itself, so this can only ever be at least as strict.
+            "Content-Security-Policy": doc.csp
+              ? `${doc.csp}; ${FRAME_ANCESTORS}`
+              : FRAME_ANCESTORS,
+          });
+          res.end(doc.html);
+        });
+
+        // Same fallback as the sandbox controller: a fixed default port can
+        // collide (a second Inspector), and losing the listener would take
+        // dedicated-origin rendering down. Retry once on an OS-assigned port,
+        // loudly — whoever pinned the port to forward it needs to know.
+        let retriedDynamic = false;
+        server.on("error", (err: NodeJS.ErrnoException) => {
+          if (err.code === "EADDRINUSE") {
+            if (!retriedDynamic && port !== 0) {
+              retriedDynamic = true;
+              console.warn(
+                `App origin: port ${port} in use; falling back to an OS-assigned port. ` +
+                  `Apps declaring _meta.ui.domain will still render, but the origin ` +
+                  `they are served from is no longer predictable — set ` +
+                  `MCP_APP_ORIGIN_PORT to a free one if your app's backend ` +
+                  `allowlists it.`,
+              );
+              server!.listen(0, host);
+              return;
+            }
+            console.error(
+              `App origin: port ${port || "dynamic"} in use. Apps declaring _meta.ui.domain will fall back to an opaque origin.`,
+            );
+          } else {
+            console.error("App origin server error:", err);
+          }
+          // Degrade rather than reject: `publish` then returns null and the
+          // renderer keeps working on the default srcdoc path.
+          server = null;
+          settle({ port: 0, url: "" });
+        });
+
+        server.listen(port, host, () => {
+          const addr = server!.address();
+          const actualPort =
+            typeof addr === "object" && addr !== null && "port" in addr
+              ? addr.port
+              : /* v8 ignore next -- unreachable for a TCP listen; `address()`
+                   returns AddressInfo. */
+                (addr as unknown as number);
+          // A wildcard bind isn't reachable as `http://0.0.0.0:PORT`, but it
+          // does serve loopback — advertise `localhost` there, and otherwise
+          // the same canonical host the origin allow-list emits.
+          const canonicalHost = canonicalUrlHost(host);
+          const urlHost = isAllInterfacesHost(canonicalHost)
+            ? "localhost"
+            : canonicalHost;
+          origin = `http://${urlHost}:${actualPort}`;
+          settle({ port: actualPort, url: origin });
+        });
+      });
+    },
+
+    async close(): Promise<void> {
+      documents.clear();
+      if (!server) return;
+      return new Promise((resolve) => {
+        server!.close(() => {
+          server = null;
+          origin = null;
+          resolve();
+        });
+      });
+    },
+
+    getOrigin(): string | null {
+      return origin;
+    },
+
+    publish(doc: AppDocument): { url: string } | null {
+      if (!origin) return null;
+      const now = Date.now();
+      evictExpired(now);
+      // Bound the map even if nothing has expired: drop the oldest entry. An
+      // evicted document's frame has long since loaded, and the alternative is
+      // an unbounded store fed by every app the user opens in a session.
+      while (documents.size >= MAX_DOCUMENTS) {
+        const oldest = documents.keys().next();
+        /* v8 ignore next -- `size >= MAX_DOCUMENTS` guarantees a first key. */
+        if (oldest.done) break;
+        documents.delete(oldest.value);
+      }
+      const id = randomBytes(16).toString("hex");
+      documents.set(id, { ...doc, expiresAt: now + DOCUMENT_TTL_MS });
+      return { url: `${origin}${DOC_PATH_PREFIX}${id}` };
+    },
+  };
+}
diff --git a/clients/web/server/sandbox-controller.ts b/clients/web/server/sandbox-controller.ts
index 50d4c440..148ceb62 100644
--- a/clients/web/server/sandbox-controller.ts
+++ b/clients/web/server/sandbox-controller.ts
@@ -70,7 +70,21 @@ const CSP_HOST_SOURCE = /^[a-z][a-z0-9+.-]*:\/\/[^\s;,'"[\]*]+$/i;
  * header can't be corrupted.
  */
 export function sandboxFrameAncestors(allowedOrigins?: string[]): string {
-  const valid = (allowedOrigins ?? []).filter((o) => CSP_HOST_SOURCE.test(o));
+  return frameAncestorsDirective(allowedOrigins);
+}
+
+/**
+ * Build a `frame-ancestors` directive from a caller-supplied origin list,
+ * dropping malformed entries ({@link CSP_HOST_SOURCE}) and falling back to
+ * {@link LOOPBACK_FRAME_ANCESTORS} when nothing valid remains.
+ *
+ * Shared with the app-origin server (#2056), which restricts a published app
+ * document to being framed by the sandbox proxy. Same grammar, same failure
+ * mode — a directive whose only source is invalid degrades to `'none'` and
+ * blocks the frame — so the two derive it here rather than each rolling one.
+ */
+export function frameAncestorsDirective(origins?: string[]): string {
+  const valid = (origins ?? []).filter((o) => CSP_HOST_SOURCE.test(o));
   const sources = valid.length > 0 ? valid : LOOPBACK_FRAME_ANCESTORS;
   return `frame-ancestors ${sources.join(" ")}`;
 }
diff --git a/clients/web/server/server.ts b/clients/web/server/server.ts
index 2a10e59b..3a43e5b3 100644
--- a/clients/web/server/server.ts
+++ b/clients/web/server/server.ts
@@ -16,6 +16,10 @@ import type { Context } from "hono";
 import { createRemoteApp } from "../../../core/mcp/remote/node/server.ts";
 import { formatHostForUrl } from "../../../core/node/hostUrl.ts";
 import { createSandboxController } from "./sandbox-controller.js";
+import {
+  createAppOriginController,
+  sandboxOriginList,
+} from "./app-origin-controller.js";
 import { injectAuthToken } from "./inject-auth-token.js";
 import type { WebServerConfig } from "./web-server-config.js";
 import { getSecretStorageInfo } from "../../../core/auth/node/secret-store-selection.ts";
@@ -44,6 +48,15 @@ export async function startHonoServer(
     allowedOrigins: config.allowedOrigins,
   });
   await sandboxController.start();
+  // The dedicated origin apps declaring `_meta.ui.domain` are served from
+  // (#2056). Started after the sandbox because its `frame-ancestors` names the
+  // sandbox proxy's origin — the proxy is what embeds the app frame.
+  const appOriginController = createAppOriginController({
+    port: config.appOriginPort,
+    host: config.sandboxHost,
+    embedderOrigins: sandboxOriginList(sandboxController.getUrl()),
+  });
+  await appOriginController.start();
 
   const resolvedAuthToken =
     config.authToken ||
@@ -65,6 +78,7 @@ export async function startHonoServer(
     initialServers: config.initialServers ?? undefined,
     allowedOrigins: config.allowedOrigins,
     sandboxUrl: sandboxController.getUrl() ?? undefined,
+    publishAppDocument: (doc) => appOriginController.publish(doc),
     logger: config.logger,
     initialConfig: webServerConfigToInitialPayload(config, secretStorage),
     // The startup value above is what the banner printed; the route
@@ -159,6 +173,7 @@ export async function startHonoServer(
     async close(): Promise<void> {
       await closeApi();
       await sandboxController.close();
+      await appOriginController.close();
       if ("closeAllConnections" in httpServer) {
         httpServer.closeAllConnections();
       }
diff --git a/clients/web/server/vite-hono-plugin.ts b/clients/web/server/vite-hono-plugin.ts
index ab4a9fe4..c38f3fca 100644
--- a/clients/web/server/vite-hono-plugin.ts
+++ b/clients/web/server/vite-hono-plugin.ts
@@ -16,6 +16,10 @@ import type { Plugin } from "vite";
 // spurious "could not resolve" warnings during build.
 import { createRemoteApp } from "../../../core/mcp/remote/node/server.ts";
 import { createSandboxController } from "./sandbox-controller.js";
+import {
+  createAppOriginController,
+  sandboxOriginList,
+} from "./app-origin-controller.js";
 import { injectAuthToken } from "./inject-auth-token.js";
 import type { WebServerConfig } from "./web-server-config.js";
 import { getSecretStorageInfo } from "../../../core/auth/node/secret-store-selection.ts";
@@ -67,6 +71,15 @@ export function honoMiddlewarePlugin(config: WebServerConfig): Plugin {
         allowedOrigins: config.allowedOrigins,
       });
       await sandboxController.start();
+      // The dedicated origin apps declaring `_meta.ui.domain` are served from
+      // (#2056). Started after the sandbox because its `frame-ancestors` names
+      // the sandbox proxy's origin — the proxy is what embeds the app frame.
+      const appOriginController = createAppOriginController({
+        port: config.appOriginPort,
+        host: config.sandboxHost,
+        embedderOrigins: sandboxOriginList(sandboxController.getUrl()),
+      });
+      await appOriginController.start();
       // Resolved before the API is built so `/api/config` and the banner
       // report the same store (the selection itself is cached process-wide).
       const secretStorage = await getSecretStorageInfo();
@@ -84,6 +97,7 @@ export function honoMiddlewarePlugin(config: WebServerConfig): Plugin {
         initialServers: config.initialServers ?? undefined,
         allowedOrigins: config.allowedOrigins,
         sandboxUrl: sandboxController.getUrl() ?? undefined,
+        publishAppDocument: (doc) => appOriginController.publish(doc),
         logger: config.logger,
         initialConfig: webServerConfigToInitialPayload(config, secretStorage),
         // The startup value above is what the banner printed; the route
@@ -103,6 +117,7 @@ export function honoMiddlewarePlugin(config: WebServerConfig): Plugin {
       server.close = async () => {
         await closeApi();
         await sandboxController.close();
+        await appOriginController.close();
         return originalClose();
       };
 
diff --git a/clients/web/server/web-server-config.ts b/clients/web/server/web-server-config.ts
index a4359728..cd179df7 100644
--- a/clients/web/server/web-server-config.ts
+++ b/clients/web/server/web-server-config.ts
@@ -19,6 +19,7 @@ import type { SecretStorageInfo } from "../../../core/auth/secret-storage-info.t
 import { secretStorageSummary } from "../../../core/auth/secret-storage-info.ts";
 import { readInspectorVersionSafe } from "../../../core/node/version.ts";
 import { resolveSandboxPort } from "./sandbox-controller.js";
+import { resolveAppOriginPort } from "./app-origin-controller.js";
 import { resolveBindHostname } from "./resolve-bind-host.js";
 import {
   canonicalUrlHost,
@@ -66,6 +67,13 @@ export interface WebServerConfig {
   /** Sandbox port (0 = dynamic). */
   sandboxPort: number;
   sandboxHost: string;
+  /**
+   * Port for the dedicated app origin (#2056) — the listener that serves an
+   * MCP App declaring `_meta.ui.domain` so its requests carry a real `Origin`
+   * instead of `null`. `0` = dynamic. Bound on {@link sandboxHost}, the same
+   * address the sandbox uses.
+   */
+  appOriginPort: number;
   logger: Logger | undefined;
   /** When true, open browser after server starts. */
   autoOpen: boolean;
@@ -369,6 +377,7 @@ export function buildWebServerConfig(
       "");
 
   const sandboxPort = resolveSandboxPort();
+  const appOriginPort = resolveAppOriginPort();
 
   let logger: Logger | undefined;
   if (process.env.MCP_LOG_FILE) {
@@ -439,6 +448,7 @@ export function buildWebServerConfig(
       : defaultAllowedOrigins(hostname, port),
     sandboxPort,
     sandboxHost: hostname,
+    appOriginPort,
     logger,
     autoOpen: resolveAutoOpen(),
   };
diff --git a/clients/web/src/App.tsx b/clients/web/src/App.tsx
index 7918919c..d566e65a 100644
--- a/clients/web/src/App.tsx
+++ b/clients/web/src/App.tsx
@@ -148,6 +148,7 @@ import {
 import { clearScrollMemory } from "./hooks/useScrollMemory";
 import type { AppRendererHandle } from "./components/elements/AppRenderer/AppRenderer";
 import { createAppBridgeFactory } from "./components/elements/AppRenderer/createAppBridgeFactory";
+import { publishAppDocument } from "./lib/publishAppDocument";
 import { AppElicitationHost } from "./components/elements/AppElicitation/AppElicitationHost";
 import {
   AppElicitationController,
@@ -808,9 +809,23 @@ function App() {
     [],
   );
 
+  // `_meta.ui.domain` support (#2056): hand a wrapped app document to the
+  // backend so it can serve it from a dedicated origin, giving the app's
+  // requests a real `Origin`. Resolves `null` on any backend that can't, and
+  // the factory then renders the app the default (opaque-origin) way.
+  const publishDocument = useCallback(
+    (doc: { html: string; csp?: string }) =>
+      publishAppDocument(doc, {
+        baseUrl: configBaseUrl,
+        authToken: getAuthToken(),
+      }),
+    [configBaseUrl],
+  );
+
   const sandboxBridgeFactory = useMemo(
     () =>
       createAppBridgeFactory({
+        publishAppDocument: publishDocument,
         getClient: () => inspectorClient?.getAppRendererClient() ?? null,
         getListedResourceMeta,
         readResource: async (uri) => {
@@ -832,7 +847,7 @@ function App() {
           });
         },
       }),
-    [inspectorClient, getListedResourceMeta],
+    [inspectorClient, getListedResourceMeta, publishDocument],
   );
 
   // App-rendered form elicitations (#1854). The controller is created once and
@@ -885,6 +900,7 @@ function App() {
     () =>
       createAppBridgeFactory({
         advertiseElicitation: true,
+        publishAppDocument: publishDocument,
         getClient: () => inspectorClient?.getAppRendererClient() ?? null,
         getListedResourceMeta,
         readResource: async (uri) => {
@@ -903,7 +919,7 @@ function App() {
           });
         },
       }),
-    [inspectorClient, getListedResourceMeta],
+    [inspectorClient, getListedResourceMeta, publishDocument],
   );
   /**
    * Close the previous client's session and open one for the client being
diff --git a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
index 1e97877d..742fabf1 100644
--- a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
+++ b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
@@ -483,6 +483,141 @@ describe("createAppBridgeFactory", () => {
     expect(call.html).toContain("connect-src &#39;none&#39;");
   });
 
+  describe("_meta.ui.domain — dedicated origin (#2056)", () => {
+    // An app rendered under the default opaque origin sends `Origin: null`, so
+    // no CORS / OAuth-callback / API-key allowlist can admit it. `domain` is
+    // how a server asks its host for a real one; the Inspector answers with a
+    // URL on its own app-origin listener and passes it as `src`.
+
+    it("publishes the wrapped document and passes its URL as `src`", async () => {
+      const readResource = vi.fn().mockResolvedValue(
+        uiResource("<h1>weather</h1>", {
+          domain: "my-app.example.com",
+          csp: { connectDomains: ["https://api.example.com"] },
+        }),
+      );
+      const publishAppDocument = vi
+        .fn<(doc: { html: string; csp?: string }) => Promise<string | null>>()
+        .mockResolvedValue("http://localhost:6276/app-document/abc");
+      const factory = createAppBridgeFactory({
+        getClient: () => fakeClient,
+        readResource,
+        publishAppDocument,
+      });
+      await factory(makeIframe(), { kind: "tool", tool });
+      bridgeInstances[0].emit("sandboxready");
+      await flush();
+
+      // What is published is the SAME wrapped document the srcdoc path would
+      // have rendered, plus the policy as a separate string so the backend can
+      // serve it as a real response header.
+      const published = publishAppDocument.mock.calls[0][0];
+      expect(published.html).toContain("<body><h1>weather</h1></body>");
+      expect(published.csp).toContain("connect-src https://api.example.com");
+
+      const call = bridgeInstances[0].sendSandboxResourceReady.mock
+        .calls[0][0] as { html: string; src?: string };
+      expect(call.src).toBe("http://localhost:6276/app-document/abc");
+      // `html` still rides along: a proxy that ignores `src` renders the app
+      // rather than a blank frame.
+      expect(call.html).toBe(published.html);
+    });
+
+    it.each([
+      ["an empty domain", ""],
+      ["a whitespace-only domain", "   "],
+      ["a non-string domain", 42],
+    ])("does not take the dedicated path for %s", async (_label, domain) => {
+      const publishAppDocument = vi
+        .fn<(doc: { html: string; csp?: string }) => Promise<string | null>>()
+        .mockResolvedValue("http://localhost:6276/app-document/abc");
+      const factory = createAppBridgeFactory({
+        getClient: () => fakeClient,
+        readResource: vi
+          .fn()
+          .mockResolvedValue(uiResource("<h1>x</h1>", { domain })),
+        publishAppDocument,
+      });
+      await factory(makeIframe(), { kind: "tool", tool });
+      bridgeInstances[0].emit("sandboxready");
+      await flush();
+      expect(publishAppDocument).not.toHaveBeenCalled();
+      expect(
+        bridgeInstances[0].sendSandboxResourceReady.mock.calls[0][0],
+      ).not.toHaveProperty("src");
+    });
+
+    it("never publishes a resource that declares no domain", async () => {
+      const publishAppDocument = vi
+        .fn<(doc: { html: string; csp?: string }) => Promise<string | null>>()
+        .mockResolvedValue("http://localhost:6276/app-document/abc");
+      const factory = createAppBridgeFactory({
+        getClient: () => fakeClient,
+        readResource: vi.fn().mockResolvedValue(uiResource("<h1>x</h1>")),
+        publishAppDocument,
+      });
+      await factory(makeIframe(), { kind: "tool", tool });
+      bridgeInstances[0].emit("sandboxready");
+      await flush();
+      expect(publishAppDocument).not.toHaveBeenCalled();
+    });
+
+    it("falls back to srcdoc, warning, when the backend cannot host the document", async () => {
+      // A backend with no app-origin listener. Losing the real origin degrades
+      // what the app can reach and the developer needs to see why — losing the
+      // app itself would be worse.
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        const factory = createAppBridgeFactory({
+          getClient: () => fakeClient,
+          readResource: vi
+            .fn()
+            .mockResolvedValue(
+              uiResource("<h1>x</h1>", { domain: "my-app.example.com" }),
+            ),
+          publishAppDocument: vi.fn().mockResolvedValue(null),
+        });
+        await factory(makeIframe(), { kind: "tool", tool });
+        bridgeInstances[0].emit("sandboxready");
+        await flush();
+        const call = bridgeInstances[0].sendSandboxResourceReady.mock
+          .calls[0][0] as { html: string; src?: string };
+        expect(call.src).toBeUndefined();
+        expect(call.html).toContain("<body><h1>x</h1></body>");
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining("_meta.ui.domain"),
+        );
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+
+    it("falls back to srcdoc when the factory was given no publisher at all", async () => {
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        const factory = createAppBridgeFactory({
+          getClient: () => fakeClient,
+          readResource: vi
+            .fn()
+            .mockResolvedValue(
+              uiResource("<h1>x</h1>", { domain: "my-app.example.com" }),
+            ),
+        });
+        await factory(makeIframe(), { kind: "tool", tool });
+        bridgeInstances[0].emit("sandboxready");
+        await flush();
+        expect(
+          bridgeInstances[0].sendSandboxResourceReady.mock.calls[0][0],
+        ).not.toHaveProperty("src");
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining("_meta.ui.domain"),
+        );
+      } finally {
+        warnSpy.mockRestore();
+      }
+    });
+  });
+
   it("does not mutate the shared HOST_CAPABILITIES when echoing the approved sandbox", async () => {
     // The factory builds a per-app copy ({ ...HOST_CAPABILITIES }) so the
     // sandbox echo never leaks across apps/renders. Lock that in: after a
diff --git a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
index e5d3215d..00a67983 100644
--- a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
+++ b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.ts
@@ -7,6 +7,7 @@ import type {
   McpUiDisplayMode,
   McpUiHostCapabilities,
   McpUiResourceMeta,
+  McpUiSandboxResourceReadyNotification,
 } from "@modelcontextprotocol/ext-apps/app-bridge";
 import type { Client } from "@modelcontextprotocol/client";
 import type {
@@ -108,6 +109,21 @@ export interface AppBridgeFactoryDeps {
    * there would tell the app something untrue about what its host will do.
    */
   advertiseElicitation?: boolean;
+  /**
+   * Publish a wrapped app document to the backend's dedicated app-origin
+   * listener and resolve with the URL to load it from, or `null` when the
+   * backend can't host one (#2056).
+   *
+   * Only consulted for a UI resource that declares `_meta.ui.domain` — the
+   * spec field by which a server asks its host for a stable, dedicated origin
+   * so its requests carry a real `Origin` instead of `null`. Optional: a
+   * factory without it (and a `null` result from one with it) renders every
+   * app the default way, under an opaque origin.
+   */
+  publishAppDocument?: (doc: {
+    html: string;
+    csp?: string;
+  }) => Promise<string | null>;
 }
 
 /**
@@ -174,6 +190,20 @@ function extractHtmlAndMeta(
   throw new Error("UI resource has no text (HTML) content");
 }
 
+/**
+ * Whether a UI resource asked for a dedicated origin (#2056).
+ *
+ * Any non-empty `domain` string counts. The spec is explicit that the field's
+ * format is host-dependent — hosts publish their own rules, and the examples it
+ * gives (`{hash}.claudemcpcontent.com`, `www-example-com.oaiusercontent.com`)
+ * are each one host's convention. The Inspector's convention is that the value
+ * is a *request*, not an address: it grants a real loopback origin and does not
+ * try to honor the specific name, which it could not serve anyway.
+ */
+function wantsDedicatedOrigin(meta: McpUiResourceMeta | undefined): boolean {
+  return typeof meta?.domain === "string" && meta.domain.trim() !== "";
+}
+
 /**
  * Decode a base64-encoded blob resource into bytes for download. Allocates the
  * backing store explicitly so the return type is `Uint8Array<ArrayBuffer>`
@@ -359,10 +389,43 @@ export function createAppBridgeFactory(
             permissions: approvedPermissions,
             csp: approvedCsp,
           };
-          await bridge.sendSandboxResourceReady({
-            html: wrapSandboxedHtml(html, buildSandboxCspPolicy(approvedCsp)),
+          const policy = buildSandboxCspPolicy(approvedCsp);
+          const wrapped = wrapSandboxedHtml(html, policy);
+          // `_meta.ui.domain` (#2056): the resource is asking to be served
+          // from a stable, dedicated origin rather than rendered into the
+          // default opaque-origin srcdoc frame, because an opaque origin sends
+          // `Origin: null` and no CORS / OAuth-callback / API-key allowlist can
+          // admit that. The spec makes the field's format host-dependent and
+          // the Inspector owns no domain infrastructure, so what it honors the
+          // request WITH is a real loopback origin — any non-empty domain opts
+          // in, and the string itself is not interpreted (see the app-origin
+          // controller for the host-specific contract).
+          //
+          // A `null` back means the backend has no such listener (an older
+          // backend, or one whose port never bound). Fall back to srcdoc: the
+          // app loses its real origin, which is a degradation the developer
+          // can see and act on — losing the app entirely is not.
+          const dedicated = wantsDedicatedOrigin(meta);
+          const src = dedicated
+            ? await deps.publishAppDocument?.({ html: wrapped, csp: policy })
+            : undefined;
+          if (dedicated && !src) {
+            console.warn(
+              "[mcp-app] resource declares _meta.ui.domain but no dedicated app origin is available; rendering under an opaque origin (requests will send `Origin: null`).",
+            );
+          }
+          // `src` is an Inspector-specific extension to the (internal)
+          // sandbox-resource-ready params, which ext-apps types but does not
+          // validate — the bridge forwards the params object verbatim. Declared
+          // as an intersection rather than cast so the extra key stays typed.
+          const readyParams: McpUiSandboxResourceReadyNotification["params"] & {
+            src?: string;
+          } = {
+            html: wrapped,
             permissions: approvedPermissions,
-          });
+            ...(src ? { src } : {}),
+          };
+          await bridge.sendSandboxResourceReady(readyParams);
         } catch (err) {
           const error = err instanceof Error ? err : new Error(String(err));
           console.error(
diff --git a/clients/web/src/lib/publishAppDocument.test.ts b/clients/web/src/lib/publishAppDocument.test.ts
new file mode 100644
index 00000000..289cdfdb
--- /dev/null
+++ b/clients/web/src/lib/publishAppDocument.test.ts
@@ -0,0 +1,119 @@
+/**
+ * `publishAppDocument` (#2056) — the browser half of dedicated-origin hosting.
+ *
+ * The contract worth pinning is the failure behavior: every way this can fail
+ * must resolve `null` rather than throw, because the caller's response to all
+ * of them is the same (render the app the default way), and a throw there
+ * would cost the user the app itself.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { publishAppDocument } from "./publishAppDocument";
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  } as unknown as Response;
+}
+
+describe("publishAppDocument", () => {
+  it("POSTs the document with the auth header and returns the URL", async () => {
+    const fetchFn = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(
+        jsonResponse({ url: "http://localhost:6276/app-document/abc" }),
+      );
+    const url = await publishAppDocument(
+      { html: "<p>app</p>", csp: "default-src 'none'" },
+      { baseUrl: "http://localhost:6274", authToken: "tok", fetchFn },
+    );
+    expect(url).toBe("http://localhost:6276/app-document/abc");
+    expect(fetchFn).toHaveBeenCalledWith(
+      "http://localhost:6274/api/app-document",
+      expect.objectContaining({
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-mcp-remote-auth": "Bearer tok",
+        },
+        body: JSON.stringify({ html: "<p>app</p>", csp: "default-src 'none'" }),
+      }),
+    );
+  });
+
+  it("omits the auth header when there is no token, and trims a trailing slash", async () => {
+    const fetchFn = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(jsonResponse({ url: "http://x/y" }));
+    await publishAppDocument(
+      { html: "<p>app</p>" },
+      { baseUrl: "http://localhost:6274/", fetchFn },
+    );
+    expect(fetchFn).toHaveBeenCalledWith(
+      "http://localhost:6274/api/app-document",
+      expect.objectContaining({
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+  });
+
+  it.each([
+    ["a 503 (no app-origin listener)", jsonResponse({}, 503)],
+    ["a 404 (backend predating the route)", jsonResponse({}, 404)],
+    ["a body with no url", jsonResponse({})],
+    ["a body whose url is not a string", jsonResponse({ url: 42 })],
+    ["a body whose url is empty", jsonResponse({ url: "" })],
+  ])("resolves null for %s", async (_label, response) => {
+    const fetchFn = vi.fn<typeof fetch>().mockResolvedValue(response);
+    await expect(
+      publishAppDocument(
+        { html: "<p>app</p>" },
+        { baseUrl: "http://b", fetchFn },
+      ),
+    ).resolves.toBeNull();
+  });
+
+  it("resolves null on a network error rather than rejecting", async () => {
+    const fetchFn = vi
+      .fn<typeof fetch>()
+      .mockRejectedValue(new Error("offline"));
+    await expect(
+      publishAppDocument(
+        { html: "<p>app</p>" },
+        { baseUrl: "http://b", fetchFn },
+      ),
+    ).resolves.toBeNull();
+  });
+
+  it("resolves null when the response body is not JSON", async () => {
+    const fetchFn = vi.fn<typeof fetch>().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => {
+        throw new Error("not json");
+      },
+    } as unknown as Response);
+    await expect(
+      publishAppDocument(
+        { html: "<p>app</p>" },
+        { baseUrl: "http://b", fetchFn },
+      ),
+    ).resolves.toBeNull();
+  });
+
+  it("defaults to globalThis.fetch when none is injected", async () => {
+    const spy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(jsonResponse({ url: "http://x/y" }));
+    try {
+      await expect(
+        publishAppDocument({ html: "<p>app</p>" }, { baseUrl: "http://b" }),
+      ).resolves.toBe("http://x/y");
+      expect(spy).toHaveBeenCalled();
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});
diff --git a/clients/web/src/lib/publishAppDocument.ts b/clients/web/src/lib/publishAppDocument.ts
new file mode 100644
index 00000000..4a313e62
--- /dev/null
+++ b/clients/web/src/lib/publishAppDocument.ts
@@ -0,0 +1,67 @@
+/**
+ * Publish a wrapped MCP App document to the backend's dedicated app-origin
+ * listener and get back the URL to load it from (#2056).
+ *
+ * This is `lib`, not `utils`: it does network I/O against the authenticated
+ * `/api/*` surface.
+ *
+ * ## Why the browser hands the bytes back
+ *
+ * The app's HTML arrives over the MCP connection, which only the browser
+ * holds — the backend has no client of its own to read the `ui://` resource
+ * with. So the one way an app can be served from a real HTTP origin is for the
+ * browser to POST the document it already wrapped. The backend stores it under
+ * an unguessable id and serves it from a separate listener on its own port,
+ * which is what makes the app's origin real instead of opaque.
+ *
+ * Only apps whose UI resource declares `_meta.ui.domain` take this path; every
+ * other app keeps the default `srcdoc` render under an opaque origin.
+ */
+
+/** Backend response shape for a successful publish. */
+interface PublishResponse {
+  url?: unknown;
+}
+
+export interface PublishAppDocumentOptions {
+  /** Base URL of the backend (typically `window.location.origin`). */
+  baseUrl: string;
+  /** Optional auth token for the `x-mcp-remote-auth` header. */
+  authToken?: string;
+  /** Fetch function to use (default: `globalThis.fetch`). Useful in tests. */
+  fetchFn?: typeof fetch;
+}
+
+/**
+ * POST the document and return the absolute URL it is served from, or `null`
+ * when the backend cannot host it.
+ *
+ * Never throws. Every failure — an old backend with no route, a backend with no
+ * app-origin listener (503), a network error, a malformed body — is a `null`,
+ * because the caller's response to all of them is the same: render the app the
+ * default way. Losing the dedicated origin degrades what the app can reach; it
+ * must not cost the user the app itself.
+ */
+export async function publishAppDocument(
+  doc: { html: string; csp?: string },
+  opts: PublishAppDocumentOptions,
+): Promise<string | null> {
+  const doFetch = opts.fetchFn ?? globalThis.fetch;
+  const base = opts.baseUrl.replace(/\/$/, "");
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (opts.authToken) headers["x-mcp-remote-auth"] = `Bearer ${opts.authToken}`;
+  try {
+    const res = await doFetch(`${base}/api/app-document`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(doc),
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as PublishResponse;
+    return typeof body.url === "string" && body.url ? body.url : null;
+  } catch {
+    return null;
+  }
+}
diff --git a/clients/web/src/test/integration/mcp/remote/app-document-route.test.ts b/clients/web/src/test/integration/mcp/remote/app-document-route.test.ts
new file mode 100644
index 00000000..d9939f38
--- /dev/null
+++ b/clients/web/src/test/integration/mcp/remote/app-document-route.test.ts
@@ -0,0 +1,134 @@
+/**
+ * `POST /api/app-document` (#2056) — the authenticated seam the browser hands a
+ * wrapped MCP App document back through so the backend can serve it from a
+ * dedicated origin.
+ *
+ * The route owns validation and the two "can't host it" answers; the listener
+ * that actually serves the bytes is `clients/web/server/app-origin-controller`
+ * and is tested separately.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { createRemoteApp } from "@inspector/core/mcp/remote/node/server.js";
+
+function post(body: unknown): Request {
+  return new Request("http://test/api/app-document", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: typeof body === "string" ? body : JSON.stringify(body),
+  });
+}
+
+function appWith(
+  publishAppDocument?: (doc: {
+    html: string;
+    csp?: string;
+  }) => { url: string } | null,
+) {
+  return createRemoteApp({
+    dangerouslyOmitAuth: true,
+    allowedOrigins: ["http://127.0.0.1:6274"],
+    initialConfig: { defaultEnvironment: {} },
+    publishAppDocument,
+  }).app;
+}
+
+describe("createRemoteApp POST /api/app-document", () => {
+  it("publishes the document and returns the URL", async () => {
+    const publish = vi
+      .fn<(doc: { html: string; csp?: string }) => { url: string } | null>()
+      .mockReturnValue({ url: "http://localhost:6276/app-document/abc" });
+    const res = await appWith(publish).request(
+      post({ html: "<h1>hi</h1>", csp: "default-src 'none'" }),
+    );
+    expect(res.status).toBe(200);
+    await expect(res.json()).resolves.toEqual({
+      url: "http://localhost:6276/app-document/abc",
+    });
+    expect(publish).toHaveBeenCalledWith({
+      html: "<h1>hi</h1>",
+      csp: "default-src 'none'",
+    });
+  });
+
+  it("accepts a document with no csp", async () => {
+    const publish = vi
+      .fn<(doc: { html: string; csp?: string }) => { url: string } | null>()
+      .mockReturnValue({ url: "http://localhost:6276/app-document/abc" });
+    const res = await appWith(publish).request(post({ html: "<h1>hi</h1>" }));
+    expect(res.status).toBe(200);
+    expect(publish).toHaveBeenCalledWith({
+      html: "<h1>hi</h1>",
+      csp: undefined,
+    });
+  });
+
+  it("answers 503 when the backend supplies no publisher", async () => {
+    // An embedder with no app-origin listener at all — the browser reads this
+    // as "no dedicated origin available" and renders the app the default way.
+    const res = await appWith().request(post({ html: "<h1>hi</h1>" }));
+    expect(res.status).toBe(503);
+  });
+
+  it("answers 503 when the publisher declines (listener never bound)", async () => {
+    const res = await appWith(() => null).request(
+      post({ html: "<h1>hi</h1>" }),
+    );
+    expect(res.status).toBe(503);
+  });
+
+  it("rejects a malformed body", async () => {
+    const res = await appWith(() => ({ url: "http://x/y" })).request(
+      post("{not json"),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  it.each([
+    ["missing html", {}],
+    ["empty html", { html: "" }],
+    ["non-string html", { html: 42 }],
+    ["non-string csp", { html: "<p>x</p>", csp: 42 }],
+  ])("rejects %s with 400", async (_label, body) => {
+    const publish = vi
+      .fn<(doc: { html: string; csp?: string }) => { url: string } | null>()
+      .mockReturnValue({ url: "http://x/y" });
+    const res = await appWith(publish).request(post(body));
+    expect(res.status).toBe(400);
+    expect(publish).not.toHaveBeenCalled();
+  });
+
+  it("rejects an oversized document with 413 rather than pinning it in memory", async () => {
+    const publish = vi
+      .fn<(doc: { html: string; csp?: string }) => { url: string } | null>()
+      .mockReturnValue({ url: "http://x/y" });
+    const res = await appWith(publish).request(
+      post({ html: "x".repeat(8 * 1024 * 1024 + 1) }),
+    );
+    expect(res.status).toBe(413);
+    expect(publish).not.toHaveBeenCalled();
+  });
+
+  it("requires the auth token like every other /api route", async () => {
+    const { app } = createRemoteApp({
+      authToken: "s3cret",
+      allowedOrigins: ["http://127.0.0.1:6274"],
+      initialConfig: { defaultEnvironment: {} },
+      publishAppDocument: () => ({ url: "http://x/y" }),
+    });
+    const unauthorized = await app.request(post({ html: "<p>x</p>" }));
+    expect(unauthorized.status).toBe(401);
+
+    const authorized = await app.request(
+      new Request("http://test/api/app-document", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-mcp-remote-auth": "Bearer s3cret",
+        },
+        body: JSON.stringify({ html: "<p>x</p>" }),
+      }),
+    );
+    expect(authorized.status).toBe(200);
+  });
+});
diff --git a/clients/web/src/test/integration/server/app-origin-controller.test.ts b/clients/web/src/test/integration/server/app-origin-controller.test.ts
new file mode 100644
index 00000000..098be332
--- /dev/null
+++ b/clients/web/src/test/integration/server/app-origin-controller.test.ts
@@ -0,0 +1,375 @@
+/**
+ * The dedicated app origin (#2056): the listener that serves an MCP App whose
+ * UI resource declares `_meta.ui.domain`, so the app document has a real origin
+ * and its requests carry a real `Origin` instead of `null`.
+ *
+ * The behaviors pinned here are the ones the feature's value rests on: the
+ * document is reachable at the URL `publish` hands back, it is served with the
+ * per-app CSP as a real response header plus a `frame-ancestors` naming the
+ * sandbox proxy, an id nobody published is a 404, and every degradation path
+ * (no listener, port taken, unusable bind host) leaves the caller able to fall
+ * back to the default opaque-origin render rather than losing the app.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { createServer, type Server } from "node:http";
+import { EventEmitter } from "node:events";
+import {
+  createAppOriginController,
+  DEFAULT_APP_ORIGIN_PORT,
+  parseDocumentId,
+  resolveAppOriginPort,
+  sandboxOriginList,
+} from "../../../../server/app-origin-controller.js";
+
+describe("resolveAppOriginPort", () => {
+  const saved = process.env.MCP_APP_ORIGIN_PORT;
+  afterEach(() => {
+    if (saved === undefined) delete process.env.MCP_APP_ORIGIN_PORT;
+    else process.env.MCP_APP_ORIGIN_PORT = saved;
+  });
+
+  it("defaults to the fixed port so it can be forwarded", () => {
+    delete process.env.MCP_APP_ORIGIN_PORT;
+    expect(resolveAppOriginPort()).toBe(DEFAULT_APP_ORIGIN_PORT);
+  });
+
+  it("honors a valid MCP_APP_ORIGIN_PORT, including an explicit 0", () => {
+    process.env.MCP_APP_ORIGIN_PORT = "9200";
+    expect(resolveAppOriginPort()).toBe(9200);
+    process.env.MCP_APP_ORIGIN_PORT = "0";
+    expect(resolveAppOriginPort()).toBe(0);
+  });
+
+  it.each(["6276abc", "70000", "-1", "nope", "  "])(
+    "warns and falls back for an invalid value %j",
+    (value) => {
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        process.env.MCP_APP_ORIGIN_PORT = value;
+        expect(resolveAppOriginPort()).toBe(DEFAULT_APP_ORIGIN_PORT);
+        // A blank value is "unset", not "invalid" — nothing to warn about.
+        if (value.trim()) {
+          expect(warnSpy).toHaveBeenCalledWith(
+            expect.stringContaining("MCP_APP_ORIGIN_PORT"),
+          );
+        } else {
+          expect(warnSpy).not.toHaveBeenCalled();
+        }
+      } finally {
+        warnSpy.mockRestore();
+      }
+    },
+  );
+});
+
+describe("parseDocumentId", () => {
+  const id = "a".repeat(32);
+
+  it("reads the id out of a document path, query string and all", () => {
+    expect(parseDocumentId(`/app-document/${id}`)).toBe(id);
+    expect(parseDocumentId(`/app-document/${id}?x=1`)).toBe(id);
+    expect(parseDocumentId(`/app-document/${id}#frag`)).toBe(id);
+  });
+
+  it.each([
+    ["undefined target", undefined],
+    ["another path", "/sandbox"],
+    ["no id", "/app-document/"],
+    ["a non-hex id", "/app-document/" + "z".repeat(32)],
+    ["a short id", "/app-document/abc"],
+    ["a traversal attempt", "/app-document/../../etc/passwd"],
+    ["a nested path", `/app-document/${id}/extra`],
+  ])("rejects %s", (_label, url) => {
+    expect(parseDocumentId(url as string | undefined)).toBeNull();
+  });
+});
+
+describe("sandboxOriginList", () => {
+  it("reduces the sandbox URL to its origin", () => {
+    expect(sandboxOriginList("http://127.0.0.1:6275/sandbox")).toEqual([
+      "http://127.0.0.1:6275",
+    ]);
+  });
+
+  it.each([[null], [undefined], [""]])(
+    "returns undefined for %j so frame-ancestors falls back to loopback",
+    (value) => {
+      // Not `[]`: an empty list would make the directive `'none'` and block the
+      // app frame outright, which is worse than a permissive loopback fallback.
+      expect(
+        sandboxOriginList(value as string | null | undefined),
+      ).toBeUndefined();
+    },
+  );
+});
+
+describe("createAppOriginController", () => {
+  let controller: ReturnType<typeof createAppOriginController> | null = null;
+
+  beforeEach(() => {
+    controller = null;
+  });
+
+  afterEach(async () => {
+    await controller?.close();
+  });
+
+  it("serves a published document at the URL it hands back, with the CSP as a header", async () => {
+    controller = createAppOriginController({
+      port: 0,
+      host: "127.0.0.1",
+      embedderOrigins: ["http://127.0.0.1:6275"],
+    });
+    const { url } = await controller.start();
+    expect(url).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
+    expect(controller.getOrigin()).toBe(url);
+
+    const published = controller.publish({
+      html: "<!doctype html><p>app</p>",
+      csp: "default-src 'none'; connect-src https://api.example.com",
+    });
+    expect(published).not.toBeNull();
+    expect(published!.url.startsWith(`${url}/app-document/`)).toBe(true);
+
+    const res = await fetch(published!.url);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+    // `nosniff` matters more here than on a page we authored: these bytes are
+    // server-supplied and untrusted.
+    expect(res.headers.get("x-content-type-options")).toBe("nosniff");
+    expect(res.headers.get("cache-control")).toContain("no-store");
+    // The per-app policy, plus a frame-ancestors naming the sandbox proxy —
+    // the only page allowed to frame this document.
+    expect(res.headers.get("content-security-policy")).toBe(
+      "default-src 'none'; connect-src https://api.example.com; frame-ancestors http://127.0.0.1:6275",
+    );
+    await expect(res.text()).resolves.toBe("<!doctype html><p>app</p>");
+  });
+
+  it("serves only frame-ancestors when the document carries no csp", async () => {
+    controller = createAppOriginController({ port: 0, host: "127.0.0.1" });
+    await controller.start();
+    const published = controller.publish({ html: "<p>x</p>" })!;
+    const res = await fetch(published.url);
+    // No embedderOrigins supplied → the loopback fallback, same as the sandbox
+    // proxy's own directive.
+    expect(res.headers.get("content-security-policy")).toBe(
+      "frame-ancestors http://127.0.0.1:* http://localhost:*",
+    );
+  });
+
+  it("mints a distinct, unguessable id per document", async () => {
+    controller = createAppOriginController({ port: 0, host: "127.0.0.1" });
+    const { url } = await controller.start();
+    const a = controller.publish({ html: "<p>a</p>" })!;
+    const b = controller.publish({ html: "<p>b</p>" })!;
+    expect(a.url).not.toBe(b.url);
+    expect(a.url.slice(`${url}/app-document/`.length)).toMatch(
+      /^[0-9a-f]{32}$/,
+    );
+    await expect((await fetch(a.url)).text()).resolves.toBe("<p>a</p>");
+    await expect((await fetch(b.url)).text()).resolves.toBe("<p>b</p>");
+  });
+
+  it("404s an unknown id and any non-document request", async () => {
+    controller = createAppOriginController({ port: 0, host: "127.0.0.1" });
+    const { url } = await controller.start();
+    expect((await fetch(`${url}/app-document/${"b".repeat(32)}`)).status).toBe(
+      404,
+    );
+    expect((await fetch(`${url}/`)).status).toBe(404);
+    expect((await fetch(`${url}/sandbox`)).status).toBe(404);
+  });
+
+  it("404s a non-GET request to a real document", async () => {
+    controller = createAppOriginController({ port: 0, host: "127.0.0.1" });
+    await controller.start();
+    const published = controller.publish({ html: "<p>x</p>" })!;
+    expect((await fetch(published.url, { method: "POST" })).status).toBe(404);
+    expect((await fetch(published.url)).status).toBe(200);
+  });
+
+  it("returns null from publish before start, so the caller falls back to srcdoc", async () => {
+    controller = createAppOriginController({ port: 0, host: "127.0.0.1" });
+    expect(controller.publish({ html: "<p>x</p>" })).toBeNull();
+    expect(controller.getOrigin()).toBeNull();
+  });
+
+  it("evicts the oldest document past the cap rather than growing unbounded", async () => {
+    controller = createAppOriginController({ port: 0, host: "127.0.0.1" });
+    await controller.start();
+    const first = controller.publish({ html: "<p>first</p>" })!;
+    // 32 is the cap; publishing 32 more must have pushed the first out.
+    for (let i = 0; i < 32; i++) {
+      controller.publish({ html: `<p>${i}</p>` });
+    }
+    expect((await fetch(first.url)).status).toBe(404);
+  });
+
+  it("404s a document past its TTL", async () => {
+    // Fake `Date` ONLY — the TTL is the sole thing that reads it, and faking
+    // the timer queue too would deadlock the real HTTP round-trip below.
+    vi.useFakeTimers({ toFake: ["Date"] });
+    try {
+      controller = createAppOriginController({ port: 0, host: "127.0.0.1" });
+      await controller.start();
+      const published = controller.publish({ html: "<p>x</p>" })!;
+      expect((await fetch(published.url)).status).toBe(200);
+      vi.setSystemTime(Date.now() + 61 * 60 * 1000);
+      expect((await fetch(published.url)).status).toBe(404);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("returns the same handle when start() is called twice", async () => {
+    controller = createAppOriginController({ port: 0, host: "127.0.0.1" });
+    const first = await controller.start();
+    const second = await controller.start();
+    expect(second).toEqual(first);
+  });
+
+  it("drops published documents on close so nothing is served after teardown", async () => {
+    controller = createAppOriginController({ port: 0, host: "127.0.0.1" });
+    await controller.start();
+    const published = controller.publish({ html: "<p>x</p>" })!;
+    await controller.close();
+    expect(controller.getOrigin()).toBeNull();
+    expect(controller.publish({ html: "<p>y</p>" })).toBeNull();
+    await expect(fetch(published.url)).rejects.toThrow();
+    controller = null;
+  });
+
+  it("advertises localhost for a wildcard bind", async () => {
+    controller = createAppOriginController({ port: 0, host: "0.0.0.0" });
+    const { url } = await controller.start();
+    // `http://0.0.0.0:PORT` isn't reachable from a browser, but a wildcard bind
+    // does serve loopback.
+    expect(url).toMatch(/^http:\/\/localhost:\d+$/);
+  });
+
+  /** Claim a port so a subsequent listen on it fails with EADDRINUSE. */
+  async function claimPort(): Promise<{
+    port: number;
+    release: () => Promise<void>;
+  }> {
+    const blocker: Server = createServer();
+    await new Promise<void>((resolve) =>
+      blocker.listen(0, "127.0.0.1", () => resolve()),
+    );
+    const addr = blocker.address();
+    const port =
+      typeof addr === "object" && addr !== null && "port" in addr
+        ? addr.port
+        : 0;
+    expect(port).toBeGreaterThan(0);
+    return {
+      port,
+      release: () =>
+        new Promise<void>((resolve) => blocker.close(() => resolve())),
+    };
+  }
+
+  it("falls back to an OS-assigned port when the fixed port is taken, loudly", async () => {
+    const { port, release } = await claimPort();
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    controller = createAppOriginController({ port, host: "127.0.0.1" });
+    try {
+      const result = await controller.start();
+      expect(result.port).toBeGreaterThan(0);
+      expect(result.port).not.toBe(port);
+      const published = controller.publish({ html: "<p>x</p>" })!;
+      expect((await fetch(published.url)).status).toBe(200);
+      // Loud: an app's backend may allowlist this origin, so a port that
+      // silently moved is the failure the fixed default exists to prevent.
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining(`App origin: port ${port} in use`),
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("MCP_APP_ORIGIN_PORT"),
+      );
+    } finally {
+      warnSpy.mockRestore();
+      await release();
+    }
+  });
+
+  it("degrades to publish()===null when listen fails for a non-EADDRINUSE reason", async () => {
+    // The backends await start() during boot; if it ever stopped resolving the
+    // whole web server would hang. Instead it resolves empty and every publish
+    // answers null, which the renderer reads as "no dedicated origin".
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    controller = createAppOriginController({
+      port: 0,
+      host: "203.0.113.1", // TEST-NET-3: not assigned to any local interface
+    });
+    try {
+      const result = await controller.start();
+      expect(result).toEqual({ port: 0, url: "" });
+      expect(controller.getOrigin()).toBeNull();
+      expect(controller.publish({ html: "<p>x</p>" })).toBeNull();
+      await expect(controller.close()).resolves.toBeUndefined();
+      expect(errorSpy).toHaveBeenCalledWith(
+        "App origin server error:",
+        expect.objectContaining({ code: expect.any(String) }),
+      );
+    } finally {
+      errorSpy.mockRestore();
+      controller = null;
+    }
+  });
+
+  it("gives up after one retry when the dynamic fallback also fails", async () => {
+    // Guards the `retriedDynamic` latch. A real `listen(0)` effectively always
+    // succeeds, so a claimed port only ever produces ONE EADDRINUSE — under
+    // which this test would pass with the latch deleted. Mock `node:http` so
+    // every listen fails: without the latch this recurses until timeout.
+    vi.resetModules();
+    const listenCalls: number[] = [];
+    vi.doMock("node:http", async () => {
+      const actual =
+        await vi.importActual<typeof import("node:http")>("node:http");
+      return {
+        ...actual,
+        createServer: () => {
+          const emitter = new EventEmitter();
+          return Object.assign(emitter, {
+            listen: (p: number) => {
+              listenCalls.push(p);
+              setImmediate(() =>
+                emitter.emit(
+                  "error",
+                  Object.assign(new Error("in use"), { code: "EADDRINUSE" }),
+                ),
+              );
+            },
+            address: () => null,
+            close: (cb?: () => void) => cb?.(),
+          });
+        },
+      };
+    });
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const mod = await import("../../../../server/app-origin-controller.js");
+      const c = mod.createAppOriginController({
+        port: DEFAULT_APP_ORIGIN_PORT,
+        host: "127.0.0.1",
+      });
+      const result = await c.start();
+      expect(result).toEqual({ port: 0, url: "" });
+      // Exactly two listens: the fixed port, then one dynamic retry.
+      expect(listenCalls).toEqual([DEFAULT_APP_ORIGIN_PORT, 0]);
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.stringContaining("in use. Apps declaring _meta.ui.domain"),
+      );
+    } finally {
+      warnSpy.mockRestore();
+      errorSpy.mockRestore();
+      vi.doUnmock("node:http");
+      vi.resetModules();
+    }
+  });
+});
diff --git a/clients/web/src/test/integration/server/server-auto-open.test.ts b/clients/web/src/test/integration/server/server-auto-open.test.ts
index 527f8b56..003ece9f 100644
--- a/clients/web/src/test/integration/server/server-auto-open.test.ts
+++ b/clients/web/src/test/integration/server/server-auto-open.test.ts
@@ -123,6 +123,7 @@ describe("startHonoServer autoOpen", () => {
         storageDir: undefined,
         allowedOrigins: [baseUrl],
         sandboxPort: 0,
+        appOriginPort: 0,
         sandboxHost: "127.0.0.1",
         logger: undefined,
         autoOpen: true,
diff --git a/clients/web/src/test/integration/server/server-token-injection.test.ts b/clients/web/src/test/integration/server/server-token-injection.test.ts
index 18fd96f0..a39ddc17 100644
--- a/clients/web/src/test/integration/server/server-token-injection.test.ts
+++ b/clients/web/src/test/integration/server/server-token-injection.test.ts
@@ -73,6 +73,7 @@ describe("startHonoServer index.html token injection (/ -> /api/*)", () => {
       // Allow the same-origin requests the test issues below.
       allowedOrigins: [baseUrl],
       sandboxPort: 0,
+      appOriginPort: 0,
       sandboxHost: "127.0.0.1",
       logger: undefined,
       autoOpen: false,
diff --git a/clients/web/src/test/integration/server/web-server-config.test.ts b/clients/web/src/test/integration/server/web-server-config.test.ts
index df51e8ab..dec8406e 100644
--- a/clients/web/src/test/integration/server/web-server-config.test.ts
+++ b/clients/web/src/test/integration/server/web-server-config.test.ts
@@ -26,6 +26,7 @@ const MUTATED_ENV_KEYS = [
   "MCP_STORAGE_DIR",
   "ALLOWED_ORIGINS",
   "MCP_SANDBOX_PORT",
+  "MCP_APP_ORIGIN_PORT",
   "SERVER_PORT",
   "MCP_LOG_FILE",
   "MCP_AUTO_OPEN_ENABLED",
@@ -43,6 +44,7 @@ const baseConfig = (): WebServerConfig => ({
   storageDir: undefined,
   allowedOrigins: ["http://localhost:6274"],
   sandboxPort: 0,
+  appOriginPort: 0,
   sandboxHost: "127.0.0.1",
   logger: undefined,
   autoOpen: false,
@@ -301,6 +303,17 @@ describe("buildWebServerConfigFromEnv", () => {
     expect(buildWebServerConfigFromEnv().sandboxPort).toBe(9100);
   });
 
+  it("resolves appOriginPort from MCP_APP_ORIGIN_PORT, defaulting to 6276", () => {
+    // The dedicated app origin (#2056). Deliberately NOT sharing the sandbox's
+    // SERVER_PORT fallback: it is a different listener and must be pinnable
+    // (and forwardable) on its own.
+    delete process.env.MCP_APP_ORIGIN_PORT;
+    process.env.SERVER_PORT = "9100";
+    expect(buildWebServerConfigFromEnv().appOriginPort).toBe(6276);
+    process.env.MCP_APP_ORIGIN_PORT = "9300";
+    expect(buildWebServerConfigFromEnv().appOriginPort).toBe(9300);
+  });
+
   it("sets MCP_STORAGE_DIR when present", () => {
     process.env.MCP_STORAGE_DIR = "/tmp/storage";
     expect(buildWebServerConfigFromEnv().storageDir).toBe("/tmp/storage");
diff --git a/clients/web/static/sandbox_proxy.html b/clients/web/static/sandbox_proxy.html
index 2f4336e8..ddd676a2 100644
--- a/clients/web/static/sandbox_proxy.html
+++ b/clients/web/static/sandbox_proxy.html
@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="color-scheme" content="light dark" />
-    <!-- Isolation model: the inner iframe is sandboxed WITHOUT
+    <!-- Isolation model: by default the inner iframe is sandboxed WITHOUT
          `allow-same-origin`, so the untrusted app runs under an opaque
          ("null") origin. That is the structural boundary — the app cannot
          touch this proxy's DOM, window, or cookies, so it cannot bypass its
@@ -15,6 +15,18 @@
          resource-ready message's `sandbox` field; `allow-same-origin` is
          always stripped from a server-supplied value.
 
+         Dedicated-origin exception (#2056): an app whose UI resource declares
+         `_meta.ui.domain` is instead served from the host's own app-origin
+         listener, handed to us as the resource-ready message's `src`. That
+         frame IS granted `allow-same-origin` — an opaque origin sends
+         `Origin: null`, which defeats the CORS / OAuth-callback / API-key
+         allowlists the field exists to support. The boundary is preserved by
+         the origin itself rather than by opacity: the listener is on its own
+         port, so the app is cross-origin to this proxy and to the host, and
+         the grant is refused outright if the URL's origin equals this page's.
+         The grant is host-driven — it is never reachable from the server's
+         own `sandbox` string, which is still stripped.
+
          Network/resource egress from the inner document is constrained by a
          Content-Security-Policy that the HOST builds and bakes into the
          delivered HTML before it reaches this proxy (see
@@ -85,13 +97,21 @@
       // This is the origin we expect all parent messages to come from.
       const EXPECTED_HOST_ORIGIN = new URL(document.referrer).origin;
 
-      // The inner iframe is sandboxed without allow-same-origin, so its
-      // document has an opaque origin and every postMessage from it arrives
+      // The inner iframe is sandboxed without allow-same-origin by default, so
+      // its document has an opaque origin and every postMessage from it arrives
       // with event.origin === "null" (the literal string). That value is
       // checked below as a defense-in-depth assertion; the actual identity
       // proof is `event.source === inner.contentWindow`, which a sibling
       // frame cannot forge.
-      const INNER_ORIGIN = "null";
+      //
+      // The dedicated-origin path (#2056) is the one exception: when the host
+      // supplies a `src` on its own app-origin listener, the frame is granted
+      // allow-same-origin so the app has a REAL origin — which is the entire
+      // point, since an opaque origin sends `Origin: null` and defeats any
+      // CORS / OAuth-callback / API-key allowlist the app's backend applies.
+      // `innerOrigin` is then that URL's origin, and the assertion above still
+      // holds against it.
+      let innerOrigin = "null";
 
       // Security self-test: verify iframe isolation is working correctly.
       // This MUST throw a SecurityError -- if `window.top` is accessible, the sandbox
@@ -158,7 +178,37 @@
           }
 
           if (event.data && event.data.method === RESOURCE_READY_NOTIFICATION) {
-            const { html, sandbox, permissions } = event.data.params;
+            const { html, sandbox, permissions, src } = event.data.params;
+            // The host asked for the dedicated-origin path: it published the
+            // wrapped document to its own app-origin listener and is handing
+            // us the URL. Only an absolute http(s) URL is honored — anything
+            // else (a relative path, a `javascript:` or `data:` URL) falls
+            // through to the srcdoc path below rather than being navigated to.
+            let srcUrl = null;
+            if (typeof src === "string") {
+              try {
+                const parsed = new URL(src);
+                if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+                  srcUrl = parsed;
+                } else {
+                  console.warn("[Sandbox] ignoring non-http(s) src:", src);
+                }
+              } catch (e) {
+                console.warn("[Sandbox] ignoring unparseable src:", src);
+              }
+            }
+            // The app origin MUST differ from this proxy's own — otherwise
+            // granting allow-same-origin below would put the untrusted app in
+            // this realm, exactly the escape the double-iframe model exists to
+            // prevent. Refuse rather than degrade quietly: this is a host
+            // misconfiguration, not app input.
+            if (srcUrl && srcUrl.origin === window.location.origin) {
+              console.error(
+                "[Sandbox] refusing a src on the proxy's own origin:",
+                srcUrl.origin,
+              );
+              srcUrl = null;
+            }
             if (typeof sandbox === "string") {
               // Never grant allow-same-origin even if the server asks for it —
               // that would let the untrusted app reach this proxy's DOM and
@@ -179,13 +229,34 @@
               }
               inner.setAttribute("sandbox", safeTokens.join(" "));
             }
+            if (srcUrl) {
+              // Re-grant what the strip above removes unconditionally. Safe
+              // here and only here: the document is served from a DIFFERENT
+              // origin than this proxy (asserted above), so same-origin policy
+              // still denies it this realm's DOM — it gains its own origin,
+              // not ours.
+              const tokens = (inner.getAttribute("sandbox") || "")
+                .split(/\s+/)
+                .filter(Boolean);
+              if (!tokens.some((t) => t.toLowerCase() === "allow-same-origin")) {
+                tokens.push("allow-same-origin");
+              }
+              inner.setAttribute("sandbox", tokens.join(" "));
+            }
             // Set Permission Policy allow attribute if permissions are requested
             const allowAttribute = buildAllowAttribute(permissions);
             if (allowAttribute) {
               console.log("[Sandbox] Setting allow attribute:", allowAttribute);
               inner.setAttribute("allow", allowAttribute);
             }
-            if (typeof html === "string") {
+            if (srcUrl) {
+              // Navigate to the host's app-origin URL. The per-app CSP is
+              // delivered as a real response header there (stronger than the
+              // <meta> the srcdoc path relies on), so no wrapping applies here
+              // — this proxy still never parses the untrusted bytes.
+              innerOrigin = srcUrl.origin;
+              inner.src = srcUrl.href;
+            } else if (typeof html === "string") {
               // The host has already wrapped the app's HTML in a fixed shell
               // whose first <head> child is the CSP <meta>; assign it verbatim.
               // srcdoc is the only delivery path that works without
@@ -198,7 +269,16 @@
             }
           } else {
             if (inner && inner.contentWindow) {
-              inner.contentWindow.postMessage(event.data, "*");
+              // Target the inner frame's real origin on the dedicated-origin
+              // path, so a frame that navigated itself elsewhere stops
+              // receiving host messages. The opaque default has no targetable
+              // origin ("null" is not a valid targetOrigin), so it keeps "*" —
+              // safe there because the frame is `srcdoc` and cannot navigate
+              // to another origin's document without allow-top-navigation.
+              inner.contentWindow.postMessage(
+                event.data,
+                innerOrigin === "null" ? "*" : innerOrigin,
+              );
             }
           }
         } else if (event.source === inner.contentWindow) {
@@ -207,12 +287,12 @@
           // sandbox means its origin serialises as the literal string "null";
           // assert that as defense-in-depth so a future change that
           // accidentally re-grants allow-same-origin is caught here.
-          if (event.origin !== INNER_ORIGIN) {
+          if (event.origin !== innerOrigin) {
             console.error(
               "[Sandbox] Rejecting message from inner iframe with unexpected origin:",
               event.origin,
-              "expected opaque:",
-              INNER_ORIGIN,
+              "expected:",
+              innerOrigin,
             );
             return;
           }
diff --git a/core/mcp/remote/node/server.ts b/core/mcp/remote/node/server.ts
index 5e744e40..1541d646 100644
--- a/core/mcp/remote/node/server.ts
+++ b/core/mcp/remote/node/server.ts
@@ -256,6 +256,23 @@ export interface RemoteServerOptions {
   /** Optional sandbox URL for MCP Apps tab. When set, GET /api/config includes sandboxUrl. */
   sandboxUrl?: string;
 
+  /**
+   * Publish a fully-wrapped MCP App document to the backend's dedicated
+   * app-origin listener and return the URL to load it from (#2056). When set,
+   * `POST /api/app-document` is served; when absent — or when it returns
+   * `null`, meaning the listener never bound — the route answers 503 and the
+   * browser falls back to the default opaque-origin `srcdoc` render.
+   *
+   * Supplied by the web backends only. It is an option rather than a route
+   * built here because the listener is a `clients/web/server` concern; this
+   * module owns nothing but the authenticated seam the browser reaches it
+   * through.
+   */
+  publishAppDocument?: (doc: {
+    html: string;
+    csp?: string;
+  }) => { url: string } | null;
+
   /** Initial config for GET /api/config. Caller must pass this (e.g. from webServerConfigToInitialPayload(config)). */
   initialConfig: InitialConfigPayload;
 
@@ -280,6 +297,15 @@ export interface RemoteServerOptions {
   secretStorageResolver?: () => Promise<SecretStorageInfo | undefined>;
 }
 
+/**
+ * Upper bound on a single MCP App document accepted by `POST /api/app-document`
+ * (#2056). Counted in UTF-16 code units, which is what `String.length` gives —
+ * a loose but cheap proxy for bytes, and it only has to keep a runaway or
+ * hostile payload from being pinned in the backend's memory. Generous: a real
+ * app inlines its own scripts and styles into this one document.
+ */
+const MAX_APP_DOCUMENT_CHARS = 8 * 1024 * 1024;
+
 export interface CreateRemoteAppResult {
   /** The Hono app */
   app: Hono;
@@ -707,6 +733,45 @@ export function createRemoteApp(
     return c.json(payload);
   });
 
+  /**
+   * Hand the backend a wrapped MCP App document and get back the URL its
+   * dedicated origin serves it from (#2056).
+   *
+   * The browser is what holds the document — it read the `ui://` resource over
+   * the MCP connection and wrapped it — so the only way it can reach a real
+   * HTTP origin is to hand the bytes back. This route is the authenticated
+   * seam for that; the returned URL is unguessable and is served by a separate
+   * listener on its own port, which is what makes the app's origin real
+   * instead of opaque.
+   */
+  app.post("/api/app-document", async (c) => {
+    const publish = options.publishAppDocument;
+    if (!publish) {
+      return c.json({ error: "App-origin hosting is not available" }, 503);
+    }
+    let body: { html?: unknown; csp?: unknown };
+    try {
+      body = (await c.req.json()) as { html?: unknown; csp?: unknown };
+    } catch {
+      return c.json({ error: "Invalid JSON body" }, 400);
+    }
+    const { html, csp } = body;
+    if (typeof html !== "string" || html === "") {
+      return c.json({ error: "Missing html" }, 400);
+    }
+    if (csp !== undefined && typeof csp !== "string") {
+      return c.json({ error: "csp must be a string" }, 400);
+    }
+    if (html.length > MAX_APP_DOCUMENT_CHARS) {
+      return c.json({ error: "Document too large" }, 413);
+    }
+    const published = publish({ html, csp });
+    if (!published) {
+      return c.json({ error: "App-origin hosting is not available" }, 503);
+    }
+    return c.json(published);
+  });
+
   app.post("/api/mcp/connect", async (c) => {
     let body: RemoteConnectRequest;
     try {

From 8e8c1bbad9b17217f4f77e7de434e14b32bf6f17 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 23:21:41 -0400
Subject: [PATCH 07/14] test(web): prove the dedicated app origin end to end
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`frame-ancestors` is checked against every ancestor, not just the parent.
A published app document is framed by the sandbox proxy, which is framed
by the Inspector page — so admitting only the proxy's origin blocked the
frame outright (it rendered as a chrome-error frame that never reached
the bridge). `appDocumentEmbedders` now admits both.

That failure was invisible to every unit test, so `smoke:web:app` grows a
second phase: the same demo app declaring `_meta.ui.domain`, driven
through the same connect → open → ready chain, then asserting the two
facts that only hold on the dedicated path — the inner frame was
navigated to a published document, and its own `location.origin` is a
real http origin rather than "null". Both phases end at
`data-app-status="ready"`, so nothing short of reading the frame's origin
can tell them apart.

Adds `test-servers/configs/mcp-app-domain-http.json` (and a `domain`
param on the `mcp_app_demo_widget` preset) as the showcase server for
both the smoke and hand testing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/server/app-origin-controller.ts   |  36 +++--
 clients/web/server/server.ts                  |   7 +-
 clients/web/server/vite-hono-plugin.ts        |   7 +-
 .../server/app-origin-controller.test.ts      |  29 +++-
 scripts/smoke-web-app.mjs                     | 124 ++++++++++++++++--
 test-servers/configs/mcp-app-domain-http.json |  17 +++
 test-servers/src/preset-registry.ts           |   2 +-
 test-servers/src/test-server-fixtures.ts      |  10 +-
 8 files changed, 199 insertions(+), 33 deletions(-)
 create mode 100644 test-servers/configs/mcp-app-domain-http.json

diff --git a/clients/web/server/app-origin-controller.ts b/clients/web/server/app-origin-controller.ts
index 6f274e31..f455542a 100644
--- a/clients/web/server/app-origin-controller.ts
+++ b/clients/web/server/app-origin-controller.ts
@@ -75,23 +75,33 @@ const MAX_DOCUMENTS = 32;
 const DOCUMENT_TTL_MS = 60 * 60 * 1000;
 
 /**
- * The sandbox proxy's origin as a one-entry list for
- * {@link AppOriginControllerOptions.embedderOrigins}, or `undefined` when the
- * sandbox never bound (its controller degrades to a null URL). Passing
- * `undefined` is what makes the app-origin `frame-ancestors` fall back to
- * loopback rather than to `'none'`, which would block the frame outright.
+ * The origins that may appear in a published document's ancestor chain, for
+ * {@link AppOriginControllerOptions.embedderOrigins}.
+ *
+ * There are **two**, and getting this wrong blocks the frame outright: CSP's
+ * `frame-ancestors` is checked against *every* ancestor, not just the immediate
+ * parent. A published document is framed by the sandbox proxy, which is itself
+ * framed by the Inspector app page — so the directive has to admit the proxy's
+ * origin **and** the app's, which is exactly the backend's origin allow-list.
+ *
+ * `undefined` when neither is known, which makes the directive fall back to the
+ * loopback family rather than to `'none'`.
  */
-export function sandboxOriginList(
+export function appDocumentEmbedders(
   sandboxUrl: string | null | undefined,
+  allowedOrigins?: string[],
 ): string[] | undefined {
-  if (!sandboxUrl) return undefined;
-  try {
-    return [new URL(sandboxUrl).origin];
-  } catch {
-    /* v8 ignore next -- the sandbox controller only ever emits a URL it built
-       itself; an unparseable value would be a bug there, not input. */
-    return undefined;
+  const origins: string[] = [];
+  if (sandboxUrl) {
+    try {
+      origins.push(new URL(sandboxUrl).origin);
+    } catch {
+      /* v8 ignore next -- the sandbox controller only ever emits a URL it built
+         itself; an unparseable value would be a bug there, not input. */
+    }
   }
+  origins.push(...(allowedOrigins ?? []));
+  return origins.length > 0 ? origins : undefined;
 }
 
 export interface AppOriginControllerOptions {
diff --git a/clients/web/server/server.ts b/clients/web/server/server.ts
index 3a43e5b3..f128685c 100644
--- a/clients/web/server/server.ts
+++ b/clients/web/server/server.ts
@@ -18,7 +18,7 @@ import { formatHostForUrl } from "../../../core/node/hostUrl.ts";
 import { createSandboxController } from "./sandbox-controller.js";
 import {
   createAppOriginController,
-  sandboxOriginList,
+  appDocumentEmbedders,
 } from "./app-origin-controller.js";
 import { injectAuthToken } from "./inject-auth-token.js";
 import type { WebServerConfig } from "./web-server-config.js";
@@ -54,7 +54,10 @@ export async function startHonoServer(
   const appOriginController = createAppOriginController({
     port: config.appOriginPort,
     host: config.sandboxHost,
-    embedderOrigins: sandboxOriginList(sandboxController.getUrl()),
+    embedderOrigins: appDocumentEmbedders(
+      sandboxController.getUrl(),
+      config.allowedOrigins,
+    ),
   });
   await appOriginController.start();
 
diff --git a/clients/web/server/vite-hono-plugin.ts b/clients/web/server/vite-hono-plugin.ts
index c38f3fca..59cee730 100644
--- a/clients/web/server/vite-hono-plugin.ts
+++ b/clients/web/server/vite-hono-plugin.ts
@@ -18,7 +18,7 @@ import { createRemoteApp } from "../../../core/mcp/remote/node/server.ts";
 import { createSandboxController } from "./sandbox-controller.js";
 import {
   createAppOriginController,
-  sandboxOriginList,
+  appDocumentEmbedders,
 } from "./app-origin-controller.js";
 import { injectAuthToken } from "./inject-auth-token.js";
 import type { WebServerConfig } from "./web-server-config.js";
@@ -77,7 +77,10 @@ export function honoMiddlewarePlugin(config: WebServerConfig): Plugin {
       const appOriginController = createAppOriginController({
         port: config.appOriginPort,
         host: config.sandboxHost,
-        embedderOrigins: sandboxOriginList(sandboxController.getUrl()),
+        embedderOrigins: appDocumentEmbedders(
+          sandboxController.getUrl(),
+          config.allowedOrigins,
+        ),
       });
       await appOriginController.start();
       // Resolved before the API is built so `/api/config` and the banner
diff --git a/clients/web/src/test/integration/server/app-origin-controller.test.ts b/clients/web/src/test/integration/server/app-origin-controller.test.ts
index 098be332..dced7e5e 100644
--- a/clients/web/src/test/integration/server/app-origin-controller.test.ts
+++ b/clients/web/src/test/integration/server/app-origin-controller.test.ts
@@ -19,7 +19,7 @@ import {
   DEFAULT_APP_ORIGIN_PORT,
   parseDocumentId,
   resolveAppOriginPort,
-  sandboxOriginList,
+  appDocumentEmbedders,
 } from "../../../../server/app-origin-controller.js";
 
 describe("resolveAppOriginPort", () => {
@@ -85,20 +85,37 @@ describe("parseDocumentId", () => {
   });
 });
 
-describe("sandboxOriginList", () => {
-  it("reduces the sandbox URL to its origin", () => {
-    expect(sandboxOriginList("http://127.0.0.1:6275/sandbox")).toEqual([
+describe("appDocumentEmbedders", () => {
+  it("admits the sandbox proxy AND the Inspector page", () => {
+    // `frame-ancestors` is checked against EVERY ancestor, not just the parent:
+    // the document is framed by the proxy, which is framed by the app page.
+    // Omitting the app page's origin blocks the frame outright (it renders as a
+    // chrome-error frame that never reaches the bridge).
+    expect(
+      appDocumentEmbedders("http://127.0.0.1:6275/sandbox", [
+        "http://127.0.0.1:6274",
+        "http://localhost:6274",
+      ]),
+    ).toEqual([
       "http://127.0.0.1:6275",
+      "http://127.0.0.1:6274",
+      "http://localhost:6274",
+    ]);
+  });
+
+  it("still returns the allow-list when the sandbox never bound", () => {
+    expect(appDocumentEmbedders(null, ["http://127.0.0.1:6274"])).toEqual([
+      "http://127.0.0.1:6274",
     ]);
   });
 
   it.each([[null], [undefined], [""]])(
-    "returns undefined for %j so frame-ancestors falls back to loopback",
+    "returns undefined for %j with no allow-list, so frame-ancestors falls back to loopback",
     (value) => {
       // Not `[]`: an empty list would make the directive `'none'` and block the
       // app frame outright, which is worse than a permissive loopback fallback.
       expect(
-        sandboxOriginList(value as string | null | undefined),
+        appDocumentEmbedders(value as string | null | undefined),
       ).toBeUndefined();
     },
   );
diff --git a/scripts/smoke-web-app.mjs b/scripts/smoke-web-app.mjs
index b849f357..485f9e21 100644
--- a/scripts/smoke-web-app.mjs
+++ b/scripts/smoke-web-app.mjs
@@ -8,6 +8,13 @@
  * unexercised by any smoke. This closes that gap: it drives the full
  * **connect → open app → widget ready** chain against a real MCP App server.
  *
+ * A second phase (#2056) drives the same app declaring `_meta.ui.domain`, and
+ * asserts the thing that field exists for: the app document is served from the
+ * backend's dedicated app-origin listener and runs at a REAL origin, not the
+ * opaque one whose requests carry `Origin: null`. Both phases end at
+ * `data-app-status="ready"`, so only reading the inner frame's own
+ * `location.origin` can tell them apart.
+ *
  * The assertion is the `data-app-status="ready"` contract documented in
  * clients/web/README.md ("MCP Apps screen automation contract"): the renderer
  * only reports `ready` once the widget has loaded inside the sandbox iframe and
@@ -72,6 +79,14 @@ const appConfig = join(
   "configs",
   "mcp-app-http.json",
 );
+// The same demo app, with `_meta.ui.domain` declared (#2056). Phase 2 drives it
+// to prove the dedicated-origin path end to end.
+const appDomainConfig = join(
+  repoRoot,
+  "test-servers",
+  "configs",
+  "mcp-app-domain-http.json",
+);
 // The path clients/web/server/sandbox-controller.ts resolves at runtime, from
 // the built runner at clients/web/build/. Kept in sync with the `join(__dirname,
 // "../static/sandbox_proxy.html")` there.
@@ -104,6 +119,7 @@ const FATAL_CONSOLE = /^Uncaught\b|Failed to fetch dynamically imported module/;
 let mcpUrl = null;
 
 let mcpServer = null;
+let domainMcpServer = null;
 let browser = null;
 const server = startProdWebServer({
   host: HOST,
@@ -127,6 +143,14 @@ async function shutdown() {
     mcpServer = null;
     await stopChild(child, { label: "smoke:web:app", what: "MCP test server" });
   }
+  if (domainMcpServer) {
+    const child = domainMcpServer;
+    domainMcpServer = null;
+    await stopChild(child, {
+      label: "smoke:web:app",
+      what: "MCP test server (domain)",
+    });
+  }
 }
 
 async function fail(message) {
@@ -176,15 +200,18 @@ function ensureTestServer() {
  * createTestServerHttp resolves through findAvailablePort(), which walks upward
  * when the configured value is taken.
  */
-async function startMcpServer() {
+async function startMcpServer(
+  config = appConfig,
+  publish = (child) => {
+    mcpServer = child;
+  },
+) {
   const { match } = await startAnnouncedChild({
     command: process.execPath,
-    args: [composableServer, "--config", appConfig],
+    args: [composableServer, "--config", config],
     cwd: repoRoot,
     pattern: /listening at (http:\/\/\S+)/i,
-    onSpawn: (child) => {
-      mcpServer = child;
-    },
+    onSpawn: publish,
     what: `MCP test server (${composableServer})`,
   });
   return { url: match[1] };
@@ -256,10 +283,11 @@ try {
   // Deep link: connect, switch to the Apps tab, pre-select the app tool, and
   // fire "Open App". autoConnect/autoOpen must equal the session token (CSRF
   // gate). Shape owned by clients/web/README.md#deep-link-auto-connect.
-  const url =
-    `${server.baseUrl}/?serverUrl=${encodeURIComponent(mcpUrl)}` +
+  const deepLink = (target) =>
+    `${server.baseUrl}/?serverUrl=${encodeURIComponent(target)}` +
     `&transport=http&autoConnect=${TOKEN}&openApp=${APP_TOOL}` +
     `&appArgs=${encodeAppArgs({ title: "smoke:web:app" })}&autoOpen=${TOKEN}`;
+  const url = deepLink(mcpUrl);
 
   const drive = async () => {
     const response = await page.goto(url, {
@@ -309,10 +337,88 @@ try {
     }
   };
 
+  /**
+   * Phase 2 (#2056): the same app, this time declaring `_meta.ui.domain`.
+   *
+   * Phase 1 proves the default render works; it cannot distinguish it from the
+   * dedicated-origin render, because both end at `data-app-status="ready"`. The
+   * thing #2056 is actually about is the *origin the app document runs at* — an
+   * opaque origin sends `Origin: null`, which no CORS / OAuth-callback /
+   * API-key allowlist can admit. So this phase asserts the two facts that only
+   * hold on the dedicated path: the inner frame was navigated to a published
+   * document on the backend's app-origin listener, and the document's own
+   * `location.origin` is a real origin rather than the literal "null".
+   *
+   * It reuses the running web server and browser page — only a second MCP
+   * server and a second deep-link navigate are added.
+   */
+  const driveDedicatedOrigin = async () => {
+    const { url: domainUrl } = await startMcpServer(
+      appDomainConfig,
+      (child) => {
+        domainMcpServer = child;
+      },
+    );
+    await page.goto(deepLink(domainUrl), {
+      waitUntil: "domcontentloaded",
+      timeout: 30_000,
+    });
+    await page
+      .locator('[data-testid="connection-status"][data-status="connected"]')
+      .waitFor({ state: "attached", timeout: 45_000 });
+    try {
+      await page
+        .locator('[data-testid="apps-form"][data-app-status="ready"]')
+        .waitFor({ state: "attached", timeout: 45_000 });
+    } catch {
+      const form = page.locator('[data-testid="apps-form"]');
+      const appStatus = (await form.count())
+        ? await form.getAttribute("data-app-status")
+        : "(no apps-form)";
+      const appError = (await form.count())
+        ? await form.getAttribute("data-app-error")
+        : null;
+      throw new Error(
+        `dedicated-origin app never reached data-app-status="ready" (last: ` +
+          `"${appStatus}"${appError ? `, data-app-error="${appError}"` : ""}) — ` +
+          `frames: ${page
+            .frames()
+            .map((f) => f.url() || "(blank)")
+            .join(", ")}`,
+      );
+    }
+
+    const appFrame = page
+      .frames()
+      .find((f) => /\/app-document\/[0-9a-f]{32}$/.test(f.url()));
+    if (!appFrame) {
+      throw new Error(
+        "app declaring _meta.ui.domain was not served from the dedicated app " +
+          `origin — no frame at /app-document/<id> (frames: ${page
+            .frames()
+            .map((f) => f.url() || "(blank)")
+            .join(", ")})`,
+      );
+    }
+    const origin = await appFrame.evaluate(() => window.location.origin);
+    if (!/^http:\/\/[^/]+$/.test(origin)) {
+      throw new Error(
+        `app document ran at origin "${origin}" — expected a real http origin. ` +
+          "An opaque origin sends `Origin: null`, which is the bug #2056 fixes.",
+      );
+    }
+    return { origin, url: appFrame.url() };
+  };
+
   // Race against launcher death so a mid-run server crash is reported as the
   // real cause instead of a downstream timeout.
+  let dedicated = null;
   try {
     await Promise.race([server.whenChildExits(), drive()]);
+    dedicated = await Promise.race([
+      server.whenChildExits(),
+      driveDedicatedOrigin(),
+    ]);
   } catch (err) {
     const diagnostics = [
       ...pageErrors,
@@ -345,7 +451,9 @@ try {
 
   console.log(
     `smoke:web:app OK — connected to ${mcpUrl}, opened "${APP_TOOL}", ` +
-      `widget reached data-app-status="ready" through the sandbox proxy`,
+      `widget reached data-app-status="ready" through the sandbox proxy; ` +
+      `and an app declaring _meta.ui.domain rendered from the dedicated origin ` +
+      `${dedicated?.origin} (${dedicated?.url})`,
   );
   await shutdown();
   process.exit(0);
diff --git a/test-servers/configs/mcp-app-domain-http.json b/test-servers/configs/mcp-app-domain-http.json
new file mode 100644
index 00000000..6d99d514
--- /dev/null
+++ b/test-servers/configs/mcp-app-domain-http.json
@@ -0,0 +1,17 @@
+{
+  "serverInfo": {
+    "name": "mcp-app-domain-showcase",
+    "version": "1.0.0"
+  },
+  "tools": [{ "preset": "echo" }, { "preset": "mcp_app_demo" }],
+  "resources": [
+    {
+      "preset": "mcp_app_demo_widget",
+      "params": { "domain": "my-app-domain.example.com" }
+    }
+  ],
+  "transport": {
+    "type": "streamable-http",
+    "port": 3134
+  }
+}
diff --git a/test-servers/src/preset-registry.ts b/test-servers/src/preset-registry.ts
index b535bb20..f3f4bdfc 100644
--- a/test-servers/src/preset-registry.ts
+++ b/test-servers/src/preset-registry.ts
@@ -253,7 +253,7 @@ function resolveResourcePreset(
     case "numbered_resources":
       return createNumberedResources(Number(get("count")) || 3);
     case "mcp_app_demo_widget":
-      return createMcpAppDemoResource();
+      return createMcpAppDemoResource(get("domain") as string | undefined);
     case "choose_option_app":
       return createAppElicitationResource();
     case "rfc6570_base":
diff --git a/test-servers/src/test-server-fixtures.ts b/test-servers/src/test-server-fixtures.ts
index 5022e0f3..2cc29cf2 100644
--- a/test-servers/src/test-server-fixtures.ts
+++ b/test-servers/src/test-server-fixtures.ts
@@ -1617,8 +1617,15 @@ export function createMcpAppDemoTool(): ToolDefinition {
  * `_meta.ui.csp` (no external connect/resource domains) and a sample
  * `permissions` block so `--app-info` and the host's CSP enforcement both have
  * something to read.
+ *
+ * `domain` is the spec field by which a server asks its host for a stable,
+ * dedicated origin (#2056). Omitted by default so the default opaque-origin
+ * render stays the thing this fixture exercises; pass one to drive the
+ * dedicated-origin path instead. Its *value* is not an address the Inspector
+ * serves — the spec makes the format host-dependent, and the Inspector reads
+ * any non-empty string as "give me a real origin".
  */
-export function createMcpAppDemoResource(): ResourceDefinition {
+export function createMcpAppDemoResource(domain?: string): ResourceDefinition {
   return {
     name: "mcp_app_demo_widget",
     uri: MCP_APP_DEMO_URI,
@@ -1630,6 +1637,7 @@ export function createMcpAppDemoResource(): ResourceDefinition {
         csp: { connectDomains: [], resourceDomains: [] },
         permissions: { clipboard: false },
         prefersBorder: true,
+        ...(domain ? { domain } : {}),
       },
     },
   };

From 41c063b9ec46afd134a07ec61bf5697d7a37870e Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 23:22:08 -0400
Subject: [PATCH 08/14] docs: add the dedicated-origin showcase server to the
 README

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 README.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/README.md b/README.md
index 7594ddfa..db796475 100644
--- a/README.md
+++ b/README.md
@@ -143,6 +143,7 @@ Each config below is a ready-made server for exercising one feature by hand. Loa
 | ----------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------- |
 | `mcp-app-http.json` **(legacy era)**      | An MCP App (UI resource + app tool) in the Apps tab | [#1859](https://github.com/modelcontextprotocol/inspector/issues/1859) |
 | `app-elicitation-http.json` **(legacy era)** | An MCP App rendering a form elicitation           | [#1854](https://github.com/modelcontextprotocol/inspector/issues/1854) |
+| `mcp-app-domain-http.json` **(legacy era)** | An MCP App asking for a dedicated origin (`_meta.ui.domain`) | [#2056](https://github.com/modelcontextprotocol/inspector/issues/2056) |
 | `modern-mrtr-http.json`                   | A single MRTR round-trip                           | —                                                                      |
 | `mrtr-showcase-http.json`                 | Every MRTR preset in one server                    | [#1860](https://github.com/modelcontextprotocol/inspector/issues/1860) |
 | `modern-network-http.json`                | Network tab: `Mcp-*` headers + error taxonomy      | [#1628](https://github.com/modelcontextprotocol/inspector/issues/1628) |
@@ -165,6 +166,16 @@ Open the Apps tab, select `mcp_app_demo`, give it a title and click **Open App**
 
 For the scripted version of the same flow (`--app-info` probe → deep link → rendered widget), see [Reviewing an MCP App](./docs/mcp-app-review.md).
 
+#### An App's dedicated origin
+
+`mcp-app-domain-http.json` serves the same `mcp_app_demo` widget as above, with one addition: its UI resource declares `_meta.ui.domain`. Plain streamable-HTTP; connect with the **default (legacy)** protocol era.
+
+That field is how a server asks its host for a stable, dedicated origin. Without one, an App renders into a `srcdoc` frame sandboxed without `allow-same-origin`, so its document has an *opaque* origin and every request it makes carries `Origin: null` — which no CORS policy, OAuth callback, or API-key allowlist can admit ([#2056](https://github.com/modelcontextprotocol/inspector/issues/2056)).
+
+Open the Apps tab and run `mcp_app_demo`. The widget renders identically to `mcp-app-http.json` — the difference is not visual. Inspect the inner iframe in devtools: on this server it is served from `http://localhost:6276/app-document/<id>` and `location.origin` is that real origin, where on `mcp-app-http.json` it is `about:srcdoc` with an origin of `null`.
+
+The spec makes `domain`'s format **host-dependent**, and the Inspector owns no domain infrastructure — so it reads any non-empty value as a *request* rather than an address, and answers with a real loopback origin of its own. See [MCP App dedicated origins](./clients/web/README.md#mcp-app-dedicated-origins-metauidomain) for the full contract, including what the one shared origin does and does not isolate, and how every failure falls back to the default render rather than blanking the app.
+
 #### App-rendered form elicitations
 
 `app-elicitation-http.json` serves `app_choose_option` alongside the `choose_option_app` UI resource (`ui://demo/choose-option.html`). The tool sends a completely ordinary form `elicitation/create` — the only thing added is `_meta.ui.resourceUri` naming that app. Plain streamable-HTTP; connect with the **default (legacy)** protocol era.

From fa441da85f011e382aecd7104aae87ee3efcd4c7 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Sun, 23 Aug 2026 23:48:30 -0400
Subject: [PATCH 09/14] fix(web): harden the app-origin paths and correct three
 docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copilot review round 1 on #2100.

- POST /api/app-document: `null` and `[1,2]` are valid JSON, so the
  destructure that followed threw OUTSIDE the parse try/catch and turned a
  malformed body into a 500 instead of the documented 400.
- app-origin controller: the error handler cleared `server` but not
  `origin`, and `publish` gates on `origin` — so an error after a successful
  listen kept minting URLs on a dead port and the browser never took the
  srcdoc fallback. Clear both, and drop the now-unfetchable documents.
- sandbox proxy: drop a stale `srcdoc` before navigating to a dedicated
  origin (srcdoc wins over src), and restore the opaque-origin posture —
  strip `allow-same-origin`, reset `innerOrigin` — before assigning `srcdoc`
  on the fallback path. Not reachable today (each render remounts the
  iframe), but the cost of being wrong about that later is an isolation
  boundary.
- publishAppDocument tests: replace two `as unknown as Response` casts with
  real `Response`s.
- docs: `frame-ancestors` admits the proxy AND the Inspector page (every
  ancestor is checked); the shared helper falls back to loopback, not
  `'none'`; the showcase origin is `127.0.0.1`, the default bind address.
- tests: null/array body, post-listen error, and both factories receiving a
  working `publishAppDocument`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 README.md                                     |  2 +-
 clients/web/README.md                         |  6 ++-
 clients/web/server/app-origin-controller.ts   |  9 +++-
 clients/web/server/sandbox-controller.ts      |  8 +--
 clients/web/src/App.test.tsx                  | 54 +++++++++++++++++++
 .../web/src/lib/publishAppDocument.test.ts    | 24 +++++----
 .../mcp/remote/app-document-route.test.ts     | 14 +++++
 .../server/app-origin-controller.test.ts      | 52 ++++++++++++++++++
 clients/web/static/sandbox_proxy.html         | 22 ++++++++
 core/mcp/remote/node/server.ts                | 17 ++++--
 10 files changed, 188 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index db796475..d9fce752 100644
--- a/README.md
+++ b/README.md
@@ -172,7 +172,7 @@ For the scripted version of the same flow (`--app-info` probe → deep link →
 
 That field is how a server asks its host for a stable, dedicated origin. Without one, an App renders into a `srcdoc` frame sandboxed without `allow-same-origin`, so its document has an *opaque* origin and every request it makes carries `Origin: null` — which no CORS policy, OAuth callback, or API-key allowlist can admit ([#2056](https://github.com/modelcontextprotocol/inspector/issues/2056)).
 
-Open the Apps tab and run `mcp_app_demo`. The widget renders identically to `mcp-app-http.json` — the difference is not visual. Inspect the inner iframe in devtools: on this server it is served from `http://localhost:6276/app-document/<id>` and `location.origin` is that real origin, where on `mcp-app-http.json` it is `about:srcdoc` with an origin of `null`.
+Open the Apps tab and run `mcp_app_demo`. The widget renders identically to `mcp-app-http.json` — the difference is not visual. Inspect the inner iframe in devtools: on this server it is served from `http://127.0.0.1:6276/app-document/<id>` and `location.origin` is that real origin, where on `mcp-app-http.json` it is `about:srcdoc` with an origin of `null`. (The host is whatever the Inspector bound to — `127.0.0.1` by default, an *address* rather than the name `localhost`, for the reason `resolve-bind-host.ts` documents.)
 
 The spec makes `domain`'s format **host-dependent**, and the Inspector owns no domain infrastructure — so it reads any non-empty value as a *request* rather than an address, and answers with a real loopback origin of its own. See [MCP App dedicated origins](./clients/web/README.md#mcp-app-dedicated-origins-metauidomain) for the full contract, including what the one shared origin does and does not isolate, and how every failure falls back to the default render rather than blanking the app.
 
diff --git a/clients/web/README.md b/clients/web/README.md
index f6963294..5065ea17 100644
--- a/clients/web/README.md
+++ b/clients/web/README.md
@@ -160,7 +160,11 @@ Inspector owns no domain infrastructure — it cannot serve
 - The app document is served from there under an unguessable path, its
   per-app CSP delivered as a real response **header** (stronger than the
   `<meta>` the `srcdoc` path relies on) plus a `frame-ancestors` that admits
-  only the sandbox proxy.
+  only the two origins in its real ancestor chain — the sandbox proxy that
+  frames it, **and** the Inspector page that frames the proxy. Both are
+  required, not belt-and-braces: `frame-ancestors` is checked against every
+  ancestor, so omitting the Inspector's own origin blocks the frame outright
+  (see `appDocumentEmbedders`).
 - The inner iframe is granted `allow-same-origin` on this path **only** —
   that is what makes the origin real rather than opaque. It is not a
   weakening of #1565: the listener is on its own port, so the app is
diff --git a/clients/web/server/app-origin-controller.ts b/clients/web/server/app-origin-controller.ts
index f455542a..a13bfe84 100644
--- a/clients/web/server/app-origin-controller.ts
+++ b/clients/web/server/app-origin-controller.ts
@@ -273,8 +273,15 @@ export function createAppOriginController(
             console.error("App origin server error:", err);
           }
           // Degrade rather than reject: `publish` then returns null and the
-          // renderer keeps working on the default srcdoc path.
+          // renderer keeps working on the default srcdoc path. Clearing
+          // `origin` is what makes that true — `publish` gates on it, not on
+          // `server`, so an error arriving AFTER a successful listen would
+          // otherwise keep minting URLs on a dead listener and the browser
+          // would never take the promised fallback. Dropping the documents
+          // with it releases their memory, since nothing can fetch them now.
           server = null;
+          origin = null;
+          documents.clear();
           settle({ port: 0, url: "" });
         });
 
diff --git a/clients/web/server/sandbox-controller.ts b/clients/web/server/sandbox-controller.ts
index 148ceb62..042e8b3f 100644
--- a/clients/web/server/sandbox-controller.ts
+++ b/clients/web/server/sandbox-controller.ts
@@ -79,9 +79,11 @@ export function sandboxFrameAncestors(allowedOrigins?: string[]): string {
  * {@link LOOPBACK_FRAME_ANCESTORS} when nothing valid remains.
  *
  * Shared with the app-origin server (#2056), which restricts a published app
- * document to being framed by the sandbox proxy. Same grammar, same failure
- * mode — a directive whose only source is invalid degrades to `'none'` and
- * blocks the frame — so the two derive it here rather than each rolling one.
+ * document to being framed by the sandbox proxy and the Inspector page above
+ * it. Same grammar, same fallback — an all-invalid list yields the loopback
+ * family rather than an empty source list, since a `frame-ancestors` with no
+ * sources means `'none'` and would block the frame outright — so the two
+ * derive it here rather than each rolling one.
  */
 export function frameAncestorsDirective(origins?: string[]): string {
   const valid = (origins ?? []).filter((o) => CSP_HOST_SOURCE.test(o));
diff --git a/clients/web/src/App.test.tsx b/clients/web/src/App.test.tsx
index 2b638d79..b7f7a11f 100644
--- a/clients/web/src/App.test.tsx
+++ b/clients/web/src/App.test.tsx
@@ -391,6 +391,24 @@ vi.mock(
   },
 );
 
+// --- publishAppDocument spy (#2056) -----------------------------------------
+// The dedicated-origin publisher App hands both bridge factories. Mocked at the
+// module so a test can assert the wiring is live — the factory's own tests
+// inject the dep and cannot see App failing to supply it.
+const publishAppDocumentMock =
+  vi.fn<
+    (
+      doc: { html: string; csp?: string },
+      opts: { baseUrl: string; authToken?: string },
+    ) => Promise<string | null>
+  >();
+vi.mock("./lib/publishAppDocument", () => ({
+  publishAppDocument: (
+    doc: { html: string; csp?: string },
+    opts: { baseUrl: string; authToken?: string },
+  ) => publishAppDocumentMock(doc, opts),
+}));
+
 // --- InspectorView double ---------------------------------------------------
 // Surfaces each piece of session-scoped state under test and exposes buttons
 // that invoke the App's connect / call-tool / get-prompt / read-resource /
@@ -3463,4 +3481,40 @@ describe("App MCP App listed-resource metadata wiring (#2055)", () => {
       ).toBeUndefined();
     }
   });
+
+  it("hands BOTH bridge factories a working publishAppDocument (#2056)", async () => {
+    // Both call sites pass the same `publishDocument`, and the end-to-end smoke
+    // only covers the Apps-screen one — so without this the elicitation
+    // factory's `publishAppDocument` could be dropped and every test stays
+    // green while a domain-declaring elicitation app silently loses its real
+    // origin. Assert it is not merely present but actually reaches the lib.
+    publishAppDocumentMock.mockResolvedValue(
+      "http://127.0.0.1:6276/app-document/deadbeef",
+    );
+
+    renderWithMantine(<App />);
+
+    const appsFactory = () =>
+      appBridgeFactoryDeps.find((d) => !d.advertiseElicitation);
+    const elicitationFactory = () =>
+      appBridgeFactoryDeps.find((d) => d.advertiseElicitation === true);
+    await waitFor(() => {
+      expect(appsFactory()).toBeDefined();
+      expect(elicitationFactory()).toBeDefined();
+    });
+
+    for (const deps of [appsFactory(), elicitationFactory()]) {
+      publishAppDocumentMock.mockClear();
+      await expect(
+        deps?.publishAppDocument?.({
+          html: "<p>app</p>",
+          csp: "default-src 'none'",
+        }),
+      ).resolves.toBe("http://127.0.0.1:6276/app-document/deadbeef");
+      expect(publishAppDocumentMock).toHaveBeenCalledWith(
+        { html: "<p>app</p>", csp: "default-src 'none'" },
+        expect.objectContaining({ baseUrl: expect.any(String) }),
+      );
+    }
+  });
 });
diff --git a/clients/web/src/lib/publishAppDocument.test.ts b/clients/web/src/lib/publishAppDocument.test.ts
index 289cdfdb..1f435683 100644
--- a/clients/web/src/lib/publishAppDocument.test.ts
+++ b/clients/web/src/lib/publishAppDocument.test.ts
@@ -10,12 +10,16 @@
 import { describe, it, expect, vi } from "vitest";
 import { publishAppDocument } from "./publishAppDocument";
 
+/**
+ * A real `Response`, not a shaped literal. The platform implementation is
+ * available here, so building one keeps `ok`/`status`/`json()` honest rather
+ * than asserting a hand-written object is a Response.
+ */
 function jsonResponse(body: unknown, status = 200): Response {
-  return {
-    ok: status >= 200 && status < 300,
+  return new Response(JSON.stringify(body), {
     status,
-    json: async () => body,
-  } as unknown as Response;
+    headers: { "Content-Type": "application/json" },
+  });
 }
 
 describe("publishAppDocument", () => {
@@ -88,13 +92,11 @@ describe("publishAppDocument", () => {
   });
 
   it("resolves null when the response body is not JSON", async () => {
-    const fetchFn = vi.fn<typeof fetch>().mockResolvedValue({
-      ok: true,
-      status: 200,
-      json: async () => {
-        throw new Error("not json");
-      },
-    } as unknown as Response);
+    // A real 200 whose body is not JSON, so `json()` rejects for the reason
+    // the production path has to survive rather than because a stub threw.
+    const fetchFn = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(new Response("not json", { status: 200 }));
     await expect(
       publishAppDocument(
         { html: "<p>app</p>" },
diff --git a/clients/web/src/test/integration/mcp/remote/app-document-route.test.ts b/clients/web/src/test/integration/mcp/remote/app-document-route.test.ts
index d9939f38..d60a41c5 100644
--- a/clients/web/src/test/integration/mcp/remote/app-document-route.test.ts
+++ b/clients/web/src/test/integration/mcp/remote/app-document-route.test.ts
@@ -84,6 +84,20 @@ describe("createRemoteApp POST /api/app-document", () => {
     expect(res.status).toBe(400);
   });
 
+  it.each([
+    ["a JSON null body", "null"],
+    ["a JSON array body", "[1,2]"],
+  ])("rejects %s with 400 rather than a 500", async (_label, raw) => {
+    // Both parse cleanly, so the try/catch above sees nothing — destructuring
+    // them is what used to throw, outside it, turning a bad shape into a 500.
+    const publish = vi
+      .fn<(doc: { html: string; csp?: string }) => { url: string } | null>()
+      .mockReturnValue({ url: "http://x/y" });
+    const res = await appWith(publish).request(post(raw));
+    expect(res.status).toBe(400);
+    expect(publish).not.toHaveBeenCalled();
+  });
+
   it.each([
     ["missing html", {}],
     ["empty html", { html: "" }],
diff --git a/clients/web/src/test/integration/server/app-origin-controller.test.ts b/clients/web/src/test/integration/server/app-origin-controller.test.ts
index dced7e5e..1126b630 100644
--- a/clients/web/src/test/integration/server/app-origin-controller.test.ts
+++ b/clients/web/src/test/integration/server/app-origin-controller.test.ts
@@ -337,6 +337,58 @@ describe("createAppOriginController", () => {
     }
   });
 
+  it("stops minting URLs when the listener errors AFTER it bound", async () => {
+    // `publish` gates on `origin`, not on `server`. An error arriving once the
+    // listener is live must therefore clear `origin` too — otherwise the
+    // browser keeps being handed URLs on a dead port and never takes the
+    // srcdoc fallback the caller is promised.
+    vi.resetModules();
+    let emitter!: EventEmitter;
+    vi.doMock("node:http", async () => {
+      const actual =
+        await vi.importActual<typeof import("node:http")>("node:http");
+      return {
+        ...actual,
+        createServer: () => {
+          emitter = new EventEmitter();
+          return Object.assign(emitter, {
+            listen: (_p: number, _h: string, cb?: () => void) =>
+              setImmediate(() => cb?.()),
+            address: () => ({
+              address: "127.0.0.1",
+              family: "IPv4",
+              port: 6276,
+            }),
+            close: (cb?: () => void) => cb?.(),
+          });
+        },
+      };
+    });
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const mod = await import("../../../../server/app-origin-controller.js");
+      const c = mod.createAppOriginController({
+        port: 6276,
+        host: "127.0.0.1",
+      });
+      await c.start();
+      expect(c.getOrigin()).toBe("http://127.0.0.1:6276");
+      expect(c.publish({ html: "<p>x</p>" })).not.toBeNull();
+
+      emitter.emit(
+        "error",
+        Object.assign(new Error("boom"), { code: "EPIPE" }),
+      );
+
+      expect(c.getOrigin()).toBeNull();
+      expect(c.publish({ html: "<p>x</p>" })).toBeNull();
+    } finally {
+      errorSpy.mockRestore();
+      vi.doUnmock("node:http");
+      vi.resetModules();
+    }
+  });
+
   it("gives up after one retry when the dynamic fallback also fails", async () => {
     // Guards the `retriedDynamic` latch. A real `listen(0)` effectively always
     // succeeds, so a claimed port only ever produces ONE EADDRINUSE — under
diff --git a/clients/web/static/sandbox_proxy.html b/clients/web/static/sandbox_proxy.html
index ddd676a2..99d27f73 100644
--- a/clients/web/static/sandbox_proxy.html
+++ b/clients/web/static/sandbox_proxy.html
@@ -254,6 +254,14 @@
               // delivered as a real response header there (stronger than the
               // <meta> the srcdoc path relies on), so no wrapping applies here
               // — this proxy still never parses the untrusted bytes.
+              //
+              // Drop any `srcdoc` a previous render left behind first: it takes
+              // precedence over `src`, so a frame that had rendered an opaque
+              // document would keep showing it and never load this URL. Not
+              // reachable today (each render remounts the iframe, which reloads
+              // this document), but the cost of being wrong about that later is
+              // an app silently rendering the wrong bytes.
+              inner.removeAttribute("srcdoc");
               innerOrigin = srcUrl.origin;
               inner.src = srcUrl.href;
             } else if (typeof html === "string") {
@@ -265,6 +273,20 @@
               // boundary). Known trade-off: a small set of libraries (e.g.
               // CesiumJS Map) don't initialise correctly under srcdoc — that
               // is accepted in exchange for the isolation guarantee.
+              //
+              // Restore the opaque-origin posture first. A frame that
+              // previously took the dedicated-origin path still carries
+              // `allow-same-origin`, and `innerOrigin` still names that origin;
+              // assigning `srcdoc` under those would put the untrusted document
+              // in THIS proxy's realm — the exact escape the double-iframe
+              // model exists to prevent. The sandbox attribute is read at
+              // navigation time and assigning `srcdoc` is the navigation, so
+              // stripping it here takes effect for the document being loaded.
+              const fallbackTokens = (inner.getAttribute("sandbox") || "")
+                .split(/\s+/)
+                .filter((t) => t && t.toLowerCase() !== "allow-same-origin");
+              inner.setAttribute("sandbox", fallbackTokens.join(" "));
+              innerOrigin = "null";
               inner.srcdoc = html;
             }
           } else {
diff --git a/core/mcp/remote/node/server.ts b/core/mcp/remote/node/server.ts
index 1541d646..6b2b237f 100644
--- a/core/mcp/remote/node/server.ts
+++ b/core/mcp/remote/node/server.ts
@@ -749,13 +749,24 @@ export function createRemoteApp(
     if (!publish) {
       return c.json({ error: "App-origin hosting is not available" }, 503);
     }
-    let body: { html?: unknown; csp?: unknown };
+    let parsed: unknown;
     try {
-      body = (await c.req.json()) as { html?: unknown; csp?: unknown };
+      parsed = await c.req.json();
     } catch {
       return c.json({ error: "Invalid JSON body" }, 400);
     }
-    const { html, csp } = body;
+    // `null` and `[1,2]` are both valid JSON, so `c.req.json()` resolving is
+    // not proof there is an object to destructure — and destructuring `null`
+    // here would throw OUTSIDE the try above, turning a malformed body into a
+    // 500 instead of the 400 every other bad shape gets.
+    if (
+      parsed === null ||
+      typeof parsed !== "object" ||
+      Array.isArray(parsed)
+    ) {
+      return c.json({ error: "Invalid JSON body" }, 400);
+    }
+    const { html, csp } = parsed as { html?: unknown; csp?: unknown };
     if (typeof html !== "string" || html === "") {
       return c.json({ error: "Missing html" }, 400);
     }

From fafc8367b8a61c589faa1c0746e2e3d8537b4098 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Mon, 24 Aug 2026 00:07:15 -0400
Subject: [PATCH 10/14] fix(web): move the app origin off 6276, bound the
 publish route
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copilot review round 2 on #2100, plus a collision the review did not find.

The default app-origin port was 6276 — which is already
RUNNER_OAUTH_CALLBACK_DEFAULT_PORT, the CLI/TUI loopback OAuth callback.
That port is fixed precisely so an OAuth app can pre-register
http://127.0.0.1:6276/oauth/callback, which makes it the one listener here
that cannot move when something takes it first. A running --web would hold
it and break a later --cli/--tui OAuth flow at its registered redirect URI,
and docs/mcp-app-review.md has those two running side by side. This
listener has a documented dynamic fallback, so this listener yields: the
default is now 6278 (6277 skipped — v1's retired proxy port, which the
migration guide tells people to stop forwarding). A test asserts the two
defaults stay distinct.

Review comments:

- POST /api/app-document now applies hono's bodyLimit BEFORE parsing. The
  8MiB check ran after c.req.json() had buffered and parsed the whole
  request, and bounded only `html` — so bulk in `csp`, or in keys the route
  never reads, was fully materialized before the 413.
- `csp` is validated as an HTTP header value and length-bounded. The
  controller hands it to res.writeHead() verbatim, where Node throws
  ERR_INVALID_CHAR synchronously — inside the handler for a later,
  unrelated request, outside this route's error handling.
- The app-origin port now propagates everywhere the other two do: the CLI
  --print-handoff port-forward command (and its test), the Dockerfile's ENV
  and EXPOSE, and the remote-review SSH recipe in docs/mcp-app-review.md.
  Without it an app declaring _meta.ui.domain is unreachable through every
  documented remote workflow.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 AGENTS.md                                     |   2 +-
 Dockerfile                                    |   9 +-
 README.md                                     |   6 +-
 clients/cli/__tests__/stored-auth.test.ts     |   4 +
 clients/cli/src/cli.ts                        |   7 +-
 clients/web/README.md                         |   9 +-
 clients/web/server/app-origin-controller.ts   |  21 ++-
 clients/web/src/App.test.tsx                  |   4 +-
 .../createAppBridgeFactory.test.ts            |   8 +-
 .../web/src/lib/publishAppDocument.test.ts    |   4 +-
 .../mcp/remote/app-document-route.test.ts     |  46 ++++++-
 .../server/app-origin-controller.test.ts      |  22 ++-
 .../server/web-server-config.test.ts          |   4 +-
 core/mcp/remote/node/server.ts                | 129 ++++++++++++------
 docs/mcp-app-review.md                        |   9 +-
 15 files changed, 211 insertions(+), 73 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 0281b69a..2cad2e5d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,7 +25,7 @@ v2/main/
 │   │                               #     HOST-DEPENDENT and the Inspector owns no domain
 │   │                               #     infrastructure, so it treats any non-empty value as a
 │   │                               #     REQUEST, not an address, and answers with a real loopback
-│   │                               #     origin on its own port (MCP_APP_ORIGIN_PORT, default 6276).
+│   │                               #     origin on its own port (MCP_APP_ORIGIN_PORT, default 6278).
 │   │                               #     ONE SHARED origin, path-keyed per document — a real,
 │   │                               #     allowlistable origin without a port or DNS name per app,
 │   │                               #     and therefore NOT a per-app isolation boundary (two such
diff --git a/Dockerfile b/Dockerfile
index 24455398..84f40d29 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -32,11 +32,14 @@ ENV HOST=0.0.0.0 \
     DANGEROUSLY_BIND_ALL_INTERFACES=true \
     CLIENT_PORT=6274 \
     MCP_SANDBOX_PORT=6275 \
+    MCP_APP_ORIGIN_PORT=6278 \
     MCP_AUTO_OPEN_ENABLED=false
-# 6275 is the MCP Apps sandbox, a second listener the browser reaches directly.
-# It is only needed for the Apps tab, so it is EXPOSEd but publishing it is
+# 6275 is the MCP Apps sandbox and 6278 the dedicated app origin (#2056) — two
+# further listeners the browser reaches DIRECTLY, so neither works through the
+# 6274 publish alone. Both are only needed for the Apps tab (6278 only for an
+# App declaring `_meta.ui.domain`), so they are EXPOSEd but publishing them is
 # optional — see the Docker section of the root README.
-EXPOSE 6274 6275
+EXPOSE 6274 6275 6278
 
 # Run as the non-root `node` user the base image ships. The inspector resolves
 # its runtime-state dir (default catalog, OAuth token storage) from `HOME`
diff --git a/README.md b/README.md
index d9fce752..ce97d1cd 100644
--- a/README.md
+++ b/README.md
@@ -172,7 +172,7 @@ For the scripted version of the same flow (`--app-info` probe → deep link →
 
 That field is how a server asks its host for a stable, dedicated origin. Without one, an App renders into a `srcdoc` frame sandboxed without `allow-same-origin`, so its document has an *opaque* origin and every request it makes carries `Origin: null` — which no CORS policy, OAuth callback, or API-key allowlist can admit ([#2056](https://github.com/modelcontextprotocol/inspector/issues/2056)).
 
-Open the Apps tab and run `mcp_app_demo`. The widget renders identically to `mcp-app-http.json` — the difference is not visual. Inspect the inner iframe in devtools: on this server it is served from `http://127.0.0.1:6276/app-document/<id>` and `location.origin` is that real origin, where on `mcp-app-http.json` it is `about:srcdoc` with an origin of `null`. (The host is whatever the Inspector bound to — `127.0.0.1` by default, an *address* rather than the name `localhost`, for the reason `resolve-bind-host.ts` documents.)
+Open the Apps tab and run `mcp_app_demo`. The widget renders identically to `mcp-app-http.json` — the difference is not visual. Inspect the inner iframe in devtools: on this server it is served from `http://127.0.0.1:6278/app-document/<id>` and `location.origin` is that real origin, where on `mcp-app-http.json` it is `about:srcdoc` with an origin of `null`. (The host is whatever the Inspector bound to — `127.0.0.1` by default, an *address* rather than the name `localhost`, for the reason `resolve-bind-host.ts` documents.)
 
 The spec makes `domain`'s format **host-dependent**, and the Inspector owns no domain infrastructure — so it reads any non-empty value as a *request* rather than an address, and answers with a real loopback origin of its own. See [MCP App dedicated origins](./clients/web/README.md#mcp-app-dedicated-origins-metauidomain) for the full contract, including what the one shared origin does and does not isolate, and how every failure falls back to the default render rather than blanking the app.
 
@@ -477,10 +477,10 @@ docker run --rm -p 127.0.0.1:6274:6274 -p 127.0.0.1:6275:6275 \
   ghcr.io/modelcontextprotocol/inspector
 ```
 
-**And `6276` if your app declares `_meta.ui.domain`.** That is the spec field a server uses to ask its host for a stable, dedicated origin — without one the app runs at an opaque origin and its requests carry `Origin: null`, which no CORS / OAuth-callback / API-key allowlist can admit. The Inspector answers the request with a real loopback origin on a third listener, `MCP_APP_ORIGIN_PORT` (default `6276`); apps that declare no `domain` never touch it. An app that declares one and can't reach it still renders — at an opaque origin, with a console warning. See [MCP App dedicated origins](./clients/web/README.md#mcp-app-dedicated-origins-metauidomain) for the host-specific contract and its isolation trade-offs.
+**And `6278` if your app declares `_meta.ui.domain`.** That is the spec field a server uses to ask its host for a stable, dedicated origin — without one the app runs at an opaque origin and its requests carry `Origin: null`, which no CORS / OAuth-callback / API-key allowlist can admit. The Inspector answers the request with a real loopback origin on a third listener, `MCP_APP_ORIGIN_PORT` (default `6278`); apps that declare no `domain` never touch it. An app that declares one and can't reach it still renders — at an opaque origin, with a console warning. See [MCP App dedicated origins](./clients/web/README.md#mcp-app-dedicated-origins-metauidomain) for the host-specific contract and its isolation trade-offs.
 
 ```bash
-docker run --rm -p 127.0.0.1:6274:6274 -p 127.0.0.1:6275:6275 -p 127.0.0.1:6276:6276 \
+docker run --rm -p 127.0.0.1:6274:6274 -p 127.0.0.1:6275:6275 -p 127.0.0.1:6278:6278 \
   ghcr.io/modelcontextprotocol/inspector
 ```
 
diff --git a/clients/cli/__tests__/stored-auth.test.ts b/clients/cli/__tests__/stored-auth.test.ts
index 4a45ec33..1b9b5768 100644
--- a/clients/cli/__tests__/stored-auth.test.ts
+++ b/clients/cli/__tests__/stored-auth.test.ts
@@ -554,6 +554,7 @@ describe("--print-handoff", () => {
           MCP_INSPECTOR_API_TOKEN: "tok123",
           CLIENT_PORT: "16274",
           MCP_SANDBOX_PORT: "16275",
+          MCP_APP_ORIGIN_PORT: "16278",
           MCP_STORAGE_DIR: "/tmp/inspector-storage",
           MCP_INSPECTOR_OAUTH_STATE_PATH: "",
         },
@@ -574,6 +575,9 @@ describe("--print-handoff", () => {
     expect(out.deepLink).toContain("transport=http");
     expect(out.portForwardCmd).toContain("--tcp 16274:16274");
     expect(out.portForwardCmd).toContain("--tcp 16275:16275");
+    // The dedicated app origin (#2056) forwards with the other two — an app
+    // declaring `_meta.ui.domain` is unreachable without it.
+    expect(out.portForwardCmd).toContain("--tcp 16278:16278");
     expect(out.oauthStatePath).toBe(
       join("/tmp/inspector-storage", "oauth.json"),
     );
diff --git a/clients/cli/src/cli.ts b/clients/cli/src/cli.ts
index 6f2f894e..60e5a3d8 100644
--- a/clients/cli/src/cli.ts
+++ b/clients/cli/src/cli.ts
@@ -452,6 +452,11 @@ function buildHandoff(
     : canonicalUrlHost(host);
   const clientPort = process.env.CLIENT_PORT || "6274";
   const sandboxPort = process.env.MCP_SANDBOX_PORT || "6275";
+  // The dedicated app origin (#2056). Forwarded alongside the other two: an App
+  // whose UI resource declares `_meta.ui.domain` is served from this port and
+  // the browser reaches it DIRECTLY, so a handoff that forwards only 6274/6275
+  // renders that app from an unreachable origin.
+  const appOriginPort = process.env.MCP_APP_ORIGIN_PORT || "6278";
   // Treat an empty MCP_INSPECTOR_API_TOKEN the same as unset — an empty token
   // can't satisfy the deep-link autoConnect gate.
   const apiToken = process.env.MCP_INSPECTOR_API_TOKEN || undefined;
@@ -469,7 +474,7 @@ function buildHandoff(
   return {
     serverUrl: normalizedUrl,
     deepLink: `http://${linkHost}:${clientPort}/?${params.toString()}`,
-    portForwardCmd: `coder port-forward <workspace> --tcp ${clientPort}:${clientPort} --tcp ${sandboxPort}:${sandboxPort}`,
+    portForwardCmd: `coder port-forward <workspace> --tcp ${clientPort}:${clientPort} --tcp ${sandboxPort}:${sandboxPort} --tcp ${appOriginPort}:${appOriginPort}`,
     oauthStatePath: statePath,
     apiToken: apiToken ?? null,
     note:
diff --git a/clients/web/README.md b/clients/web/README.md
index 5065ea17..63023953 100644
--- a/clients/web/README.md
+++ b/clients/web/README.md
@@ -155,8 +155,11 @@ Inspector owns no domain infrastructure — it cannot serve
   not parsed, matched, or reserved — declare whatever your production host
   expects.
 - The Inspector answers with a real HTTP origin on loopback:
-  `http://<host>:<MCP_APP_ORIGIN_PORT>`, default **`6276`** (beside the web
-  port `6274` and the sandbox port `6275`, so the three forward together).
+  `http://<host>:<MCP_APP_ORIGIN_PORT>`, default **`6278`** — in the same
+  `627x` family as the web port `6274` and the sandbox port `6275`, so the
+  three forward together. It is **not** `6276`: that is the fixed loopback
+  OAuth callback the CLI and TUI listen on, which OAuth apps pre-register and
+  which therefore cannot move. `6277` is skipped as v1's retired proxy port.
 - The app document is served from there under an unguessable path, its
   per-app CSP delivered as a real response **header** (stronger than the
   `<meta>` the `srcdoc` path relies on) plus a `frame-ancestors` that admits
@@ -186,7 +189,7 @@ default (opaque-origin) way and logs a console warning naming `_meta.ui.domain`.
 Losing the real origin degrades what the app can reach; losing the app itself
 would be worse.
 
-**Forward `6276` too** if you need this off loopback (a container, a tunnel).
+**Forward `6278` too** if you need this off loopback (a container, a tunnel).
 As with the sandbox port, a taken port falls back to an OS-assigned one with a
 loud warning — the app still renders, but the origin an app's backend was told
 to allowlist is then wrong, which is what the warning tells you.
diff --git a/clients/web/server/app-origin-controller.ts b/clients/web/server/app-origin-controller.ts
index a13bfe84..a9dc61e9 100644
--- a/clients/web/server/app-origin-controller.ts
+++ b/clients/web/server/app-origin-controller.ts
@@ -57,11 +57,22 @@ import { frameAncestorsDirective } from "./sandbox-controller.js";
 /**
  * The default app-origin listen port — **fixed**, for the same reason
  * `DEFAULT_SANDBOX_PORT` is: a port that changes per run can never be named in
- * a dev container's `forwardPorts`, a `docker run -p`, or an SSH tunnel. `6276`
- * sits next to the web (`6274`) and sandbox (`6275`) ports so the three forward
- * together.
+ * a dev container's `forwardPorts`, a `docker run -p`, or an SSH tunnel.
+ *
+ * **Not 6276, and not 6277.** `6276` is already taken, by the fixed loopback
+ * OAuth callback the CLI and TUI listen on
+ * (`RUNNER_OAUTH_CALLBACK_DEFAULT_PORT`) — fixed precisely so an OAuth app can
+ * pre-register `http://127.0.0.1:6276/oauth/callback`, which means it is the
+ * one port here that CANNOT move when something else takes it first. Binding it
+ * would let a running `--web` (started at login, holding the port) break a
+ * later `--cli`/`--tui` OAuth flow at its registered redirect URI — and the
+ * handoff recipe in `docs/mcp-app-review.md` has those two running side by
+ * side. Of the two listeners this listener is the one with a documented
+ * dynamic fallback, so it is the one that yields. `6277` is skipped because it
+ * was v1's MCP proxy port, which the migration guide tells people to stop
+ * forwarding; reusing it would make that instruction wrong.
  */
-export const DEFAULT_APP_ORIGIN_PORT = 6276;
+export const DEFAULT_APP_ORIGIN_PORT = 6278;
 
 /** Documents kept at once. Oldest is evicted past this; see {@link publish}. */
 const MAX_DOCUMENTS = 32;
@@ -142,7 +153,7 @@ export interface AppOriginController {
 /**
  * A usable listen port from a raw env value, or `undefined` if it isn't a plain
  * integer in `0`–`65535`. Mirrors `sandbox-controller`'s parser: `^\d+$` rejects
- * `parseInt`'s partial parses (`6276abc`) and the bound keeps an out-of-range
+ * `parseInt`'s partial parses (`6278abc`) and the bound keeps an out-of-range
  * value from reaching `server.listen`, which throws synchronously.
  */
 function parseListenPort(raw: string | undefined): number | undefined {
diff --git a/clients/web/src/App.test.tsx b/clients/web/src/App.test.tsx
index b7f7a11f..0d0f7007 100644
--- a/clients/web/src/App.test.tsx
+++ b/clients/web/src/App.test.tsx
@@ -3489,7 +3489,7 @@ describe("App MCP App listed-resource metadata wiring (#2055)", () => {
     // green while a domain-declaring elicitation app silently loses its real
     // origin. Assert it is not merely present but actually reaches the lib.
     publishAppDocumentMock.mockResolvedValue(
-      "http://127.0.0.1:6276/app-document/deadbeef",
+      "http://127.0.0.1:6278/app-document/deadbeef",
     );
 
     renderWithMantine(<App />);
@@ -3510,7 +3510,7 @@ describe("App MCP App listed-resource metadata wiring (#2055)", () => {
           html: "<p>app</p>",
           csp: "default-src 'none'",
         }),
-      ).resolves.toBe("http://127.0.0.1:6276/app-document/deadbeef");
+      ).resolves.toBe("http://127.0.0.1:6278/app-document/deadbeef");
       expect(publishAppDocumentMock).toHaveBeenCalledWith(
         { html: "<p>app</p>", csp: "default-src 'none'" },
         expect.objectContaining({ baseUrl: expect.any(String) }),
diff --git a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
index 742fabf1..55d624dc 100644
--- a/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
+++ b/clients/web/src/components/elements/AppRenderer/createAppBridgeFactory.test.ts
@@ -498,7 +498,7 @@ describe("createAppBridgeFactory", () => {
       );
       const publishAppDocument = vi
         .fn<(doc: { html: string; csp?: string }) => Promise<string | null>>()
-        .mockResolvedValue("http://localhost:6276/app-document/abc");
+        .mockResolvedValue("http://localhost:6278/app-document/abc");
       const factory = createAppBridgeFactory({
         getClient: () => fakeClient,
         readResource,
@@ -517,7 +517,7 @@ describe("createAppBridgeFactory", () => {
 
       const call = bridgeInstances[0].sendSandboxResourceReady.mock
         .calls[0][0] as { html: string; src?: string };
-      expect(call.src).toBe("http://localhost:6276/app-document/abc");
+      expect(call.src).toBe("http://localhost:6278/app-document/abc");
       // `html` still rides along: a proxy that ignores `src` renders the app
       // rather than a blank frame.
       expect(call.html).toBe(published.html);
@@ -530,7 +530,7 @@ describe("createAppBridgeFactory", () => {
     ])("does not take the dedicated path for %s", async (_label, domain) => {
       const publishAppDocument = vi
         .fn<(doc: { html: string; csp?: string }) => Promise<string | null>>()
-        .mockResolvedValue("http://localhost:6276/app-document/abc");
+        .mockResolvedValue("http://localhost:6278/app-document/abc");
       const factory = createAppBridgeFactory({
         getClient: () => fakeClient,
         readResource: vi
@@ -550,7 +550,7 @@ describe("createAppBridgeFactory", () => {
     it("never publishes a resource that declares no domain", async () => {
       const publishAppDocument = vi
         .fn<(doc: { html: string; csp?: string }) => Promise<string | null>>()
-        .mockResolvedValue("http://localhost:6276/app-document/abc");
+        .mockResolvedValue("http://localhost:6278/app-document/abc");
       const factory = createAppBridgeFactory({
         getClient: () => fakeClient,
         readResource: vi.fn().mockResolvedValue(uiResource("<h1>x</h1>")),
diff --git a/clients/web/src/lib/publishAppDocument.test.ts b/clients/web/src/lib/publishAppDocument.test.ts
index 1f435683..f9fd0158 100644
--- a/clients/web/src/lib/publishAppDocument.test.ts
+++ b/clients/web/src/lib/publishAppDocument.test.ts
@@ -27,13 +27,13 @@ describe("publishAppDocument", () => {
     const fetchFn = vi
       .fn<typeof fetch>()
       .mockResolvedValue(
-        jsonResponse({ url: "http://localhost:6276/app-document/abc" }),
+        jsonResponse({ url: "http://localhost:6278/app-document/abc" }),
       );
     const url = await publishAppDocument(
       { html: "<p>app</p>", csp: "default-src 'none'" },
       { baseUrl: "http://localhost:6274", authToken: "tok", fetchFn },
     );
-    expect(url).toBe("http://localhost:6276/app-document/abc");
+    expect(url).toBe("http://localhost:6278/app-document/abc");
     expect(fetchFn).toHaveBeenCalledWith(
       "http://localhost:6274/api/app-document",
       expect.objectContaining({
diff --git a/clients/web/src/test/integration/mcp/remote/app-document-route.test.ts b/clients/web/src/test/integration/mcp/remote/app-document-route.test.ts
index d60a41c5..ecd556a7 100644
--- a/clients/web/src/test/integration/mcp/remote/app-document-route.test.ts
+++ b/clients/web/src/test/integration/mcp/remote/app-document-route.test.ts
@@ -37,13 +37,13 @@ describe("createRemoteApp POST /api/app-document", () => {
   it("publishes the document and returns the URL", async () => {
     const publish = vi
       .fn<(doc: { html: string; csp?: string }) => { url: string } | null>()
-      .mockReturnValue({ url: "http://localhost:6276/app-document/abc" });
+      .mockReturnValue({ url: "http://localhost:6278/app-document/abc" });
     const res = await appWith(publish).request(
       post({ html: "<h1>hi</h1>", csp: "default-src 'none'" }),
     );
     expect(res.status).toBe(200);
     await expect(res.json()).resolves.toEqual({
-      url: "http://localhost:6276/app-document/abc",
+      url: "http://localhost:6278/app-document/abc",
     });
     expect(publish).toHaveBeenCalledWith({
       html: "<h1>hi</h1>",
@@ -54,7 +54,7 @@ describe("createRemoteApp POST /api/app-document", () => {
   it("accepts a document with no csp", async () => {
     const publish = vi
       .fn<(doc: { html: string; csp?: string }) => { url: string } | null>()
-      .mockReturnValue({ url: "http://localhost:6276/app-document/abc" });
+      .mockReturnValue({ url: "http://localhost:6278/app-document/abc" });
     const res = await appWith(publish).request(post({ html: "<h1>hi</h1>" }));
     expect(res.status).toBe(200);
     expect(publish).toHaveBeenCalledWith({
@@ -112,6 +112,46 @@ describe("createRemoteApp POST /api/app-document", () => {
     expect(publish).not.toHaveBeenCalled();
   });
 
+  it.each([
+    ["a CR/LF-carrying csp", "default-src 'none'\r\nX-Evil: 1"],
+    ["a NUL-carrying csp", "default-src 'none'\u0000"],
+  ])("rejects %s with 400", async (_label, csp) => {
+    // The controller hands `csp` to `res.writeHead()` verbatim. Node throws
+    // ERR_INVALID_CHAR there SYNCHRONOUSLY, inside the handler for a later,
+    // unrelated request — so accepting one here turns a bad publish into a
+    // thrown listener rather than a 400 anyone can see.
+    const publish = vi
+      .fn<(doc: { html: string; csp?: string }) => { url: string } | null>()
+      .mockReturnValue({ url: "http://x/y" });
+    const res = await appWith(publish).request(post({ html: "<p>x</p>", csp }));
+    expect(res.status).toBe(400);
+    expect(publish).not.toHaveBeenCalled();
+  });
+
+  it("rejects an oversized csp with 413 — it is retained per document", async () => {
+    const publish = vi
+      .fn<(doc: { html: string; csp?: string }) => { url: string } | null>()
+      .mockReturnValue({ url: "http://x/y" });
+    const res = await appWith(publish).request(
+      post({ html: "<p>x</p>", csp: "a".repeat(8 * 1024 + 1) }),
+    );
+    expect(res.status).toBe(413);
+    expect(publish).not.toHaveBeenCalled();
+  });
+
+  it("rejects an oversized BODY before parsing it", async () => {
+    // Distinct from the document check below, which only runs once the whole
+    // request has been buffered and parsed — and only bounds `html`.
+    const publish = vi
+      .fn<(doc: { html: string; csp?: string }) => { url: string } | null>()
+      .mockReturnValue({ url: "http://x/y" });
+    const res = await appWith(publish).request(
+      post(`{"junk":"${"x".repeat(24 * 1024 * 1024 + 1024)}"}`),
+    );
+    expect(res.status).toBe(413);
+    expect(publish).not.toHaveBeenCalled();
+  });
+
   it("rejects an oversized document with 413 rather than pinning it in memory", async () => {
     const publish = vi
       .fn<(doc: { html: string; csp?: string }) => { url: string } | null>()
diff --git a/clients/web/src/test/integration/server/app-origin-controller.test.ts b/clients/web/src/test/integration/server/app-origin-controller.test.ts
index 1126b630..7e9e66fa 100644
--- a/clients/web/src/test/integration/server/app-origin-controller.test.ts
+++ b/clients/web/src/test/integration/server/app-origin-controller.test.ts
@@ -21,6 +21,7 @@ import {
   resolveAppOriginPort,
   appDocumentEmbedders,
 } from "../../../../server/app-origin-controller.js";
+import { RUNNER_OAUTH_CALLBACK_DEFAULT_PORT } from "@inspector/core/auth/node/runner-oauth-callback.js";
 
 describe("resolveAppOriginPort", () => {
   const saved = process.env.MCP_APP_ORIGIN_PORT;
@@ -34,6 +35,19 @@ describe("resolveAppOriginPort", () => {
     expect(resolveAppOriginPort()).toBe(DEFAULT_APP_ORIGIN_PORT);
   });
 
+  it("does not default to the runners' fixed OAuth callback port", () => {
+    // Both listeners are fixed-by-default and both live in the 627x family, so
+    // the next free number is the obvious pick for each — which is how they
+    // collided. This one can move (it warns and retries on a dynamic port);
+    // the OAuth callback cannot, because apps pre-register
+    // `http://127.0.0.1:<that port>/oauth/callback`. A `--web` holding the
+    // port would therefore break a later `--cli`/`--tui` OAuth flow, and the
+    // handoff recipe runs those side by side.
+    expect(DEFAULT_APP_ORIGIN_PORT).not.toBe(
+      RUNNER_OAUTH_CALLBACK_DEFAULT_PORT,
+    );
+  });
+
   it("honors a valid MCP_APP_ORIGIN_PORT, including an explicit 0", () => {
     process.env.MCP_APP_ORIGIN_PORT = "9200";
     expect(resolveAppOriginPort()).toBe(9200);
@@ -41,7 +55,7 @@ describe("resolveAppOriginPort", () => {
     expect(resolveAppOriginPort()).toBe(0);
   });
 
-  it.each(["6276abc", "70000", "-1", "nope", "  "])(
+  it.each(["6278abc", "70000", "-1", "nope", "  "])(
     "warns and falls back for an invalid value %j",
     (value) => {
       const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
@@ -357,7 +371,7 @@ describe("createAppOriginController", () => {
             address: () => ({
               address: "127.0.0.1",
               family: "IPv4",
-              port: 6276,
+              port: 6278,
             }),
             close: (cb?: () => void) => cb?.(),
           });
@@ -368,11 +382,11 @@ describe("createAppOriginController", () => {
     try {
       const mod = await import("../../../../server/app-origin-controller.js");
       const c = mod.createAppOriginController({
-        port: 6276,
+        port: 6278,
         host: "127.0.0.1",
       });
       await c.start();
-      expect(c.getOrigin()).toBe("http://127.0.0.1:6276");
+      expect(c.getOrigin()).toBe("http://127.0.0.1:6278");
       expect(c.publish({ html: "<p>x</p>" })).not.toBeNull();
 
       emitter.emit(
diff --git a/clients/web/src/test/integration/server/web-server-config.test.ts b/clients/web/src/test/integration/server/web-server-config.test.ts
index dec8406e..ce345d4a 100644
--- a/clients/web/src/test/integration/server/web-server-config.test.ts
+++ b/clients/web/src/test/integration/server/web-server-config.test.ts
@@ -303,13 +303,13 @@ describe("buildWebServerConfigFromEnv", () => {
     expect(buildWebServerConfigFromEnv().sandboxPort).toBe(9100);
   });
 
-  it("resolves appOriginPort from MCP_APP_ORIGIN_PORT, defaulting to 6276", () => {
+  it("resolves appOriginPort from MCP_APP_ORIGIN_PORT, defaulting to 6278", () => {
     // The dedicated app origin (#2056). Deliberately NOT sharing the sandbox's
     // SERVER_PORT fallback: it is a different listener and must be pinnable
     // (and forwardable) on its own.
     delete process.env.MCP_APP_ORIGIN_PORT;
     process.env.SERVER_PORT = "9100";
-    expect(buildWebServerConfigFromEnv().appOriginPort).toBe(6276);
+    expect(buildWebServerConfigFromEnv().appOriginPort).toBe(6278);
     process.env.MCP_APP_ORIGIN_PORT = "9300";
     expect(buildWebServerConfigFromEnv().appOriginPort).toBe(9300);
   });
diff --git a/core/mcp/remote/node/server.ts b/core/mcp/remote/node/server.ts
index 6b2b237f..75d8d9c4 100644
--- a/core/mcp/remote/node/server.ts
+++ b/core/mcp/remote/node/server.ts
@@ -24,6 +24,7 @@ import type { LogEvent } from "pino";
 import { Hono } from "hono";
 import type { Context, Env, Next } from "hono";
 import { streamSSE } from "hono/streaming";
+import { bodyLimit } from "hono/body-limit";
 import { watch as chokidarWatch, type FSWatcher } from "chokidar";
 import { createTransportNode } from "../../node/transport.js";
 import { createProxyFetch } from "../../node/proxyFetch.js";
@@ -306,6 +307,41 @@ export interface RemoteServerOptions {
  */
 const MAX_APP_DOCUMENT_CHARS = 8 * 1024 * 1024;
 
+/**
+ * Upper bound on the request BODY, in bytes, enforced by `bodyLimit` *before*
+ * anything is parsed. {@link MAX_APP_DOCUMENT_CHARS} alone is not enough: it is
+ * checked after `c.req.json()` has already buffered and parsed the whole
+ * request, so an unbounded body — or one whose bulk sits in `csp` or in keys
+ * the route never reads — is fully materialized in memory before being
+ * rejected. Generous relative to the document bound because JSON escaping
+ * inflates the payload (`<` stays one byte, but a `"` or a newline becomes
+ * two, and non-BMP text more), so this must not reject a document the char
+ * check would accept.
+ */
+const MAX_APP_DOCUMENT_BODY_BYTES = 24 * 1024 * 1024;
+
+/**
+ * Upper bound on the per-app CSP policy string. Unlike the document, this is
+ * retained for the life of the published entry, and a real policy is a few
+ * hundred characters — an app pushing more is not describing sources.
+ */
+const MAX_APP_CSP_CHARS = 8 * 1024;
+
+/**
+ * Whether a string is safe to emit as an HTTP header VALUE.
+ *
+ * The published `csp` is handed to `res.writeHead()` verbatim by the app-origin
+ * controller. Node validates header values there and throws
+ * `ERR_INVALID_CHAR` **synchronously inside the request handler** — outside
+ * this route's error handling, on a request this route is not even part of —
+ * so a CR/LF or NUL accepted here surfaces later as a thrown listener rather
+ * than a 400. Restrict to tab plus printable ASCII, which is stricter than RFC
+ * 9110 field-value grammar and is all a CSP policy needs.
+ */
+function isHeaderSafeValue(value: string): boolean {
+  return !/[^\t\x20-\x7e]/.test(value);
+}
+
 export interface CreateRemoteAppResult {
   /** The Hono app */
   app: Hono;
@@ -744,44 +780,61 @@ export function createRemoteApp(
    * listener on its own port, which is what makes the app's origin real
    * instead of opaque.
    */
-  app.post("/api/app-document", async (c) => {
-    const publish = options.publishAppDocument;
-    if (!publish) {
-      return c.json({ error: "App-origin hosting is not available" }, 503);
-    }
-    let parsed: unknown;
-    try {
-      parsed = await c.req.json();
-    } catch {
-      return c.json({ error: "Invalid JSON body" }, 400);
-    }
-    // `null` and `[1,2]` are both valid JSON, so `c.req.json()` resolving is
-    // not proof there is an object to destructure — and destructuring `null`
-    // here would throw OUTSIDE the try above, turning a malformed body into a
-    // 500 instead of the 400 every other bad shape gets.
-    if (
-      parsed === null ||
-      typeof parsed !== "object" ||
-      Array.isArray(parsed)
-    ) {
-      return c.json({ error: "Invalid JSON body" }, 400);
-    }
-    const { html, csp } = parsed as { html?: unknown; csp?: unknown };
-    if (typeof html !== "string" || html === "") {
-      return c.json({ error: "Missing html" }, 400);
-    }
-    if (csp !== undefined && typeof csp !== "string") {
-      return c.json({ error: "csp must be a string" }, 400);
-    }
-    if (html.length > MAX_APP_DOCUMENT_CHARS) {
-      return c.json({ error: "Document too large" }, 413);
-    }
-    const published = publish({ html, csp });
-    if (!published) {
-      return c.json({ error: "App-origin hosting is not available" }, 503);
-    }
-    return c.json(published);
-  });
+  app.post(
+    "/api/app-document",
+    // Before the parse, not after: see MAX_APP_DOCUMENT_BODY_BYTES.
+    bodyLimit({
+      maxSize: MAX_APP_DOCUMENT_BODY_BYTES,
+      onError: (c) => c.json({ error: "Document too large" }, 413),
+    }),
+    async (c) => {
+      const publish = options.publishAppDocument;
+      if (!publish) {
+        return c.json({ error: "App-origin hosting is not available" }, 503);
+      }
+      let parsed: unknown;
+      try {
+        parsed = await c.req.json();
+      } catch {
+        return c.json({ error: "Invalid JSON body" }, 400);
+      }
+      // `null` and `[1,2]` are both valid JSON, so `c.req.json()` resolving is
+      // not proof there is an object to destructure — and destructuring `null`
+      // here would throw OUTSIDE the try above, turning a malformed body into a
+      // 500 instead of the 400 every other bad shape gets.
+      if (
+        parsed === null ||
+        typeof parsed !== "object" ||
+        Array.isArray(parsed)
+      ) {
+        return c.json({ error: "Invalid JSON body" }, 400);
+      }
+      const { html, csp } = parsed as { html?: unknown; csp?: unknown };
+      if (typeof html !== "string" || html === "") {
+        return c.json({ error: "Missing html" }, 400);
+      }
+      if (csp !== undefined && typeof csp !== "string") {
+        return c.json({ error: "csp must be a string" }, 400);
+      }
+      if (csp !== undefined && !isHeaderSafeValue(csp)) {
+        // Rejected here rather than sanitized: a policy carrying a control
+        // character is not a policy with a stray byte in it, it is a caller
+        // doing something this route has no honest interpretation of.
+        return c.json({ error: "csp is not a valid header value" }, 400);
+      }
+      if (html.length > MAX_APP_DOCUMENT_CHARS) {
+        return c.json({ error: "Document too large" }, 413);
+      }
+      if (csp !== undefined && csp.length > MAX_APP_CSP_CHARS) {
+        return c.json({ error: "csp too large" }, 413);
+      }
+      const published = publish({ html, csp });
+      if (!published) {
+        return c.json({ error: "App-origin hosting is not available" }, 503);
+      }
+      return c.json(published);
+    },
+  );
 
   app.post("/api/mcp/connect", async (c) => {
     let body: RemoteConnectRequest;
diff --git a/docs/mcp-app-review.md b/docs/mcp-app-review.md
index 7a0acbe0..593e7b17 100644
--- a/docs/mcp-app-review.md
+++ b/docs/mcp-app-review.md
@@ -159,11 +159,11 @@ launching.
 ## 6. Reaching the web inspector remotely (SSH port-forward)
 
 When the backend runs on another host and you want to complete OAuth or
-visually inspect a rendered App from your local browser, forward **both**
+visually inspect a rendered App from your local browser, forward **all three**
 ports:
 
 ```bash
-ssh -L 6274:127.0.0.1:6274 -L 6275:127.0.0.1:6275 <remote-host>
+ssh -L 6274:127.0.0.1:6274 -L 6275:127.0.0.1:6275 -L 6278:127.0.0.1:6278 <remote-host>
 ```
 
 Then open `http://127.0.0.1:6274/?MCP_INSPECTOR_API_TOKEN=$TOKEN` locally.
@@ -178,6 +178,11 @@ Then open `http://127.0.0.1:6274/?MCP_INSPECTOR_API_TOKEN=$TOKEN` locally.
 - Forward `:6275` (`MCP_SANDBOX_PORT`) as well: the Apps tab renders widgets in
   an iframe served from that second origin; without it the App frame stays
   blank.
+- Forward `:6278` (`MCP_APP_ORIGIN_PORT`) too, for an App whose UI resource
+  declares `_meta.ui.domain` (#2056). That App is served from a *third* origin
+  the browser loads directly, so without the forward its frame fails to load —
+  and the backend cannot detect that, since publishing succeeded on its side.
+  An App that declares no `domain` is unaffected.
 - Forward the **same** local port number you bind on the remote — the browser
   sends `Origin: http://127.0.0.1:<local-port>` and the backend compares it to
   its own port.

From 80f76e365ef6299bb523dcb0cde24b25196b030d Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Mon, 24 Aug 2026 00:17:05 -0400
Subject: [PATCH 11/14] test(web): raise the theme-flip waitFor budget
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pre-existing flake, not introduced here — the file is untouched by this
branch and the test already carries a comment about failing this way once.
The default 1000ms was still too tight: it failed twice consecutively under
`npm run ci` (~1021ms, 0 calls) while passing every time the file runs
alone, which is a budget signature rather than a broken observer. A
generous `waitFor` costs nothing on the passing path.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 .../elements/AppRenderer/AppRenderer.test.tsx | 27 ++++++++++++-------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/clients/web/src/components/elements/AppRenderer/AppRenderer.test.tsx b/clients/web/src/components/elements/AppRenderer/AppRenderer.test.tsx
index 2cf355be..976f2a5d 100644
--- a/clients/web/src/components/elements/AppRenderer/AppRenderer.test.tsx
+++ b/clients/web/src/components/elements/AppRenderer/AppRenderer.test.tsx
@@ -550,17 +550,26 @@ describe("AppRenderer", () => {
       // many ticks happy-dom takes to deliver the MutationObserver callback is
       // load-dependent, so under a full parallel run the observer can still be
       // pending here. Observed failing exactly once that way, with 0 calls.
-      await waitFor(() =>
-        expect(bridge.sendHostContextChange).toHaveBeenCalledWith(
-          expect.objectContaining({
-            theme: "dark",
-            styles: expect.objectContaining({
-              variables: expect.objectContaining({
-                "--color-background-primary": "#101113",
+      //
+      // The default 1000ms then turned out not to be enough either — it failed
+      // twice in a row in `npm run ci` (at ~1021ms, still 0 calls) while
+      // passing every time this file runs alone, which is the signature of a
+      // budget that is too tight rather than of a broken observer. Raised
+      // rather than retried: a `waitFor` that is generous costs nothing on the
+      // passing path, since it returns as soon as the assertion holds.
+      await waitFor(
+        () =>
+          expect(bridge.sendHostContextChange).toHaveBeenCalledWith(
+            expect.objectContaining({
+              theme: "dark",
+              styles: expect.objectContaining({
+                variables: expect.objectContaining({
+                  "--color-background-primary": "#101113",
+                }),
               }),
             }),
-          }),
-        ),
+          ),
+        { timeout: 5000 },
       );
     } finally {
       getComputedStyleSpy.mockRestore();

From bb3ba91b8aec4ab303824cd56709e23e0d8c0db2 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Mon, 24 Aug 2026 00:35:21 -0400
Subject: [PATCH 12/14] fix(web): guard the app-origin port and the
 trusted-origin grant
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copilot review round 3 on #2100.

- MCP_APP_ORIGIN_PORT could equal CLIENT_PORT or MCP_SANDBOX_PORT. The
  app-origin listener starts BEFORE the web server binds, so that is not a
  race it loses — it wins the port and the Inspector dies with EADDRINUSE.
  `CLIENT_PORT=6278` was a valid config before this feature existed. It now
  resolves to a dynamic port with a warning: of the three listeners this is
  the only one that can move, and refusing to boot would cost the user the
  whole Inspector over a feature they may not be using.
- The proxy's same-origin refusal covered only its own origin. An app served
  from the INSPECTOR's origin is no safer: same-origin with the top document
  means direct access to window.top, its DOM and its storage, and the
  cross-origin frame in between buys nothing. Both trusted origins are now
  refused before allow-same-origin is granted.
- Replaced the `as unknown as number` on `server.address()` with a real
  narrowing of the string/null members of its return type.
- MCP_APP_ORIGIN_PORT added to the v1→v2 migration guide's env table, its
  Docker recipe, and a troubleshooting entry for the symptom this actually
  produces (the app renders, but its own backend rejects `Origin: null`).
- clients/web/README.md now states which failure is outside the fallback
  guarantee — a published document the browser cannot reach — and why there
  is no honest signal to fall back on. Docs and code no longer disagree.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/README.md                         | 15 ++++++++
 clients/web/server/app-origin-controller.ts   | 15 ++++----
 clients/web/server/web-server-config.ts       | 30 +++++++++++++++-
 .../server/web-server-config.test.ts          | 36 +++++++++++++++++++
 clients/web/static/sandbox_proxy.html         | 24 +++++++++----
 docs/v1-to-v2-migration.md                    | 12 +++++++
 6 files changed, 118 insertions(+), 14 deletions(-)

diff --git a/clients/web/README.md b/clients/web/README.md
index 63023953..bbbe0835 100644
--- a/clients/web/README.md
+++ b/clients/web/README.md
@@ -189,6 +189,21 @@ default (opaque-origin) way and logs a console warning naming `_meta.ui.domain`.
 Losing the real origin degrades what the app can reach; losing the app itself
 would be worse.
 
+**One failure is outside that guarantee, deliberately: a published document the
+browser cannot reach.** Every case above is one the *host* observes — publishing
+returned nothing, so it falls back before choosing a render path. If publishing
+succeeds and the browser then cannot load the URL (the port is not forwarded, or
+a collision moved the listener to a dynamic port that is not), the frame stays
+blank instead. There is no honest signal to fall back on: the navigation is
+cross-origin, so `onerror` never fires for an HTTP error, `onload` fires for the
+error page too, and nothing about the document is readable. The alternatives are
+a timeout — which races an app that is merely slow, and "recovers" it by
+re-running it at an opaque origin, executing its side effects twice — or a
+reachability probe on every render, which proves the port answers rather than
+that this fetch will. So the cause is removed instead of guessed at: every
+documented remote workflow forwards the port (see below, the Docker section of
+the root README, and the SSH recipe in `docs/mcp-app-review.md`).
+
 **Forward `6278` too** if you need this off loopback (a container, a tunnel).
 As with the sandbox port, a taken port falls back to an OS-assigned one with a
 loud warning — the app still renders, but the origin an app's backend was told
diff --git a/clients/web/server/app-origin-controller.ts b/clients/web/server/app-origin-controller.ts
index a9dc61e9..6fe43689 100644
--- a/clients/web/server/app-origin-controller.ts
+++ b/clients/web/server/app-origin-controller.ts
@@ -298,12 +298,15 @@ export function createAppOriginController(
 
         server.listen(port, host, () => {
           const addr = server!.address();
-          const actualPort =
-            typeof addr === "object" && addr !== null && "port" in addr
-              ? addr.port
-              : /* v8 ignore next -- unreachable for a TCP listen; `address()`
-                   returns AddressInfo. */
-                (addr as unknown as number);
+          /* v8 ignore next 4 -- unreachable for a TCP listen: inside the
+             `listening` callback `address()` returns an AddressInfo. The guard
+             is a narrowing for the string (pipe/socket) and null members of the
+             return type, not a case this listener can produce. */
+          if (typeof addr !== "object" || addr === null) {
+            settle({ port: 0, url: "" });
+            return;
+          }
+          const actualPort = addr.port;
           // A wildcard bind isn't reachable as `http://0.0.0.0:PORT`, but it
           // does serve loopback — advertise `localhost` there, and otherwise
           // the same canonical host the origin allow-list emits.
diff --git a/clients/web/server/web-server-config.ts b/clients/web/server/web-server-config.ts
index cd179df7..5c0b23e1 100644
--- a/clients/web/server/web-server-config.ts
+++ b/clients/web/server/web-server-config.ts
@@ -377,7 +377,35 @@ export function buildWebServerConfig(
       "");
 
   const sandboxPort = resolveSandboxPort();
-  const appOriginPort = resolveAppOriginPort();
+  // The app-origin listener starts BEFORE the web server binds (both in prod
+  // `startHonoServer` and in the Vite plugin), so a configured collision is not
+  // a harmless race — the app origin wins the port and the Inspector itself
+  // then dies with EADDRINUSE. `CLIENT_PORT=6278` is now such a config, and it
+  // was perfectly valid before this feature existed.
+  //
+  // Resolved to a dynamic port rather than by refusing to boot: of the three
+  // listeners this is the only one that can move (the sandbox URL and the web
+  // port are both advertised to the browser as fixed), and its own EADDRINUSE
+  // path already degrades this way. Losing a predictable app origin costs an
+  // app declaring `_meta.ui.domain` its forwarded port; refusing to boot costs
+  // the user the whole Inspector over a feature they may not be using.
+  const requestedAppOriginPort = resolveAppOriginPort();
+  const appOriginCollidesWith =
+    requestedAppOriginPort !== 0 &&
+    (requestedAppOriginPort === port
+      ? "the web server (CLIENT_PORT)"
+      : requestedAppOriginPort === sandboxPort
+        ? "the MCP Apps sandbox (MCP_SANDBOX_PORT)"
+        : null);
+  if (appOriginCollidesWith) {
+    console.warn(
+      `App origin: port ${requestedAppOriginPort} is already ${appOriginCollidesWith}; ` +
+        `using an OS-assigned port instead. Apps declaring _meta.ui.domain will still ` +
+        `render, but the origin they are served from is no longer predictable — set ` +
+        `MCP_APP_ORIGIN_PORT to a free one if your app's backend allowlists it.`,
+    );
+  }
+  const appOriginPort = appOriginCollidesWith ? 0 : requestedAppOriginPort;
 
   let logger: Logger | undefined;
   if (process.env.MCP_LOG_FILE) {
diff --git a/clients/web/src/test/integration/server/web-server-config.test.ts b/clients/web/src/test/integration/server/web-server-config.test.ts
index ce345d4a..51a56993 100644
--- a/clients/web/src/test/integration/server/web-server-config.test.ts
+++ b/clients/web/src/test/integration/server/web-server-config.test.ts
@@ -314,6 +314,42 @@ describe("buildWebServerConfigFromEnv", () => {
     expect(buildWebServerConfigFromEnv().appOriginPort).toBe(9300);
   });
 
+  it.each([
+    ["the web server", "CLIENT_PORT", "the web server (CLIENT_PORT)"],
+    [
+      "the sandbox",
+      "MCP_SANDBOX_PORT",
+      "the MCP Apps sandbox (MCP_SANDBOX_PORT)",
+    ],
+  ])(
+    "yields a dynamic app-origin port when it collides with %s",
+    (_label, envVar, expectedReason) => {
+      // The app-origin listener starts BEFORE the web server binds, so a
+      // configured collision is not a race it loses — it WINS the port and the
+      // Inspector then dies with EADDRINUSE. `CLIENT_PORT=6278` was a valid
+      // config before this feature existed.
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      try {
+        process.env[envVar] = "6500";
+        process.env.MCP_APP_ORIGIN_PORT = "6500";
+        expect(buildWebServerConfigFromEnv().appOriginPort).toBe(0);
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining(expectedReason),
+        );
+      } finally {
+        warnSpy.mockRestore();
+      }
+    },
+  );
+
+  it("leaves an explicit dynamic app-origin port alone", () => {
+    // 0 means "OS-assigned" for both, so two zeros are not a collision.
+    process.env.CLIENT_PORT = "6274";
+    process.env.MCP_SANDBOX_PORT = "0";
+    process.env.MCP_APP_ORIGIN_PORT = "0";
+    expect(buildWebServerConfigFromEnv().appOriginPort).toBe(0);
+  });
+
   it("sets MCP_STORAGE_DIR when present", () => {
     process.env.MCP_STORAGE_DIR = "/tmp/storage";
     expect(buildWebServerConfigFromEnv().storageDir).toBe("/tmp/storage");
diff --git a/clients/web/static/sandbox_proxy.html b/clients/web/static/sandbox_proxy.html
index 99d27f73..5777c474 100644
--- a/clients/web/static/sandbox_proxy.html
+++ b/clients/web/static/sandbox_proxy.html
@@ -197,14 +197,24 @@
                 console.warn("[Sandbox] ignoring unparseable src:", src);
               }
             }
-            // The app origin MUST differ from this proxy's own — otherwise
-            // granting allow-same-origin below would put the untrusted app in
-            // this realm, exactly the escape the double-iframe model exists to
-            // prevent. Refuse rather than degrade quietly: this is a host
-            // misconfiguration, not app input.
-            if (srcUrl && srcUrl.origin === window.location.origin) {
+            // The app origin MUST differ from BOTH trusted origins — this
+            // proxy's own and the Inspector page above it. Granting
+            // allow-same-origin below is what makes the app's origin real, and
+            // an app sharing the proxy's origin would land in this realm
+            // outright; one sharing the HOST's origin is no better, since
+            // same-origin with the top document means direct access to
+            // `window.top`, its DOM and its storage — the cross-origin frame in
+            // between buys nothing once the inner document is same-origin with
+            // the thing it is trying to reach. Either is a host
+            // misconfiguration, not app input, so refuse rather than degrade
+            // quietly.
+            if (
+              srcUrl &&
+              (srcUrl.origin === window.location.origin ||
+                srcUrl.origin === EXPECTED_HOST_ORIGIN)
+            ) {
               console.error(
-                "[Sandbox] refusing a src on the proxy's own origin:",
+                "[Sandbox] refusing a src on a trusted origin:",
                 srcUrl.origin,
               );
               srcUrl = null;
diff --git a/docs/v1-to-v2-migration.md b/docs/v1-to-v2-migration.md
index c241e9df..19727a67 100644
--- a/docs/v1-to-v2-migration.md
+++ b/docs/v1-to-v2-migration.md
@@ -281,6 +281,7 @@ Stdout is otherwise compatible: the default `text` format still pretty-prints th
 | —                        | `DANGEROUSLY_BIND_ALL_INTERFACES`                                             | New opt-in for a wildcard bind (the Docker image sets it)                                                                                                                                                                                                                                                                                                                                             |
 | —                        | `MCP_CATALOG_PATH`                                                            | Default catalog path                                                                                                                                                                                                                                                                                                                                                                                  |
 | —                        | `MCP_SANDBOX_PORT`                                                            | MCP Apps sandbox server port (fixed `6275` by default)                                                                                                                                                                                                                                                                                                                                                     |
+| —                        | `MCP_APP_ORIGIN_PORT`                                                         | Dedicated app-origin server port (fixed `6278` by default), used only by an MCP App whose UI resource declares `_meta.ui.domain`                                                                                                                                                                                                                                                                                                                                                     |
 | —                        | `MCP_STORAGE_DIR`, `MCP_INSPECTOR_OAUTH_STATE_PATH`, `MCP_CLIENT_CONFIG_PATH` | Storage and OAuth state locations                                                                                                                                                                                                                                                                                                                                                                     |
 | —                        | `MCP_OAUTH_CALLBACK_URL`                                                      | CLI/TUI OAuth loopback callback                                                                                                                                                                                                                                                                                                                                                                       |
 
@@ -339,6 +340,15 @@ Notes:
 
   Publish it on the **same port number** inside and out: the sandbox URL is handed to the browser via `/api/config` as `http://localhost:<container port>/sandbox`, so remapping it advertises a port the browser can't reach. To use a different number, move both ends — `-e MCP_SANDBOX_PORT=6280 -p 127.0.0.1:6280:6280`.
 
+- **And a third port for an App that declares `_meta.ui.domain`.** That spec field asks the host for a stable, dedicated origin, which v2 answers with a further listener on `MCP_APP_ORIGIN_PORT` (fixed `6278` by default) that the browser also reaches directly. Apps declaring no `domain` never touch it, so publish it only if you need one:
+
+  ```bash
+  docker run --rm -p 127.0.0.1:6274:6274 -p 127.0.0.1:6275:6275 -p 127.0.0.1:6278:6278 \
+    ghcr.io/modelcontextprotocol/inspector:latest
+  ```
+
+  Same-number rule and same remap escape hatch (`-e MCP_APP_ORIGIN_PORT=6281 -p 127.0.0.1:6281:6281`). Unpublished, such an app still renders — at an opaque origin, with a console warning — so this one degrades rather than blanking. Nothing in v1 corresponds to it.
+
 - The v2 image sets `DANGEROUSLY_BIND_ALL_INTERFACES=true` internally (a container must bind `0.0.0.0` to be reachable through `-p`). Setting a bare `HOST=0.0.0.0` **outside** a container now exits with an error.
 - **If you remap the published port** (`-p 8080:6274`), the browser's origin no longer matches the in-container port, so set `ALLOWED_ORIGINS=http://localhost:8080,http://127.0.0.1:8080` (or run `-e CLIENT_PORT=8080 -p 8080:8080`) or connects will 403.
 - The image runs as non-root and has a `HEALTHCHECK` that assumes `--web`; add `--no-healthcheck` when running `--cli` / `--tui`.
@@ -358,6 +368,8 @@ Notes:
 
 **"The Apps tab is blank in Docker / over SSH."** The MCP Apps sandbox is a second port (`6275` by default). Publish/forward it too — see [MCP Apps caveats](../clients/web/README.md#hosting-on-a-network).
 
+**"One particular App renders, but its requests are rejected by its own backend."** That App declares `_meta.ui.domain` and is being served from the opaque-origin fallback, so its requests carry `Origin: null`. It needs the **third** port (`MCP_APP_ORIGIN_PORT`, `6278` by default) published or forwarded as well; the console carries a warning naming the field. See [MCP App dedicated origins](../clients/web/README.md#mcp-app-dedicated-origins-metauidomain).
+
 **"The page never loads inside a VS Code dev container."** Fixed in the release carrying #1951 — upgrade; on an older version, work around it with `HOST=127.0.0.1`. Before that fix the default `HOST=localhost` bound IPv6 loopback **only** on Linux, so anything connecting over IPv4 `127.0.0.1` was refused — which is what a dev container's port forwarder does. The terminal printed a normal banner while the browser spun forever; the failure is a **hang** rather than a connection error because the forwarder accepts on the host side before failing to connect inward. The same fix covers an `ssh -L 6274:127.0.0.1:6274` tunnel and a container healthcheck. It does **not** describe the official Docker image (it binds `0.0.0.0`, so it was never affected) or a plain `docker run -p` against a loopback bind, which is unreachable across the network namespace for an unrelated reason.
 
 **"`HOST=0.0.0.0` exits with an error."** That's the wildcard-bind guard. Bind a specific address instead, or set `DANGEROUSLY_BIND_ALL_INTERFACES=true` if you genuinely need all interfaces. See [Host binding & the origin allow-list](../clients/web/README.md#host-binding--the-origin-allow-list).

From 73bf0a25229acfdf120b51e6dba7a0cef7f2352d Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Mon, 24 Aug 2026 00:48:49 -0400
Subject: [PATCH 13/14] docs: distinguish a failed publish from an unreachable
 one
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copilot review round 4 on #2100. All three findings are the same error:
clients/web/README.md documents the limitation correctly, and every
port-forwarding blurb then said the opposite.

An unpublished/unforwarded port is NOT the opaque-origin fallback case. The
backend's listener binds fine inside the container, so publication succeeds
and the browser is handed a URL it cannot reach — the frame stays blank,
with no console warning, because a cross-origin navigation failure is not
observable from the page. The fallback and its warning cover the failures
the BACKEND can see: no listener, a port that never bound, an older backend,
a network error.

Corrected in the root README's Docker blurb and the migration guide's
third-port recipe. The migration guide's troubleshooting entry had the wrong
symptom for the same reason — a missing forward produces a blank frame, not
an app whose requests are rejected — so it now leads with that and keeps the
rejected-requests case beside it as the neighbouring symptom, since the two
have opposite causes and opposite console output.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 README.md                  | 2 +-
 docs/v1-to-v2-migration.md | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index ce97d1cd..b6547e2e 100644
--- a/README.md
+++ b/README.md
@@ -477,7 +477,7 @@ docker run --rm -p 127.0.0.1:6274:6274 -p 127.0.0.1:6275:6275 \
   ghcr.io/modelcontextprotocol/inspector
 ```
 
-**And `6278` if your app declares `_meta.ui.domain`.** That is the spec field a server uses to ask its host for a stable, dedicated origin — without one the app runs at an opaque origin and its requests carry `Origin: null`, which no CORS / OAuth-callback / API-key allowlist can admit. The Inspector answers the request with a real loopback origin on a third listener, `MCP_APP_ORIGIN_PORT` (default `6278`); apps that declare no `domain` never touch it. An app that declares one and can't reach it still renders — at an opaque origin, with a console warning. See [MCP App dedicated origins](./clients/web/README.md#mcp-app-dedicated-origins-metauidomain) for the host-specific contract and its isolation trade-offs.
+**And `6278` if your app declares `_meta.ui.domain`.** That is the spec field a server uses to ask its host for a stable, dedicated origin — without one the app runs at an opaque origin and its requests carry `Origin: null`, which no CORS / OAuth-callback / API-key allowlist can admit. The Inspector answers the request with a real loopback origin on a third listener, `MCP_APP_ORIGIN_PORT` (default `6278`); apps that declare no `domain` never touch it. **Publish it if you use one** — this is the one failure that does not fall back: the backend publishes fine (its listener bound inside the container), so it hands the browser a URL on a port the browser cannot reach, and that app's frame stays **blank**. The cross-origin navigation failure is not observable from the page, so there is no opaque-origin fallback and no console warning here; those cover the failures the *backend* can see (no listener, a port that never bound, an older backend). See [MCP App dedicated origins](./clients/web/README.md#mcp-app-dedicated-origins-metauidomain) for the host-specific contract and its isolation trade-offs.
 
 ```bash
 docker run --rm -p 127.0.0.1:6274:6274 -p 127.0.0.1:6275:6275 -p 127.0.0.1:6278:6278 \
diff --git a/docs/v1-to-v2-migration.md b/docs/v1-to-v2-migration.md
index 19727a67..e888e14b 100644
--- a/docs/v1-to-v2-migration.md
+++ b/docs/v1-to-v2-migration.md
@@ -347,7 +347,7 @@ Notes:
     ghcr.io/modelcontextprotocol/inspector:latest
   ```
 
-  Same-number rule and same remap escape hatch (`-e MCP_APP_ORIGIN_PORT=6281 -p 127.0.0.1:6281:6281`). Unpublished, such an app still renders — at an opaque origin, with a console warning — so this one degrades rather than blanking. Nothing in v1 corresponds to it.
+  Same-number rule and same remap escape hatch (`-e MCP_APP_ORIGIN_PORT=6281 -p 127.0.0.1:6281:6281`). Unlike the other degradations, leaving this **unpublished does not fall back**: the backend's listener binds fine inside the container, so publication succeeds and the browser is handed a URL on a port it cannot reach — that app's frame stays blank, with no console warning, because a cross-origin navigation failure is not observable from the page. Publish it whenever a server you inspect declares `domain`. Nothing in v1 corresponds to it.
 
 - The v2 image sets `DANGEROUSLY_BIND_ALL_INTERFACES=true` internally (a container must bind `0.0.0.0` to be reachable through `-p`). Setting a bare `HOST=0.0.0.0` **outside** a container now exits with an error.
 - **If you remap the published port** (`-p 8080:6274`), the browser's origin no longer matches the in-container port, so set `ALLOWED_ORIGINS=http://localhost:8080,http://127.0.0.1:8080` (or run `-e CLIENT_PORT=8080 -p 8080:8080`) or connects will 403.
@@ -368,7 +368,7 @@ Notes:
 
 **"The Apps tab is blank in Docker / over SSH."** The MCP Apps sandbox is a second port (`6275` by default). Publish/forward it too — see [MCP Apps caveats](../clients/web/README.md#hosting-on-a-network).
 
-**"One particular App renders, but its requests are rejected by its own backend."** That App declares `_meta.ui.domain` and is being served from the opaque-origin fallback, so its requests carry `Origin: null`. It needs the **third** port (`MCP_APP_ORIGIN_PORT`, `6278` by default) published or forwarded as well; the console carries a warning naming the field. See [MCP App dedicated origins](../clients/web/README.md#mcp-app-dedicated-origins-metauidomain).
+**"One particular App'"'"'s frame is blank, while other Apps render fine."** That App declares `_meta.ui.domain`, so it is served from the **third** port (`MCP_APP_ORIGIN_PORT`, `6278` by default) rather than from the sandbox — publish or forward that port too. Expect no console warning: the backend published the document successfully, so from its side nothing failed, and the browser'"'"'s inability to load a cross-origin URL is not observable from the page. The neighbouring symptom is different — an App that *renders* and has its requests rejected by its own backend is running on the opaque-origin fallback, which means publication itself failed (no listener, or a port that never bound) and the console **does** carry a warning naming `_meta.ui.domain`. See [MCP App dedicated origins](../clients/web/README.md#mcp-app-dedicated-origins-metauidomain).
 
 **"The page never loads inside a VS Code dev container."** Fixed in the release carrying #1951 — upgrade; on an older version, work around it with `HOST=127.0.0.1`. Before that fix the default `HOST=localhost` bound IPv6 loopback **only** on Linux, so anything connecting over IPv4 `127.0.0.1` was refused — which is what a dev container's port forwarder does. The terminal printed a normal banner while the browser spun forever; the failure is a **hang** rather than a connection error because the forwarder accepts on the host side before failing to connect inward. The same fix covers an `ssh -L 6274:127.0.0.1:6274` tunnel and a container healthcheck. It does **not** describe the official Docker image (it binds `0.0.0.0`, so it was never affected) or a plain `docker run -p` against a loopback bind, which is unreachable across the network namespace for an unrelated reason.
 

From 6011d4de030d8e4130e157a2884201420655d066 Mon Sep 17 00:00:00 2001
From: cliffhall <cliff@futurescale.com>
Date: Mon, 24 Aug 2026 01:06:12 -0400
Subject: [PATCH 14/14] fix(web): bound retained app documents by size; correct
 the cookie claim
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copilot review round 5 on #2100.

- The store bounded entry COUNT only, and the route admits 8Mi code units per
  document with a one-hour TTL — ~256Mi retainable on documents a server
  under test chooses the size of. Added a 64Mi retained-size budget evicted
  oldest-first alongside the count bound, with a running total kept in step
  with the map through a single `drop` seam so it cannot drift.
- The isolation claim was wrong about cookies. A separate port makes a
  separate ORIGIN, so DOM access, localStorage, sessionStorage and IndexedDB
  are isolated — but cookies are keyed by host and path, ignoring port, so an
  app served here shares the 127.0.0.1 jar with the Inspector and every other
  loopback service. Not a hole in the Inspector's own auth (the API token is
  a header plus a window global and sessionStorage, none of them cookies) and
  not closable without a distinct host this listener cannot mint, so it is
  stated plainly in both the module header and clients/web/README.md rather
  than left as a claim that is false for one of the three surfaces it names.
- Removed a shell-escaping artifact I left in the migration guide.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
---
 clients/web/README.md                         | 17 ++++
 clients/web/server/app-origin-controller.ts   | 79 ++++++++++++++++---
 .../server/app-origin-controller.test.ts      | 24 ++++++
 docs/v1-to-v2-migration.md                    |  2 +-
 4 files changed, 110 insertions(+), 12 deletions(-)

diff --git a/clients/web/README.md b/clients/web/README.md
index bbbe0835..885152ff 100644
--- a/clients/web/README.md
+++ b/clients/web/README.md
@@ -182,6 +182,23 @@ is *for* — a real, allowlistable origin — without minting a port or a DNS na
 per app, at the cost of not being a per-app isolation boundary: two such apps
 share `localStorage`, `sessionStorage`, and cookies for that origin.
 
+**And the separate port does not isolate cookies from the rest of loopback.**
+A distinct port makes a distinct *origin*, so the origin-scoped surfaces —
+DOM/scripting access, `localStorage`, `sessionStorage`, IndexedDB — are isolated
+from the sandbox proxy and from the Inspector page. **Cookies are not
+origin-scoped**: they are keyed by host and path, ignoring port. An app served
+here therefore shares the `127.0.0.1` cookie jar with the Inspector on `6274`
+and with anything else on loopback — it can read any non-`HttpOnly` cookie set
+for that host, and set `Path=/` cookies those services will receive.
+
+This is not a hole in the Inspector's own auth: the API token travels in the
+`x-mcp-remote-auth` header and lives in a `window` global and `sessionStorage`,
+neither of which another origin can read. Closing the cookie gap properly needs
+a distinct *host*, which this listener cannot mint (the Inspector owns no DNS,
+and a second loopback address is not portable) — so it is stated rather than
+papered over. Don't run the Inspector beside a loopback service whose session
+cookie you would not hand to an app under test.
+
 **Every failure falls back rather than blanking the app.** No app-origin
 listener, a port that never bound, an older backend with no
 `POST /api/app-document` route, a network error — each renders the app the
diff --git a/clients/web/server/app-origin-controller.ts b/clients/web/server/app-origin-controller.ts
index 6fe43689..12e028c6 100644
--- a/clients/web/server/app-origin-controller.ts
+++ b/clients/web/server/app-origin-controller.ts
@@ -27,8 +27,28 @@
  * the spec field is *for* (a real, allowlistable origin) without minting a port
  * — or a DNS name — per app. The consequence is that this origin is **not** a
  * per-app isolation boundary: two apps served here share `localStorage`,
- * `sessionStorage`, and cookies for it. They remain isolated from the sandbox
- * proxy and from the Inspector itself, which are different origins.
+ * `sessionStorage`, and cookies for it.
+ *
+ * ## What the separate port does and does not isolate
+ *
+ * A distinct port makes a distinct **origin**, so the usual origin-scoped
+ * surfaces are isolated from the sandbox proxy and from the Inspector page:
+ * DOM and scripting access, `localStorage`, `sessionStorage`, IndexedDB.
+ *
+ * **Cookies are the exception, and they are not isolated.** Cookies are scoped
+ * by host (and path), not by port — so an app served here shares the
+ * `127.0.0.1` cookie jar with the Inspector on `6274` and with every other
+ * service on loopback. It can read any non-`HttpOnly` cookie set for that host
+ * and set `Path=/` cookies those services will receive.
+ *
+ * That is a real caveat, but it is not a hole in the Inspector's own auth: the
+ * API token travels in the `x-mcp-remote-auth` header and is held in a
+ * `window` global and `sessionStorage`, both of which a different origin
+ * cannot read. Closing the cookie gap properly needs a distinct *host*, which
+ * this listener cannot mint — the Inspector owns no DNS, and a second loopback
+ * address is not portable. So it is documented rather than papered over; do
+ * not run the Inspector beside a loopback service whose session cookie you
+ * would not hand to an app under test.
  *
  * ## Why granting `allow-same-origin` here is not a regression
  *
@@ -77,6 +97,21 @@ export const DEFAULT_APP_ORIGIN_PORT = 6278;
 /** Documents kept at once. Oldest is evicted past this; see {@link publish}. */
 const MAX_DOCUMENTS = 32;
 
+/**
+ * Total retained document size, in UTF-16 code units, across every live entry.
+ *
+ * {@link MAX_DOCUMENTS} alone bounds the *count*, and the route admits up to
+ * 8Mi code units per document — so the count bound permits ~256Mi retained for
+ * a full hour, enough to OOM a memory-limited Inspector on documents a server
+ * chose the size of. Both bounds apply; whichever binds first evicts.
+ *
+ * 64Mi is roughly a full complement of ordinary widgets (a real app document is
+ * tens to hundreds of KiB) or a couple of pathological ones. An app large
+ * enough to evict its predecessors still renders — the frame fetches its `src`
+ * immediately, long before anything could push it out.
+ */
+const MAX_RETAINED_CHARS = 64 * 1024 * 1024;
+
 /**
  * How long a published document stays fetchable. An iframe fetches its `src`
  * once, so this only has to outlive the gap between publishing and the frame
@@ -192,6 +227,8 @@ export function parseDocumentId(url: string | undefined): string | null {
 
 interface StoredDocument extends AppDocument {
   expiresAt: number;
+  /** Retained size in UTF-16 code units, against {@link MAX_RETAINED_CHARS}. */
+  size: number;
 }
 
 export function createAppOriginController(
@@ -206,13 +243,25 @@ export function createAppOriginController(
 
   // Insertion-ordered, so the first key is the oldest entry.
   const documents = new Map<string, StoredDocument>();
+  // Running sum of every live entry's `size`, kept in step with the map on
+  // every insert and every delete. Tracked rather than recomputed: eviction
+  // runs per publish and summing the map there would be O(n) on a hot path.
+  let retainedChars = 0;
+
+  /** The single removal seam, so the running total cannot drift from the map. */
+  function drop(id: string): void {
+    const doc = documents.get(id);
+    if (!doc) return;
+    retainedChars -= doc.size;
+    documents.delete(id);
+  }
 
   const FRAME_ANCESTORS = frameAncestorsDirective(embedderOrigins);
 
   /** Drop everything past its TTL. Cheap: the map is bounded by MAX_DOCUMENTS. */
   function evictExpired(now: number): void {
     for (const [id, doc] of documents) {
-      if (doc.expiresAt <= now) documents.delete(id);
+      if (doc.expiresAt <= now) drop(id);
     }
   }
 
@@ -235,7 +284,7 @@ export function createAppOriginController(
           const id = req.method === "GET" ? parseDocumentId(req.url) : null;
           const doc = id ? documents.get(id) : undefined;
           if (!doc || doc.expiresAt <= Date.now()) {
-            if (id) documents.delete(id);
+            if (id) drop(id);
             res.writeHead(404, { "Content-Type": "text/plain" });
             res.end("Not Found");
             return;
@@ -293,6 +342,7 @@ export function createAppOriginController(
           server = null;
           origin = null;
           documents.clear();
+          retainedChars = 0;
           settle({ port: 0, url: "" });
         });
 
@@ -322,6 +372,7 @@ export function createAppOriginController(
 
     async close(): Promise<void> {
       documents.clear();
+      retainedChars = 0;
       if (!server) return;
       return new Promise((resolve) => {
         server!.close(() => {
@@ -340,17 +391,23 @@ export function createAppOriginController(
       if (!origin) return null;
       const now = Date.now();
       evictExpired(now);
-      // Bound the map even if nothing has expired: drop the oldest entry. An
-      // evicted document's frame has long since loaded, and the alternative is
-      // an unbounded store fed by every app the user opens in a session.
-      while (documents.size >= MAX_DOCUMENTS) {
+      const size = doc.html.length + (doc.csp?.length ?? 0);
+      // Bound the store even if nothing has expired: drop oldest-first until
+      // BOTH the count and the retained-size budget have room. An evicted
+      // document's frame has long since loaded, and the alternative is a store
+      // fed — in count and in bytes — by whatever the servers under test send.
+      while (
+        documents.size >= MAX_DOCUMENTS ||
+        (documents.size > 0 && retainedChars + size > MAX_RETAINED_CHARS)
+      ) {
         const oldest = documents.keys().next();
-        /* v8 ignore next -- `size >= MAX_DOCUMENTS` guarantees a first key. */
+        /* v8 ignore next -- both loop conditions require a non-empty map. */
         if (oldest.done) break;
-        documents.delete(oldest.value);
+        drop(oldest.value);
       }
       const id = randomBytes(16).toString("hex");
-      documents.set(id, { ...doc, expiresAt: now + DOCUMENT_TTL_MS });
+      documents.set(id, { ...doc, expiresAt: now + DOCUMENT_TTL_MS, size });
+      retainedChars += size;
       return { url: `${origin}${DOC_PATH_PREFIX}${id}` };
     },
   };
diff --git a/clients/web/src/test/integration/server/app-origin-controller.test.ts b/clients/web/src/test/integration/server/app-origin-controller.test.ts
index 7e9e66fa..92554db3 100644
--- a/clients/web/src/test/integration/server/app-origin-controller.test.ts
+++ b/clients/web/src/test/integration/server/app-origin-controller.test.ts
@@ -238,6 +238,30 @@ describe("createAppOriginController", () => {
     expect((await fetch(first.url)).status).toBe(404);
   });
 
+  it("evicts against a retained-size budget, not just the entry count", async () => {
+    // The count bound alone permits MAX_DOCUMENTS * 8Mi retained for an hour,
+    // on documents a server under test chooses the size of. Publish a few
+    // large ones — well under the 32-entry cap — and the earliest must stop
+    // being served.
+    const c = createAppOriginController({ port: 0, host: "127.0.0.1" });
+    controller = c;
+    const { url } = await c.start();
+    // 24Mi each: three fit under no count bound, but the third pushes total
+    // retained past the 64Mi budget and the first has to go.
+    const big = "x".repeat(24 * 1024 * 1024);
+    const first = c.publish({ html: big });
+    const second = c.publish({ html: big });
+    expect(first).not.toBeNull();
+    expect(second).not.toBeNull();
+    const third = c.publish({ html: big });
+    expect(third).not.toBeNull();
+
+    expect((await fetch(first!.url)).status).toBe(404);
+    // The newest is always served — its frame is about to fetch it.
+    expect((await fetch(third!.url)).status).toBe(200);
+    expect(url).toBe(c.getOrigin());
+  });
+
   it("404s a document past its TTL", async () => {
     // Fake `Date` ONLY — the TTL is the sole thing that reads it, and faking
     // the timer queue too would deadlock the real HTTP round-trip below.
diff --git a/docs/v1-to-v2-migration.md b/docs/v1-to-v2-migration.md
index e888e14b..752ecc12 100644
--- a/docs/v1-to-v2-migration.md
+++ b/docs/v1-to-v2-migration.md
@@ -368,7 +368,7 @@ Notes:
 
 **"The Apps tab is blank in Docker / over SSH."** The MCP Apps sandbox is a second port (`6275` by default). Publish/forward it too — see [MCP Apps caveats](../clients/web/README.md#hosting-on-a-network).
 
-**"One particular App'"'"'s frame is blank, while other Apps render fine."** That App declares `_meta.ui.domain`, so it is served from the **third** port (`MCP_APP_ORIGIN_PORT`, `6278` by default) rather than from the sandbox — publish or forward that port too. Expect no console warning: the backend published the document successfully, so from its side nothing failed, and the browser'"'"'s inability to load a cross-origin URL is not observable from the page. The neighbouring symptom is different — an App that *renders* and has its requests rejected by its own backend is running on the opaque-origin fallback, which means publication itself failed (no listener, or a port that never bound) and the console **does** carry a warning naming `_meta.ui.domain`. See [MCP App dedicated origins](../clients/web/README.md#mcp-app-dedicated-origins-metauidomain).
+**"One particular App's frame is blank, while other Apps render fine."** That App declares `_meta.ui.domain`, so it is served from the **third** port (`MCP_APP_ORIGIN_PORT`, `6278` by default) rather than from the sandbox — publish or forward that port too. Expect no console warning: the backend published the document successfully, so from its side nothing failed, and the browser's inability to load a cross-origin URL is not observable from the page. The neighbouring symptom is different — an App that *renders* and has its requests rejected by its own backend is running on the opaque-origin fallback, which means publication itself failed (no listener, or a port that never bound) and the console **does** carry a warning naming `_meta.ui.domain`. See [MCP App dedicated origins](../clients/web/README.md#mcp-app-dedicated-origins-metauidomain).
 
 **"The page never loads inside a VS Code dev container."** Fixed in the release carrying #1951 — upgrade; on an older version, work around it with `HOST=127.0.0.1`. Before that fix the default `HOST=localhost` bound IPv6 loopback **only** on Linux, so anything connecting over IPv4 `127.0.0.1` was refused — which is what a dev container's port forwarder does. The terminal printed a normal banner while the browser spun forever; the failure is a **hang** rather than a connection error because the forwarder accepts on the host side before failing to connect inward. The same fix covers an `ssh -L 6274:127.0.0.1:6274` tunnel and a container healthcheck. It does **not** describe the official Docker image (it binds `0.0.0.0`, so it was never affected) or a plain `docker run -p` against a loopback bind, which is unreachable across the network namespace for an unrelated reason.