Troubleshoot MCP Apps changedconnectors/building/mcp-apps/troubleshooting
Nearest release: v2.1.283, published under an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 25 Sep 2026 18:00 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+45added
Lines−41removed
From line
12
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits4to this page, all time
The whole hunk
from line 12, old and new numbered
/
from line 12
1212
1313Claude Desktop's Developer Tools can help you debug MCP Apps. To use them:
1414
15<Steps>
16 <Step title="Enable Developer Mode">
17 Open **Help > Troubleshooting** and click **Enable Developer Mode**. A new **Developer** menu appears in the menu bar.
18 </Step>
15**1. Enable Developer Mode**
1916
20 <Step title="Open Developer Tools">
21 Open Developer Tools by pressing `Cmd+Option+I` on Mac or `Ctrl+Shift+I` on Windows.
22 </Step>
17Open **Help > Troubleshooting** and click **Enable Developer Mode**. A new **Developer** menu appears in the menu bar.
2318
24 <Step title="Find your app's iframe">
25 Inspect the tool call element and look for an iframe nested inside another iframe. Your app is loaded as the content of the inner iframe.
26 </Step>
27</Steps>
19**2. Open Developer Tools**
2820
29<Tip>From the **Developer** menu, select **Reload MCP Configuration** after editing your `claude_desktop_config.json` to apply changes without restarting.</Tip>
21Open Developer Tools by pressing `Cmd+Option+I` on Mac or `Ctrl+Shift+I` on Windows.
3022
23**3. Find your app's iframe**
24
25Inspect the tool call element and look for an iframe nested inside another iframe. Your app is loaded as the content of the inner iframe.
26
27> [!TIP]
28>
29> From the **Developer** menu, select **Reload MCP Configuration** after editing your `claude_desktop_config.json` to apply changes without restarting.
30
3131### iOS
3232
3333On iOS, the Claude app renders your MCP App inside a `WKWebView`. You can inspect it from a connected Mac using Safari's Web Inspector. Follow Apple's guide to [inspecting iOS](https://developer.apple.com/documentation/safari-developer-tools/inspecting-ios) for setup. Once connected, the Claude web view appears under your device in Safari's **Develop** menu, and you can use the console, network panel, and element inspector as you would on desktop.
from line 44
4444
4545Your app must call [`app.connect()`](https://modelcontextprotocol.github.io/ext-apps/api/classes/app.App.html#connect) in vanilla JS or [`useApp()`](https://modelcontextprotocol.github.io/ext-apps/api/functions/_modelcontextprotocol_ext-apps_react.useApp.html) in React to establish communication with Claude Desktop. Register your handlers before connecting:
4646
47<CodeGroup>
48 ```javascript Vanilla JS theme={null}
49 import { App } from "@modelcontextprotocol/ext-apps";
47```javascript Vanilla JS theme={null}
48import { App } from "@modelcontextprotocol/ext-apps";
5049
51 const app = new App({ name: "My App", version: "1.0.0" });
50const app = new App({ name: "My App", version: "1.0.0" });
5251
53 // Register handlers before connecting
54 app.ontoolresult = (result) => {
55 // Handle tool results
56 };
52// Register handlers before connecting
53app.ontoolresult = (result) => {
54 // Handle tool results
55};
5756
58 await app.connect();
59 ```
57await app.connect();
58```
6059
61 ```javascript React theme={null}
62 import { useApp } from "@modelcontextprotocol/ext-apps/react";
60```javascript React theme={null}
61import { useApp } from "@modelcontextprotocol/ext-apps/react";
6362
64 function MyComponent() {
65 // The useApp hook handles connection automatically
66 const { app } = useApp({
67 appInfo: { name: "My App", version: "1.0.0" },
68 capabilities: {},
69 onAppCreated: (app) => {
70 app.ontoolresult = (result) => {
71 // Handle tool results
72 };
73 }
74 });
75 }
76 ```
77</CodeGroup>
63function MyComponent() {
64 // The useApp hook handles connection automatically
65 const { app } = useApp({
66 appInfo: { name: "My App", version: "1.0.0" },
67 capabilities: {},
68 onAppCreated: (app) => {
69 app.ontoolresult = (result) => {
70 // Handle tool results
71 };
72 }
73 });
74}
75```
7876
79<Warning>Event handlers like `app.ontoolinput` and `app.ontoolresult` aren't invoked until the app is connected.</Warning>
77> [!WARNING]
78>
79> Event handlers like `app.ontoolinput` and `app.ontoolresult` aren't invoked until the app is connected.
8080
8181#### Iframe has zero height
8282
from line 91
9191
9292When a tool result exceeds approximately 150,000 characters and Claude's code execution sandbox is active, Claude writes the result to the sandbox filesystem instead of passing it inline to the conversation. Your app receives a pointer to the stored file rather than the structured content it needs, so it never hydrates.
9393
94<Note>This \~150,000-character threshold is specific to claude.ai and Claude Desktop. Claude Code uses a separate 25,000-token default limit, configurable through `MAX_MCP_OUTPUT_TOKENS`.</Note>
94> [!NOTE]
95>
96> This \~150,000-character threshold is specific to claude.ai and Claude Desktop. Claude Code uses a separate 25,000-token default limit, configurable through `MAX_MCP_OUTPUT_TOKENS`.
9597
9698To stay under the threshold, keep initial tool result payloads lean:
9799
from line 109
107109
108110To fix the iOS failures, allowlist on the `Origin` header instead of `Referer`, because WebKit does send `Origin`. Requests from your app carry an `Origin` of `{hash}.claudemcpcontent.com`, and [Set `ui.domain` for Claude](/docs/connectors/building/mcp-apps/getting-started#set-ui-domain-for-claude) shows how to compute the hash for your server URL. Configure your infrastructure to allow requests whose `Origin` matches `*.claudemcpcontent.com` and return a corresponding `Access-Control-Allow-Origin` header.
109111
110<Note>The missing `Referer` header affects requests your app makes directly from the user's device, such as loading bundles and images or calling your own API from client-side code. MCP tool calls are proxied through Claude's backend and egress from Anthropic's published IP ranges, not the user's device.</Note>
112> [!NOTE]
113>
114> The missing `Referer` header affects requests your app makes directly from the user's device, such as loading bundles and images or calling your own API from client-side code. MCP tool calls are proxied through Claude's backend and egress from Anthropic's published IP ranges, not the user's device.
111115
112116### `ui.domain` validation fails
113117
No line in this hunk matches that.