fix(mcp-app): improve host detection, dev logging, and mobile handling (tldraw#8199)

In order to fix ChatGPT copy-paste issues and improve the MCP app's
host-detection reliability, this PR refactors hostname resolution,
replaces the debug module with an integrated dev log panel, and adds
mobile platform handling.

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

### Change type

- [x] `improvement`

### Test plan

1. Run `yarn dev` in `apps/mcp-app` and connect from Cursor/Claude
Desktop — verify the canvas loads and tools work
2. Connect from ChatGPT via `yarn dev:tunnel` — verify host detection
resolves to `chatgpt`
3. Verify the dev log panel appears when `MCP_IS_DEV=true` and can be
toggled via the toolbar button
4. Verify fullscreen toggle works in desktop clients and is disabled on
mobile platforms

- [ ] Unit tests
- [ ] End to end tests

### Release notes

- Improve MCP app host detection for ChatGPT clients
- Add integrated dev log panel visible in dev mode
- Resolve host name client-side for more reliable detection
- Disable fullscreen on mobile platforms
- Clean up verbose server-side logging
- Update README with separate Claude Desktop local/remote setup
instructions

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Medium risk because it changes how host identity is resolved, what
bootstrap data is injected into the widget, and how
fullscreen/display-mode is handled (including new mobile restrictions),
which can impact client compatibility (ChatGPT/Claude/Cursor/VS Code).
No auth or data-storage model changes beyond logging/bootstrapping.
> 
> **Overview**
> Improves MCP host detection by splitting hostname resolution into
server-side (`resolveMcpAppHostNameFromServerInfo`) vs client-side
(`resolveMcpAppHostNameFromClientInfo`) parsing and broadening ChatGPT
detection; the widget now resolves host name from `app.getHostVersion()`
instead of relying on server-injected `hostName`.
> 
> Replaces the old ad-hoc widget `debug.ts` logging with an integrated
**dev log panel** gated by a new `isDev` bootstrap flag (injected by the
canvas resource) and a toolbar toggle.
> 
> Adjusts UI behavior for mobile hosts by disabling fullscreen
capability and forcing an exit from fullscreen if the host platform
becomes `mobile`, and removes verbose server-side `console.error`
checkpoint/debug logging. Adds an MIT `LICENSE.md`, updates the `README`
setup instructions, and enables `preview_urls` in `wrangler.toml`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
450b792. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: max-drake

apps/mcp-app/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024 tldraw Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

apps/mcp-app/README.md

@@ -1,6 +1,6 @@
-# MCP app
+# tldraw MCP app
 
-This is the tldraw MCP app. It exposes an interactive tldraw canvas to AI agents via the [Model Context Protocol](https://modelcontextprotocol.io/), so agents in Cursor, Claude Desktop, ChatGPT, and VS Code can draw diagrams and shapes on a canvas during a conversation.
+This is the tldraw MCP app. It exposes an interactive tldraw canvas to AI agents via the [Model Context Protocol app specification](https://github.com/modelcontextprotocol/ext-apps/), so you can work in tldraw with agents in any MCP client that supports the MCP app spec.
 
 ## Architecture
 
@@ -19,31 +19,31 @@ Both entry points share tool registration logic in `src/register-tools.ts`.
 
 ### Widget
 
-The widget is a React app (`src/widget/mcp-app.tsx`) that renders a full tldraw canvas inside the MCP host's iframe. Vite bundles it into a single HTML file (`dist/mcp-app.html`) using `vite-plugin-singlefile`, which the server injects bootstrap data into before serving.
+The widget is a React app (`src/widget/mcp-app.tsx`) that renders a full tldraw canvas inside the MCP host's iframe.
 
-The widget handles streaming previews (shapes appear as the model streams tool arguments), checkpoint persistence to `localStorage`, and syncing state back to the server.
+The widget handles streaming previews (shapes appear as the model streams tool arguments), and syncing state back to the server.
 
 ## Developing
 
 Run all commands from `apps/mcp-app`.
 
 ### Package scripts
 
-| Command           | What it does                                                                        |
-| ----------------- | ----------------------------------------------------------------------------------- |
-| `yarn build`      | Build the widget HTML                                                               |
-| `yarn dev`        | Build widget + start local Cloudflare worker (HTTP MCP on `localhost:8787`)         |
-| `yarn dev:stdio`  | Start a local stdio MCP server                                                      |
-| `yarn dev:tunnel` | Start a Cloudflare tunnel + local worker with `WORKER_ORIGIN` set to the tunnel URL |
-| `yarn deploy`     | Build widget + deploy the Cloudflare worker to production                           |
+| Command           | What it does                                                                                       |
+| ----------------- | -------------------------------------------------------------------------------------------------- |
+| `yarn build`      | Build the widget HTML                                                                              |
+| `yarn dev`        | Build widget + start local Cloudflare worker (HTTP MCP on `localhost:8787`)                        |
+| `yarn dev:stdio`  | Build widget + Start a local stdio MCP server                                                      |
+| `yarn dev:tunnel` | Build widget + Start a Cloudflare tunnel + local worker with `WORKER_ORIGIN` set to the tunnel URL |
+| `yarn deploy`     | Build widget + deploy the Cloudflare worker to production                                          |
 
 `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`:
+Add these three servers in `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -74,17 +74,13 @@ Add up to three servers in `~/.cursor/mcp.json`:
 
 `--cwd` ensures Cursor launches in the app folder. `-s` stops yarn from writing non-JSON noise to stdout, which breaks the stdio transport.
 
-### Claude Desktop setup
+### Claude Desktop local setup
 
-Update `~/Library/Application Support/Claude/claude_desktop_config.json`:
+For local Claude Desktop development, use `claude_desktop_config.json` for the local HTTP and stdio servers:
 
 ```json
 {
 	"mcpServers": {
-		"tldraw": {
-			"command": "npx",
-			"args": ["-y", "mcp-remote", "https://tldraw-mcp-app.tldraw.workers.dev/mcp"]
-		},
 		"tldraw-local": {
 			"command": "npx",
 			"args": ["-y", "mcp-remote", "http://127.0.0.1:8787/mcp"]
@@ -105,41 +101,41 @@ Update `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
+### Claude Desktop remote setup
+
+If you'd like to try the remote MCP server in Claude Desktop, use the in-app connector flow rather than adding the production URL to `claude_desktop_config.json`.
+
+1. Open Claude Desktop
+2. In the sidebar, go to **Customize**
+3. Open **Connectors**
+4. Click the button to add a connector, then choose **Add custom connector**
+5. Give it a name such as `tldraw`
+6. Paste `https://tldraw-mcp-app.tldraw.workers.dev/mcp` as the server URL
+
+The **Add custom connector** option is not available on the free plan, so you may need Max or another paid plan.
+
+If you need Notion access in Claude Desktop, use the Notion MCP connector for that separately.
+
 ### ChatGPT local dev
 
-ChatGPT requires an HTTPS origin, so you need a Cloudflare tunnel. You must be a workspace admin.
+ChatGPT requires an HTTPS origin, so you need a Cloudflare tunnel. You must be an admin of your OpenAI org/workspace to do local dev.
 
 1. Run `yarn dev:tunnel` in `apps/mcp-app`
 2. It prints a `https://...trycloudflare.com` tunnel URL
 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
+4. You can then test in both ChatGPT web and the desktop or mobile apps
 
 `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
 
 1. Make code changes in `apps/mcp-app`
 2. Run the relevant script (`dev`, `dev:stdio`, or `dev:tunnel`)
 3. Disconnect and reconnect the MCP server in your client (or reload the page/app)
-4. When making widget changes, make sure to rebuild — `yarn dev` does this automatically
+4. When making widget changes, make sure to rebuild, either by running `yarn build` or rerunning any of the dev scripts.
 
 Reconnecting the server after changes is the most reliable way to pick up new code, especially when the widget HTML changes.
 
-## License
-
-The code in this folder is Copyright (c) 2024-present tldraw Inc. The tldraw SDK is provided under the [tldraw license](https://github.com/tldraw/tldraw/blob/main/LICENSE.md).
-
-## Trademarks
-
-Copyright (c) 2024-present tldraw Inc. The tldraw name and logo are trademarks of tldraw. Please see our [trademark guidelines](https://github.com/tldraw/tldraw/blob/main/TRADEMARKS.md) for info on acceptable usage.
-
 ## Contact
 
 Find us on Twitter/X at [@tldraw](https://twitter.com/tldraw).

apps/mcp-app/server.ts

@@ -11,7 +11,7 @@ import {
 	MCP_SERVER_VERSION,
 	MCP_SERVER_WEBSITE_URL,
 } from './src/shared/types'
-import { resolveMcpAppHostName } from './src/shared/utils'
+import { resolveMcpAppHostNameFromServerInfo } from './src/shared/utils'
 import { loadCachedCanvasWidgetHtml } from './src/tools/loadCachedCanvasWidgetHtml'
 
 // --- Server factory ---
@@ -31,9 +31,6 @@ export function createServer() {
 		assets: unknown[] = [],
 		bindings: unknown[] = []
 	): void {
-		console.error(
-			`[tldraw-mcp] saveCheckpoint: id=${id}, shapes=${shapes.length}, assets=${assets.length}, bindings=${bindings.length}, existing checkpoints=${checkpoints.size}`
-		)
 		checkpoints.set(id, { shapes, assets, bindings })
 		if (checkpoints.size > MAX_CHECKPOINTS) {
 			const oldest = checkpoints.keys().next().value
@@ -46,22 +43,13 @@ export function createServer() {
 			if (checkpoints.size > 0) {
 				const lastKey = [...checkpoints.keys()].at(-1)!
 				const entry = checkpoints.get(lastKey)!
-				console.error(
-					`[tldraw-mcp] getActiveShapes: activeCheckpointId was NULL, fell back to last checkpoint=${lastKey}, shapes=${entry.shapes.length}`
-				)
 				activeCheckpointId = lastKey
 				return entry.shapes
 			}
-			console.error(
-				`[tldraw-mcp] getActiveShapes: activeCheckpointId is NULL and no checkpoints, returning []`
-			)
 			return []
 		}
 		const entry = checkpoints.get(activeCheckpointId)
 		const shapes = entry?.shapes ?? []
-		console.error(
-			`[tldraw-mcp] getActiveShapes: activeCheckpointId=${activeCheckpointId}, shapes=${shapes.length}, checkpoints.size=${checkpoints.size}`
-		)
 		return shapes
 	}
 
@@ -94,11 +82,8 @@ export function createServer() {
 
 	server.server.oninitialized = () => {
 		const clientInfo = server.server.getClientVersion()
-		const resolved = resolveMcpAppHostName(clientInfo?.name ?? '')
+		const resolved = resolveMcpAppHostNameFromServerInfo(clientInfo?.name ?? '')
 		if (resolved) clientHostName = resolved
-		console.error(
-			`[tldraw-mcp] Client connected: ${clientHostName ?? 'unknown'} v${clientInfo?.version ?? '?'}`
-		)
 	}
 
 	const deps: ServerDeps = {

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

@@ -209,7 +209,7 @@ export function registerTools(
 				return errorResponse(
 					'create_shapes',
 					err,
-					'Ensure shapesJson is a valid JSON array string of shapes objects (call read_me first for the format reference). '
+					'Ensure shapesJson is a valid JSON array string of shapes objects (call diagram_drawing_read_me first for the format reference). '
 				)
 			}
 		}
@@ -591,7 +591,7 @@ export function registerTools(
 			const sid = deps.getSessionId()
 			const hostName = opts.getClientHostName()
 
-			const bootstrap: Record<string, unknown> = { sessionId: sid, hostName }
+			const bootstrap: Record<string, unknown> = { sessionId: sid, isDev: opts.isDev }
 			if (activeId) {
 				const checkpoint = deps.loadCheckpoint(activeId)
 				if (checkpoint) {

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

@@ -20,7 +20,7 @@ export interface RegisterToolsOptions {
 	extraConnectDomains?: 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). */
+	/** Flag so the tools, and thus the widget, know if they are running in dev mode. */
 	isDev: boolean
 	/** Logging function (defaults to console.error). */
 	log?(...args: unknown[]): void
@@ -37,7 +37,7 @@ export const MCP_SERVER_DESCRIPTION =
 	'An interactive tldraw canvas with tools for diagramming, drawing, and more.'
 export const MCP_SERVER_WEBSITE_URL = 'https://www.tldraw.com'
 export const MCP_SERVER_INSTRUCTIONS =
-	'Use read_me for shape format examples. For create_shapes, update_shapes, and delete_shapes, send JSON array strings (build the array first, then JSON.stringify). Use create_shapes before update_shapes or delete_shapes when the canvas is empty.'
+	'Use diagram_drawing_read_me for shape format examples. For create_shapes, update_shapes, and delete_shapes, send JSON array strings (build the array first, then JSON.stringify). Use create_shapes before update_shapes or delete_shapes when the canvas is empty.'
 
 export const CANVAS_RESOURCE_URI = 'ui://show-canvas/mcp-app.html'
 

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

@@ -43,16 +43,38 @@ export function generateCheckpointId(): string {
 	return crypto.randomUUID().replace(/-/g, '').slice(0, 18)
 }
 
-export function resolveMcpAppHostName(potentialHostName: string): MCP_APP_HOST_NAMES | undefined {
+// these are what we get from server.server.getClientVersion() in the worker
+export function resolveMcpAppHostNameFromServerInfo(
+	potentialHostName: string
+): MCP_APP_HOST_NAMES | undefined {
 	const normalizedPotentialHostName = potentialHostName.trim().toLowerCase()
+
 	if (normalizedPotentialHostName.includes('cursor-vscode')) return 'cursor' // we expect something like "cursor-vscode (via mcp-remote 0.1.37)"
 	if (normalizedPotentialHostName.includes('visual studio code')) return 'vscode' // we expect something like "Visual Studio Code (via mcp-remote 0.1.37)"
-	if (normalizedPotentialHostName.includes('openai-mcp')) return 'chatgpt' // we expect something like "openai-mcp"
+	if (
+		normalizedPotentialHostName.includes('openai-mcp') ||
+		normalizedPotentialHostName.includes('chatgpt')
+	)
+		return 'chatgpt' // we expect something like "openai-mcp"
 	if (normalizedPotentialHostName.includes('claude-ai')) return 'claude' // we expect something like "claude-ai (via mcp-remote 0.1.37)"
 
 	return undefined
 }
 
+// these are what we expect from app.getHostVersion() (called in the client)
+export function resolveMcpAppHostNameFromClientInfo(
+	potentialHostName: string
+): MCP_APP_HOST_NAMES | undefined {
+	const normalizedPotentialHostName = potentialHostName.trim().toLowerCase()
+
+	if (normalizedPotentialHostName.includes('cursor')) return 'cursor'
+	if (normalizedPotentialHostName.includes('visual studio code')) return 'vscode'
+	if (normalizedPotentialHostName.includes('chatgpt')) return 'chatgpt'
+	if (normalizedPotentialHostName.includes('claude')) return 'claude'
+
+	return undefined
+}
+
 const CODE_EDITOR_HOST_NAMES: MCP_APP_HOST_NAMES[] = ['cursor', 'vscode']
 
 export function isHostCodeEditor(hostName: MCP_APP_HOST_NAMES): boolean {

apps/mcp-app/src/widget/app-context.tsx

@@ -1,15 +1,19 @@
-import { type App } from '@modelcontextprotocol/ext-apps/react'
+import { type App, type McpUiDisplayMode } from '@modelcontextprotocol/ext-apps/react'
 import { createContext } from 'react'
 import type { MCP_APP_HOST_NAMES } from '../shared/types'
 
 export const McpAppContext = createContext<{
-	displayMode: 'inline' | 'fullscreen'
-	toggleFullscreen: (() => void) | null
+	displayMode: McpUiDisplayMode
+	toggleFullscreen: (() => Promise<void>) | null
 	canFullscreen: boolean
 	canDownload: boolean
 	app: App | null
 	lastEditor: 'user' | 'ai'
 	hostName: MCP_APP_HOST_NAMES | null
+	isDev: boolean
+	isDevLogVisible: boolean
+	toggleDevLog: (() => void) | null
+	logIfDevMode: ((message: string) => void) | null
 }>({
 	displayMode: 'inline',
 	toggleFullscreen: null,
@@ -18,4 +22,8 @@ export const McpAppContext = createContext<{
 	app: null,
 	lastEditor: 'ai',
 	hostName: null,
+	isDev: false,
+	isDevLogVisible: false,
+	toggleDevLog: null,
+	logIfDevMode: null,
 })