Add ngrok-skip-browser-warning header to iframe requests for dev tunnels

[thleonard]

Problem Statement

When developing a local MCP server for Claude.ai, the typical workflow is to expose it using a tunneling solution such as ngrok or cloudflared. If local-network-access is not allowed in the iframe (as discussed in #25), then all UI assets must be served through the tunnel.

With ngrok (free plan), HTTP requests hit an interstitial browser warning page unless they include the header: ngrok-skip-browser-warning: true

Since iframe-originated asset requests from Claude.ai do not include this header, they receive the interstitial HTML page instead of the expected JS/CSS assets. This breaks widget UI rendering and makes local development difficult.

Proposed Solution

If enabling local-network-access in the iframe is not an option, you could add the following header to outgoing iframe-originated HTTP requests: ngrok-skip-browser-warning: true

This would:

• Preserve existing security boundaries
• Avoid allowing direct localhost access
• Make ngrok free tunnels usable for local MCP development
• Prevent the interstitial page from breaking asset loading

Alternatives Considered

Cloudflared tunnels in free plan avoids this issue but generates a new random URL each run, which forces to create a new connector each time the tunnel is killed (which is painful).

Area

Developer Experience

Priority

Medium - Would be helpful

Additional Context

https://ngrok.com/docs/pricing-limits/free-plan-limits#removing-the-interstitial-page

[antonpk1]

Thanks for the report! We recommend using cloudflared instead of ngrok for local MCP development. It's free, has no interstitial pages, and requires no extra headers.

Here's a complete walkthrough using the MCP Apps quickstart example:

1. Clone and build the example server:

git clone https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps
npm install
cd examples/quickstart
npm run build

2. Start the server (Terminal 1):

npm start
# → MCP server listening on http://localhost:3001/mcp

3. Start a cloudflared tunnel (Terminal 2):

npx cloudflared tunnel --url http://localhost:3001

You'll see output like:

Your quick Tunnel has been created! Visit it at:
https://some-random-words.trycloudflare.com

4. Connect from Claude.ai:

Add the tunnel URL as a remote MCP server: https://some-random-words.trycloudflare.com/mcp

That's it — no special headers, no paid plans. The MCP App widget will render correctly through the tunnel.

Re: the changing URL — in practice this is less painful than it seems:

• You don't need to restart cloudflared when you restart your MCP server. Keep the tunnel running in a separate terminal; it proxies to localhost:3001 regardless of what's listening there. You only get a new URL if you kill the tunnel process itself.
• When you do restart the tunnel, updating the connector in Claude.ai is just editing the existing server URL — you don't need to delete and recreate the connector.

You can also install cloudflared directly via Homebrew (brew install cloudflared) instead of using npx.

This workflow is already documented in the ext-apps repo: Testing MCP Apps — Expose local servers with cloudflared.

We don't plan to add vendor-specific headers (like ngrok-skip-browser-warning) to iframe requests, as this would set a precedent for every tunneling provider. Cloudflared works out of the box and is our recommended approach for local development.