Skip to content

MCP Apps: container stays visibility: hidden when server uses HTTP transport (works with native stdio) #149

Closed

Description

@nearestnabors

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/ui extension capability
  • Locate the UI resource registered on the Model's session
  • Properly set up the postMessage listener 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

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

  1. Set up an MCP server with an MCP App tool using @modelcontextprotocol/ext-apps SDK
  2. Configure it in Claude Desktop using native stdio transport → App renders ✅
  3. 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.

Image

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

  1. nearestnabors commented on Apr 5, 2026

    @nearestnabors
    Author

    Possible Resolution to Problem: MCP App iframe stays visibility: hidden

    Root Cause

    App was calling callServerTool() immediately after connect(), which interfered with the SDK's visibility handshake.

    Solution

    • Don't make tool calls during initialization
    • Set up ontoolresult handler before connect()
    • Wait for host to push the tool result to your app
    • The host already has the data when it renders your app

    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.

  2. ochafik commented on Apr 21, 2026

    @ochafik

    FYI for anyone landing here from a similar symptom — @nearestnabors's resolution above ended up shaping two SDK guards:

    • modelcontextprotocol/ext-apps#623 — calling callServerTool / sendMessage / etc. before await app.connect() has completed the handshake now logs a console.warn (or throws with new App(appInfo, caps, { strict: true })).
    • modelcontextprotocol/ext-apps#629 — registering ontoolinput / ontoolresult / ontoolcancelled (or the addEventListener equivalents) after await app.connect() now logs a console.warn (or throws under strict: 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions