refactor(mcp-app): replace per-host domain config with isDev flag (tldraw#8184)

In order to simplify widget domain configuration and make local
development reliable, this PR replaces the per-host `MCP_DOMAIN_OPENAI`
/ `MCP_DOMAIN_CLAUDE` environment variables with a single `MCP_IS_DEV`
flag and a `getWidgetDomain()` function that resolves the correct domain
per host.

Reimplemented from
[`max/mcp-app-approvals-fixes`](https://github.com/tldraw/tldraw/tree/max/mcp-app-approvals-fixes)
with a clean commit history.

### Change type

- [x] `improvement`

### Test plan

1. Run `yarn dev` in `apps/mcp-app` — verify local worker starts with
`MCP_IS_DEV=true` and no `ui.domain` is set on the canvas resource
2. Run `yarn dev:tunnel` — verify tunnel mode also passes
`MCP_IS_DEV=true`
3. Deploy to production — verify `MCP_IS_DEV=false` (default in
wrangler.toml) causes `getWidgetDomain()` to return the correct domain
for ChatGPT and Claude hosts
4. Hit `/.well-known/openai-apps-challenge` — verify it returns the
verification string

### Release notes

- Replace per-host domain env vars with `MCP_IS_DEV` flag for simpler
widget domain configuration
- Add `/.well-known/openai-apps-challenge` endpoint for OpenAI domain
verification
- Add `enabled` flag to Logger to suppress logs in production

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes how `ui.domain` is computed for ChatGPT/Claude and introduces
a new unauthenticated verification route, which could affect production
widget rendering or deployment validation if misconfigured.
> 
> **Overview**
> **Widget domain handling is refactored** to drop
`MCP_DOMAIN_OPENAI`/`MCP_DOMAIN_CLAUDE` and instead use `MCP_IS_DEV` + a
new `getWidgetDomain()` to set `_meta.ui.domain` only in production
(ChatGPT uses `https://tldraw.com`; Claude hashes the deployed `/mcp`
URL from `WORKER_ORIGIN`).
> 
> **Dev/prod behavior is now explicit**: local `wrangler dev` and tunnel
scripts pass `MCP_IS_DEV:true`, while `wrangler.toml` defaults
`MCP_IS_DEV="false"`; docs are updated accordingly. The worker also adds
`/.well-known/openai-apps-challenge` (no auth) and gates structured
logging behind a new `Logger(enabled)` flag (enabled only in dev).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
50deff3. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: max-drake

apps/mcp-app/README.md

@@ -39,6 +39,8 @@ Run all commands from `apps/mcp-app`.
 
 `yarn dev:tunnel` requires the `cloudflared` CLI to be installed on your machine.
 
+The worker defaults to production-safe behavior in `wrangler.toml`, including setting `MCP_IS_DEV="false"`. Local HTTP dev scripts override that with `MCP_IS_DEV=true` so local Claude/ChatGPT connectors suppress `ui.domain` while production deployments keep it enabled.
+
 ### Cursor setup
 
 Add up to three servers in `~/.cursor/mcp.json`:
@@ -112,7 +114,14 @@ ChatGPT requires an HTTPS origin, so you need a Cloudflare tunnel. You must be a
 3. In ChatGPT web (not the desktop app), go to **Apps** and add your app using that tunnel URL
 4. You can then test in both ChatGPT web and the desktop app
 
-`dev:tunnel` automatically wires `WORKER_ORIGIN` to the tunnel URL.
+`dev:tunnel` automatically wires `WORKER_ORIGIN` to the tunnel URL and sets `MCP_IS_DEV=true` for the local worker.
+
+### Auth and environment flags
+
+- `MCP_AUTH_TOKEN` controls bearer auth for the HTTP worker. If it is unset, the worker accepts unauthenticated local requests.
+- `MCP_IS_DEV` controls local-only widget behavior, such as suppressing `ui.domain` for local HTTP/tunnel connectors.
+
+These flags are intentionally separate so auth configuration does not change widget-domain behavior.
 
 ### Iteration loop
 

apps/mcp-app/dev-tunnel.sh

@@ -47,5 +47,5 @@ echo "Update claude_desktop_config.json to use:"
 echo "  \"args\": [\"-y\", \"mcp-remote\", \"$TUNNEL_URL/mcp\"]"
 echo ""
 
-# Start wrangler with the tunnel URL as WORKER_ORIGIN
-exec wrangler dev --port "$PORT" --var "WORKER_ORIGIN:$TUNNEL_URL"
+# Start wrangler with the tunnel URL as WORKER_ORIGIN in dev mode
+exec wrangler dev --port "$PORT" --var "WORKER_ORIGIN:$TUNNEL_URL" --var "MCP_IS_DEV:true"

apps/mcp-app/package.json

@@ -9,7 +9,7 @@
 		"build": "yarn build:widget",
 		"dev": "yarn dev:http",
 		"dev:stdio": "yarn build && tsx main.ts --stdio",
-		"dev:http": "yarn build && wrangler dev",
+		"dev:http": "yarn build && wrangler dev --var \"MCP_IS_DEV:true\"",
 		"dev:tunnel": "yarn build && bash dev-tunnel.sh",
 		"deploy": "yarn build && wrangler deploy",
 		"lint": "yarn run -T tsx ../../internal/scripts/lint.ts",

apps/mcp-app/server.ts

@@ -119,13 +119,8 @@ export function createServer() {
 		loadWidgetHtml: loadCachedCanvasWidgetHtml,
 	}
 
-	const httpDomain = {
-		openai: process.env.MCP_DOMAIN_OPENAI ?? '',
-		claude: process.env.MCP_DOMAIN_CLAUDE ?? '',
-	}
-
 	registerTools(server, deps, {
-		httpDomain: httpDomain.openai || httpDomain.claude ? httpDomain : undefined,
+		isDev: true,
 		log: console.error,
 		getClientHostName: () => clientHostName,
 	})

apps/mcp-app/src/logger.ts

@@ -6,28 +6,34 @@
  */
 
 export class Logger {
-	constructor(private prefix: string) {}
+	constructor(
+		private prefix: string,
+		private enabled: boolean
+	) {}
 
 	info(message: string, data?: Record<string, unknown>) {
+		if (!this.enabled) return
 		console.error(
 			JSON.stringify({ level: 'info', prefix: this.prefix, message, ...data, ts: Date.now() })
 		)
 	}
 
 	error(message: string, data?: Record<string, unknown>) {
+		if (!this.enabled) return
 		console.error(
 			JSON.stringify({ level: 'error', prefix: this.prefix, message, ...data, ts: Date.now() })
 		)
 	}
 
 	debug(message: string, data?: Record<string, unknown>) {
+		if (!this.enabled) return
 		console.error(
 			JSON.stringify({ level: 'debug', prefix: this.prefix, message, ...data, ts: Date.now() })
 		)
 	}
 
 	child(prefix: string): Logger {
-		return new Logger(`${this.prefix}:${prefix}`)
+		return new Logger(`${this.prefix}:${prefix}`, this.enabled)
 	}
 
 	/** Returns a log function compatible with RegisterToolsOptions.log */

apps/mcp-app/src/register-tools.ts

@@ -61,21 +61,51 @@ function injectBootstrapData(html: string, bootstrap: Record<string, unknown>):
 	return html.slice(0, lastIdx) + bootstrapScript + html.slice(lastIdx)
 }
 
+/**
+ * Returns the widget domain for the given host, or `undefined` in dev mode.
+ *
+ * - ChatGPT: https://developers.openai.com/apps-sdk/build/mcp-server#widget-domains
+ *   "Set `_meta.ui.domain` on the widget resource template. This is required for app
+ *   submission and must be unique per app. ChatGPT renders the widget under
+ *   `<domain>.web-sandbox.oaiusercontent.com`"
+ *
+ * - Claude: https://claude.com/docs/connectors/building/mcp-apps/cross-compatibility#domain-handling
+ *   "Compute the value by running:
+ *   `node -e 'const u = "https://example.com/mcp"; console.log(require("crypto").createHash("sha256").update(u).digest("hex"))'`"
+ */
+async function getWidgetDomain(
+	hostName: string | undefined,
+	isDev: boolean,
+	workerOrigin?: string
+): Promise<string | undefined> {
+	if (isDev) return undefined
+	if (hostName === 'chatgpt') return 'https://tldraw.com'
+	if (hostName === 'claude' && workerOrigin) {
+		const mcpUrl = new URL('/mcp', workerOrigin).toString()
+		const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(mcpUrl))
+		const hash = Array.from(new Uint8Array(digest), (byte) =>
+			byte.toString(16).padStart(2, '0')
+		).join('')
+		return `${hash}.claudemcpcontent.com`
+	}
+	return undefined
+}
+
 // --- Registration ---
 
 export function registerTools(
 	server: McpServer,
 	deps: ServerDeps,
-	opts?: RegisterToolsOptions
+	opts: RegisterToolsOptions
 ): void {
-	const log = opts?.log ?? ((...args: unknown[]) => console.error(...args))
+	const log = opts.log ?? ((...args: unknown[]) => console.error(...args))
 	const getBindingFromId = (binding: unknown): TLShape['id'] | null => {
 		if (!binding || typeof binding !== 'object') return null
 		const maybeFromId = (binding as { fromId?: unknown }).fromId
 		return typeof maybeFromId === 'string' ? (maybeFromId as TLShape['id']) : null
 	}
 
-	const analytics = opts?.analytics
+	const analytics = opts.analytics
 
 	// --- read_me ---
 
@@ -592,7 +622,8 @@ export function registerTools(
 			// has shapes synchronously on mount — before any streaming begins.
 			const activeId = deps.getActiveCheckpointId()
 			const sid = deps.getSessionId()
-			const hostName = opts?.getClientHostName()
+			const hostName = opts.getClientHostName()
+
 			const bootstrap: Record<string, unknown> = { sessionId: sid, hostName }
 			if (activeId) {
 				const checkpoint = deps.loadCheckpoint(activeId)
@@ -605,16 +636,9 @@ export function registerTools(
 			}
 			html = injectBootstrapData(html, bootstrap)
 
-			// Resolve domain from client identity (only when serving over HTTP with configured domains)
-			let domain: string | undefined
-			if (opts?.httpDomain?.openai || opts?.httpDomain?.claude) {
-				if (hostName === 'chatgpt') {
-					domain = opts.httpDomain.openai
-				} else if (hostName === 'claude') {
-					domain = opts.httpDomain.claude
-				}
-				log(`[tldraw-mcp] Serving resource to "${hostName}" with domain: ${domain}`)
-			}
+			const domain = await getWidgetDomain(hostName, opts.isDev, opts.workerOrigin)
+
+			log(`[tldraw-mcp] Serving resource to "${hostName}" with domain: ${domain}`)
 
 			return {
 				contents: [
@@ -629,10 +653,10 @@ export function registerTools(
 										'https://cdn.tldraw.com',
 										'https://fonts.googleapis.com',
 										'https://fonts.gstatic.com',
-										...(opts?.extraResourceDomains ?? []),
+										...(opts.extraResourceDomains ?? []),
 										'blob:',
 									],
-									connectDomains: ['https://cdn.tldraw.com', ...(opts?.extraConnectDomains ?? [])],
+									connectDomains: ['https://cdn.tldraw.com', ...(opts.extraConnectDomains ?? [])],
 								},
 								permissions: { clipboardWrite: {} },
 								...(domain ? { domain } : {}),

apps/mcp-app/src/shared/types.ts

@@ -18,8 +18,10 @@ export interface RegisterToolsOptions {
 	extraResourceDomains?: string[]
 	/** Extra CSP connect domains. */
 	extraConnectDomains?: string[]
-	/** When set, the canvas resource domain is resolved from the connecting client. */
-	httpDomain?: { openai: string; claude: string }
+	/** Public origin of the deployed MCP worker, used for host-specific widget domains. */
+	workerOrigin?: string
+	/** When true, suppresses `ui.domain` on the canvas resource (required for local connectors). */
+	isDev: boolean
 	/** Logging function (defaults to console.error). */
 	log?(...args: unknown[]): void
 	/** Analytics engine dataset. */

apps/mcp-app/src/worker.ts

@@ -31,9 +31,8 @@ interface Env {
 	ASSETS: Fetcher
 	RATE_LIMITER: RateLimit
 	MCP_AUTH_TOKEN: string
+	MCP_IS_DEV: string
 	WORKER_ORIGIN: string
-	MCP_DOMAIN_OPENAI: string
-	MCP_DOMAIN_CLAUDE: string
 	MCP_ANALYTICS?: AnalyticsEngineDataset
 }
 
@@ -76,14 +75,14 @@ export class TldrawMCP extends McpAgent<Env> {
 			instructions: MCP_SERVER_INSTRUCTIONS,
 		}
 	)
+	isDev = this.env.MCP_IS_DEV === 'true'
+	logsEnabled = this.isDev
 	activeCheckpointId: string | null = null
 	sessionId: string = ''
-	logger = new Logger('TldrawMCP')
+	logger = new Logger('TldrawMCP', this.logsEnabled)
 	clientHostName: MCP_APP_HOST_NAMES | undefined = undefined
 
 	async init() {
-		this.logger.info('Initializing Durable Object')
-
 		this.server.server.oninitialized = () => {
 			const clientInfo = this.server.server.getClientVersion()
 			const resolved = resolveMcpAppHostName(clientInfo?.name ?? '')
@@ -150,21 +149,17 @@ export class TldrawMCP extends McpAgent<Env> {
 			loadWidgetHtml: async () => widgetHtml,
 		}
 
-		const workerOrigin = this.env.WORKER_ORIGIN || ''
-		const domainOpenai = this.env.MCP_DOMAIN_OPENAI || ''
-		const domainClaude = this.env.MCP_DOMAIN_CLAUDE || ''
+		const workerOrigin = this.env.WORKER_ORIGIN
 
 		registerTools(this.server, deps, {
 			log: this.logger.toLogFn(),
 			extraResourceDomains: workerOrigin ? [workerOrigin] : [],
 			extraConnectDomains: workerOrigin ? [workerOrigin] : [],
-			httpDomain:
-				domainOpenai || domainClaude ? { openai: domainOpenai, claude: domainClaude } : undefined,
+			workerOrigin,
+			isDev: this.isDev,
 			analytics: this.env.MCP_ANALYTICS,
 			getClientHostName: () => this.clientHostName,
 		})
-
-		this.logger.info('Initialization complete')
 	}
 
 	// --- Checkpoint helpers ---
@@ -225,6 +220,7 @@ const sseHandler = TldrawMCP.serveSSE('/sse')
 export default {
 	async fetch(request: Request, env: Env, ctx: ExecutionContext) {
 		try {
+			const requireAuth = Boolean(env.MCP_AUTH_TOKEN)
 			const url = new URL(request.url)
 
 			// CORS preflight
@@ -237,8 +233,15 @@ export default {
 				return Response.json({ status: 'ok', timestamp: Date.now() })
 			}
 
-			// Auth check for MCP endpoints: skip if MCP_AUTH_TOKEN not set (local dev)
-			if (env.MCP_AUTH_TOKEN) {
+			// Domain verification (no auth)
+			if (url.pathname === '/.well-known/openai-apps-challenge') {
+				return new Response('kd9yRY8fxUTGRLJ6d22gpfATKZhXhHAu5Vdn6HWJsIQ', {
+					headers: { 'Content-Type': 'text/plain' },
+				})
+			}
+
+			// Require bearer auth only when an auth token is configured.
+			if (requireAuth) {
 				const auth = request.headers.get('Authorization')
 				if (auth !== `Bearer ${env.MCP_AUTH_TOKEN}`) {
 					return corsResponse(new Response('Unauthorized', { status: 401 }))

apps/mcp-app/wrangler.toml

@@ -19,6 +19,9 @@ new_sqlite_classes = ["TldrawMCP"]
 # Set this to the public URL of the worker. Used for constructing absolute image URLs.
 # Override with `--var WORKER_ORIGIN:https://your-tunnel.trycloudflare.com` for cloudflared tunnels.
 WORKER_ORIGIN = "https://tldraw-mcp-app.tldraw.workers.dev"
+# Default to production-safe widget behavior. Local dev scripts override this with
+# `--var MCP_IS_DEV:true` so local HTTP connectors omit `ui.domain`.
+MCP_IS_DEV = "false"
 
 [[analytics_engine_datasets]]
 binding = "MCP_ANALYTICS"