Why your MCP App renders blank

Give it the server’s URL. It opens the server the way an MCP Apps host does — Claude, ChatGPT, VS Code — with no credential and without calling a tool, reads each tool’s ui:// view, and says the first step that stops it rendering, whose it is, and the fix, citing the MCP Apps spec (SEP-1865) or the host’s own documentation. Then it shows you the view, sandboxed, the way a host frames it.

Or from a terminal, against a deployed server or one on localhost:

npx --allow-git=root github:agentwares/mcp-apps-doctor https://your-server.example/mcp
npx --allow-git=root github:agentwares/mcp-apps-doctor https://your-server.example/mcp --host claude --preview preview.html

What it checks, in the order a host meets it

1. A session opened as a dual-era MCP Apps host (server/discover at 2026-07-28, then initialize), declaring io.modelcontextprotocol/ui — servers may hide UI tools from clients that do not.
2. Each tool’s link to its view: _meta.ui.resourceUri, the deprecated flat key, or ChatGPT’s openai/outputTemplate alias, which only ChatGPT reads.
3. The view itself: resources/read answers, the MIME type is text/html;profile=mcp-app, there is HTML.
4. What the HTML loads against the CSP the host builds from _meta.ui.csp: undeclared origins and relative URLs, which resolve to the host’s sandbox, are the usual blank screen. Whether it opens the bridge (ui/initialize, the SDK’s app.connect()), without which Claude never shows the frame.
5. ui.domain per host: Claude accepts only {hash}.claudemcpcontent.com for your exact URL; ChatGPT’s review wants an https origin of your own. One fixed value cannot be both.
6. What OpenAI’s directory review checks from the server: explicit readOnlyHint, destructiveHint and openWorldHint on every tool, descriptions, a public https endpoint, the domain-verification file, screenshots or none.

Verdicts per host are judged from each host’s published pages and the issues filed against it; no host is run. Host bugs seen only in issues are labelled observed, with the date opened.

Error messages, explained

• “MCP App renders blank” — Nobody prints it: Claude, ChatGPT and VS Code show the tool call and then an empty or invisible frame, with nothing in the server's logs
• “Resource not found: ui://” — The server's MCP SDK, in its answer to the host's resources/read (`Resource not found: ui://…` in the TypeScript SDK, `Resource ui://… not found` in its 1.x line), shown in a host's logs or MCP Inspector
• “Tool has no UI” — No host prints it as such: the tool runs and its result shows as text or JSON. OpenAI's troubleshooting page calls it "Structured content only, no component"
• “Invalid ui.domain format” — Claude (claude.ai and Claude Desktop), in full: `Invalid ui.domain format: expected "{hash}.claudemcpcontent.com", got "…"`, sometimes behind an "Unable to reach <app>" banner
• “ui.domain mismatch” — Claude (claude.ai and Claude Desktop), instead of rendering the view
• “Refused to load the script” — The browser, in the view's iframe console: `Refused to load the script '…' because it violates the following Content Security Policy directive: "script-src …"`
• “annotations_required” — OpenAI's plugin submission portal, at final submission of a remote MCP plugin
• “domain_verification_required” — OpenAI's plugin submission portal, when Verify Domain has not passed for the MCP host
• “frame_domain_explanation_required” — OpenAI's plugin submission portal, for each external frame domain the tool scan reports
• “screenshots_not_allowed” — OpenAI's plugin submission portal, when screenshots are attached to a plugin whose scan found no UI
• “Failed to fetch template” — ChatGPT, in place of a published app's widget

Keep checking

agentcheck's free watch checks this server every hour and emails when it stops answering or its tool list changes; no account. It does not re-read the ui:// views.

mcpcheck Server Pro diffs the server's tool catalog every night — removed tools, tightened schemas, changed descriptions — with the client-compat matrix, OAuth conformance and 90 days of history; $49 a server a month, first run free. It does not re-run these MCP Apps checks.

What it will not do

It never sends a credential and never calls a tool: tools/list, resources/list and resources/read, plus at most three GETs or one preflight of public documents on the same origin. Every request has a ten-second timeout and identifies itself as agentwares-mcp-liveness/0.1 (+https://agentwares-agentcheck.vercel.app/bot). A URL must be public https: every address it resolves to and every redirect is checked first, and one caller gets 30 URL checks a minute per server instance. The preview runs only in your browser, in a sandboxed frame. The same check is mcp_liveness_check_apps on this host’s MCP server, and npx --allow-git=root github:agentwares/mcp-apps-doctor in a terminal.

Sources

• SEP-1865 MCP Apps (Final), read 8 October 2026
• MCP Apps spec 2026-01-26, UI Resource Format, read 8 October 2026
• MCP Apps spec draft, Metadata Location, read 8 October 2026
• MCP Extensions overview, Negotiation, read 8 October 2026
• OpenAI, Add UI to your MCP server, read 8 October 2026
• OpenAI plugins reference, tool and resource _meta, read 8 October 2026
• OpenAI plugins troubleshooting, read 8 October 2026
• OpenAI plugin submission errors, read 8 October 2026
• OpenAI remote MCP server review requirements, read 8 October 2026
• Claude, Troubleshoot MCP Apps, read 8 October 2026
• Claude, Set ui.domain for Claude, read 8 October 2026

Rules read on 8 October 2026. The sign-in check · MCP Liveness · Terms · Privacy