Repository navigation
Description
What happened?
MCP App iframes fail to become visible in Claude Desktop when the MCP server uses HTTP transport (including HTTP proxied through stdio). The same app renders correctly when the server uses native stdio transport.
The container div wrapping the iframe remains at visibility: hidden indefinitely. The iframe itself loads, the @modelcontextprotocol/ext-apps SDK connects, and the PostMessageTransport is established — but the host never flips visibility.
Debugging findings
| Check | Result |
|---|---|
| HTML loads in iframe | ✅ Confirmed via DevTools |
SDK connects (PostMessageTransport) |
✅ Connection established |
autoResize: true / ResizeObserver |
✅ Firing |
Resource MIME type text/html;profile=mcp-app |
✅ Correct |
_meta.ui.resourceUri on tool |
✅ Present in tools/list |
Container visibility |
❌ Stays hidden with HTTP transport |
| Same app via native stdio | ✅ Renders correctly |
Suspected root cause
The MCP Apps initialization handshake (ui/initialize → response → ui/notifications/initialized) appears to not complete from Claude Desktop's perspective when the server is connected via HTTP transport.
Per ext-apps#481, Claude Desktop opens two separate MCP sessions over HTTP — one for the Model and one for the AppBridge. With native stdio, these share a single transport pipe. The AppBridge session may be failing to:
- Negotiate the
io.modelcontextprotocol/uiextension capability - Locate the UI resource registered on the Model's session
- Properly set up the
postMessagelistener for the iframe
Since the spec states the host MUST NOT send requests to the View before receiving ui/notifications/initialized, and the host gates visibility on this signal, a failure anywhere in this handshake would explain the visibility: hidden state.
Related issues
- Claude fails to invoke/render MCP App ui element for tool call. #61 — Same symptoms (MCP App UI fails to render, returns plain text), server uses Streamable HTTP
- Allow local-network-access in both iFrame for widget rendering #25 — iframe permission model for MCP Apps
- MCP Apps: No shared session identity between AppBridge and Model sub-connections modelcontextprotocol/ext-apps#481 — AppBridge and Model get separate session IDs over HTTP
Area
Tool Discovery / Invocation, MCP Apps rendering
What did you expect to happen?
The MCP App UI should render inline in the conversation after the ui/initialize → ui/notifications/initialized handshake completes, regardless of the underlying MCP transport.
Steps to reproduce
- Set up an MCP server with an MCP App tool using
@modelcontextprotocol/ext-appsSDK - Configure it in Claude Desktop using native stdio transport → App renders ✅
- Configure the same server using HTTP transport (or HTTP proxied through stdio) → Container stays at
visibility: hidden❌
Working reference: Any of the ext-apps example servers configured via native stdio (e.g., npx -y @modelcontextprotocol/server-<name> --stdio)
Failing case: Same server exposed via Streamable HTTP endpoint, connected to Claude Desktop as an HTTP connector or proxied through stdio
Area
MCP Connector (adding/managing servers)
MCP Server (if applicable)
custom server
Error messages or logs
Additional context
Screenshot clearly showing the UI rendered in an iframe with visibility: hidden remaining on the enclosing div.
MCP Server
Custom server using @modelcontextprotocol/ext-apps SDK v1.1.x, tested with both Streamable HTTP and stdio transports
Environment
- Claude Desktop (latest)
- macOS
- Node.js 18+
Activity
nearestnabors commentedon Apr 5, 2026
Possible Resolution to Problem: MCP App iframe stays visibility: hidden
Root Cause
App was calling
callServerTool()immediately afterconnect(), which interfered with the SDK's visibility handshake.Solution
Key Insight
Might be worth documenting!
MCP Apps are push, not pull. The host calls the tool, gets the result, renders your UI, then pushes the result to you. Your app should never fetch its own initial data.
feat(app-bridge): warn when View sends requests before initialized
feat(app,app-bridge): guard requests sent before handshake completes
feat(app,app-bridge): guard requests sent before handshake completes (#…
feat(app,app-bridge): guard requests sent before handshake completes (#…
feat(app,app-bridge): guard requests sent before handshake completes (#…
spec: Add tool registration for Apps, to be called by Host (WebMCP-st…
ochafik commentedon Apr 21, 2026
FYI for anyone landing here from a similar symptom — @nearestnabors's resolution above ended up shaping two SDK guards:
callServerTool/sendMessage/ etc. beforeawait app.connect()has completed the handshake now logs aconsole.warn(or throws withnew App(appInfo, caps, { strict: true })).ontoolinput/ontoolresult/ontoolcancelled(or theaddEventListenerequivalents) afterawait app.connect()now logs aconsole.warn(or throws understrict: true), since the host may have already fired those one-shot notifications by then.Both ship in
@modelcontextprotocol/[email protected], which should make this failure mode self-diagnosing rather than a silent hidden iframe.— drafted with the help of Claude