Skip to main content

​
App not rendering in ChatGPT or Claude

If your app shows a blank, stuck, or stale iframe after calling a tool, try these steps in order:

​
1. Check your tunnel

If you’re using ngrok or a similar tunnel to expose your local server:
  • Verify the tunnel is running and pointing to the correct port
  • Make sure the tunnel protocol matches: use ngrok http 8000, not ngrok http https://localhost:8000
  • Check that the tunnel URL in your host’s app or connector management page matches the active tunnel

​
2. Check your dev server is running

Make sure sunpeak dev is running and the MCP server started successfully. You should see:
If the port changed (e.g. port 8000 was in use), update your tunnel and host configuration to match.

​
3. Restart the dev server

This clears any stale connections and re-registers all tools and resources.

​
4. Refresh or re-add the MCP server in the host

Most issues are resolved by refreshing the MCP server connection. In ChatGPT, open the developer-mode app under Plugins and refresh it from the plugin details. In other hosts, use their app or connector management page. If refresh fails, remove and re-add the MCP server: ChatGPT: Plugins > your developer-mode app > Refresh. To add it again, first make sure Developer mode is enabled from the bottom-left user menu under Settings > Security and login > Developer mode, then use Plugins > + with your tunnel URL. Claude: Settings > MCP Servers > Refresh (or Remove > Add again with your tunnel URL)

​
5. Hard refresh the host and open a new chat

Both ChatGPT and Claude cache MCP server connections and resource content aggressively.
  1. Hard refresh the page (Cmd+Shift+R / Ctrl+Shift+R)
  2. Open a new chat (cached iframes persist within the same conversation)
  3. Re-trigger the tool call

​
Port conflicts

sunpeak uses several ports during development: If a port is taken, sunpeak automatically finds a free one and prints the actual port used. Watch the console output for messages like port 8000 was in use.

​
HTTPS / ngrok issues

If you see Received HTTPS request on HTTP server, your tunnel is sending HTTPS traffic to an HTTP upstream. Fix:

​
Safari is not compatible with sunpeak dev

Safari automatically upgrades cross-origin HTTP requests to HTTPS. The dev server uses multiple localhost ports (inspector, MCP server, sandbox proxy) to replicate production CSP isolation, and Safari’s HTTPS upgrade breaks these cross-origin connections. Use Chrome (or any Chromium-based browser) for sunpeak dev. Production deploys via sunpeak start work in all browsers, including Safari, because the app is served as a single bundled page without cross-origin localhost dependencies.

​
Build errors with sunpeak dev --prod-resources

If --prod-resources mode fails, the built HTML may be stale or missing:
For inspector and test-related troubleshooting (blank inspector page, iframe test errors, live test auth), see Testing Troubleshooting.