> ## Documentation Index
> Fetch the complete documentation index at: https://sunpeak.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and how to fix them when developing MCP Apps.

## 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:

```
Sunpeak MCP server listening on http://localhost:8000
  MCP endpoint: http://localhost:8000/mcp
```

If the port changed (e.g. `port 8000 was in use`), update your tunnel and host configuration to match.

### 3. Restart the dev server

<Tabs>
  <Tab title="pnpm">
    ```bash theme={null}
    # Stop the dev server (Ctrl+C), then restart
    pnpm dev
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    # Stop the dev server (Ctrl+C), then restart
    npm run dev
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    # Stop the dev server (Ctrl+C), then restart
    yarn dev
    ```
  </Tab>
</Tabs>

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:

| Port | Purpose | Override |
| - | - | - |
| 3000 | Inspector UI | `sunpeak dev --port 3001` |
| 8000 | MCP server (tunnel target) | Automatic fallback |
| 24679 | Vite HMR WebSocket | `SUNPEAK_HMR_PORT` env var |
| 24680 | Sandbox iframe server | `SUNPEAK_SANDBOX_PORT` env var |

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:

```bash theme={null}
# Wrong:
ngrok http https://localhost:8000

# Correct:
ngrok http 8000
```

### 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:

<Tabs>
  <Tab title="pnpm">
    ```bash theme={null}
    # Rebuild manually
    pnpm build

    # Then retry with prod resources
    pnpm dev -- --prod-resources
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    # Rebuild manually
    npm run build

    # Then retry with prod resources
    npm run dev -- --prod-resources
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    # Rebuild manually
    yarn build

    # Then retry with prod resources
    yarn dev --prod-resources
    ```
  </Tab>
</Tabs>

<Note>
  For inspector and test-related troubleshooting (blank inspector page, iframe test errors, live test auth), see [Testing Troubleshooting](/docs/testing/troubleshooting).
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.