From 4abcd6b04bfc2f36b723998f6ba050529058bb87 Mon Sep 17 00:00:00 2001 From: Booyaka101 Date: Fri, 31 Jul 2026 19:35:56 +0800 Subject: [PATCH] docs(csp-cors): note that a rejected ui.domain stops the app rendering The docs introduce _meta.ui.domain as a way to get a stable origin for CORS allowlisting, and #309 clarified that its format is host-dependent. Neither says what happens when the value isn't one the host accepts: the app doesn't fall back to the default sandbox origin, it doesn't render at all. Because the field is documented as an optional CORS convenience, it reads as safe to set speculatively. Adding it while hashing an endpoint URL spelled slightly differently from the one the client connected with turns a working app into one that silently doesn't render. Co-Authored-By: Claude Opus 5 --- docs/csp-cors.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/csp-cors.md b/docs/csp-cors.md index 8978ab615..41e241db9 100644 --- a/docs/csp-cors.md +++ b/docs/csp-cors.md @@ -60,5 +60,10 @@ registerAppResource( Note that `_meta.ui.csp` and `_meta.ui.domain` are set in the `contents[]` objects returned by the resource read callback, not in `registerAppResource()`'s config object. +> [!IMPORTANT] +> Hosts validate `_meta.ui.domain` when it is present, and a value they do not accept can stop the app rendering entirely rather than falling back to the default origin. On Claude, a domain that doesn't match the expected value means no iframe is created at all, reported only as a generic failure to reach the server. Omitting the field is safe — the host uses its default sandbox origin — so only set it when you need a stable origin to allowlist. +> +> When deriving the value, hash exactly the endpoint URL the app is connected as. A trailing slash, a missing path segment, or a different scheme each produce a different hash, and therefore a domain the host rejects. + > [!NOTE] > For full examples that configures CSP, see: [`examples/sheet-music-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/sheet-music-server) (`connectDomains`) and [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) (`connectDomains` and `resourceDomains`).