I spent a week building Wingman, an open source MCP server that renders a persistent task panel inline in Claude conversations using MCP Apps (SEP-1865). The spec is solid. The SDK is solid. But I hit two bugs that cost me most of a weekend each, and neither is documented anywhere I could find. Writing them up here in case they save someone else the time.

Bug 1: resourceUri has two valid-looking locations, and only one works

MCP Apps needs a way to tell the host "render this resource as a UI for this tool call." That pointer lives in _meta.ui.resourceUri. The question is: meta on what?

I started with a parameterized resource template, ui://wingman/panel/{plan_name}, registered per plan. That was my first mistake. Parameterized templates get listed under resources/templates/list, not resources/list, and hosts do not prefetch or render anything from the templates list. The fix was straightforward once I found it: register one static resource, ui://wingman/panel, and pass the actual plan data through structuredContent on the tool result instead of baking it into the URI.

That fix surfaced the real bug. My show_plan tool was returning a plain Python dict:

return {
    "plan": plan_data,
    "_meta": {"ui": {"resourceUri": "ui://wingman/panel"}}
}

This looks correct. It is not. FastMCP's result conversion takes a returned dict and serializes the whole thing into structuredContent, verbatim, including any _meta key the dict happens to carry. So the actual wire result looked like this:

result.structuredContent["_meta"]["ui"]["resourceUri"]  # == "ui://wingman/panel", but wrong place
result.meta  # None — this is what the host actually reads

MCP Apps hosts read resourceUri off the top-level _meta on the CallToolResult, not off whatever ended up inside structuredContent. With that pointer effectively missing, the host had nowhere to bind the iframe. The visible symptom was strange: actions in the UI would update on screen but nothing persisted. The panel was rendering against the wrong contract entirely, but it rendered well enough to look like a smaller bug.

The fix is to stop returning a dict and return a CallToolResult directly, with _meta set on the result object itself:

from mcp.types import CallToolResult, TextContent

return CallToolResult(
    content=[TextContent(type="text", text=summary)],
    structuredContent={"plan": plan_data},
    _meta={"ui": {"resourceUri": "ui://wingman/panel"}},
)

FastMCP's lowlevel handler passes a returned CallToolResult through unchanged, so the top-level _meta survives intact. I added a regression test that asserts on result.meta directly, not on anything inside structuredContent, so this can never silently regress again.

If you are building an MCP App and using a framework that lets you return a plain dict from a tool, check exactly where that framework puts a _meta key you pass in. There are two plausible-looking destinations and only one of them is real.

Bug 2: CSS specificity quietly killed three "fixed" bugs at once

After fixing the resourceUri issue, I still had three visible UI bugs in the host: the empty state showed even when tasks existed, the three-dot menu would not close on a second click, and it would not close on click-outside either.

I went through the JavaScript line by line. The toggle logic was correct. The empty-state gate (tasks.length === 0) was correct. The click-outside listener was attaching and firing correctly, confirmed with console logging at every step. The DOM hidden attribute was being set exactly when it should be. And the bugs were still visible.

The browser's default stylesheet includes [hidden] { display: none; }, but user-agent stylesheet rules have the lowest possible specificity. Any author-level class selector that sets display wins over it. My stylesheet had:

.empty-state { display: flex; }
.task-list   { display: flex; }
.menu        { display: flex; }

Every one of these elements also got hidden set or removed correctly by JavaScript at the right moments. But the explicit display: flex in each class rule outranked the UA stylesheet's [hidden] rule, so the elements stayed visually displayed regardless of what the hidden attribute said. The JavaScript was never wrong. The DOM state was never wrong. The CSS was just quietly overriding the one thing that was supposed to control visibility.

One line fixed all three reported bugs at once:

[hidden] { display: none !important; }

The lesson generalizes past this one panel: if your JS is setting state correctly, your event listeners are firing correctly, and the bug is still visible, check whether you have a display rule anywhere that outranks [hidden]. Three independent-looking bug reports were one missing CSS line.

Smaller findings, for completeness

Building the v0.2 menu actions (export, delete, clear) surfaced three more iframe sandbox constraints inside MCP Apps hosts that are not called out in the spec docs:

• confirm() fails silently inside the sandboxed iframe. No dialog appears, no error throws. Replace it with an inline confirmation UI in the panel itself.
• navigator.clipboard.writeText is unavailable. For "export as markdown," route the text back through sendMessage so it lands in the chat instead of trying to hit the clipboard.
• Blob and URL.createObjectURL downloads are blocked. Same workaround: surface the content through sendMessage rather than triggering a file download from inside the iframe.

None of these throw errors you can catch cleanly. They just do nothing, which makes them easy to miss in testing and easy to misdiagnose as "my code is wrong" when the real answer is "this API does not exist in this sandbox."

Takeaway

Both of the big bugs shared a shape: the code that looked wrong was fine, and the actual fault was one layer away from where I was looking; a field nested in the wrong container, a stylesheet rule with higher specificity than expected. Worth checking that layer early next time, before assuming the logic is at fault.

Wingman is MIT licensed and on PyPI as wingman-mcp if you want to see the fixes in context: github.com/adeoluwaadesina/wingman-mcp