Building an MCP App: declarations, sandbox and text fallbacks

October 24, 2026 · Part 25 of 35

An MCP App is an interactive view that a Model Context Protocol (MCP) server puts into the conversation. Building one turned out to be mostly declarations: a page, a tool that points at it, and the few domains the page may reach. The host does the enforcing. What I’d hold onto is the plain part: a tool with a view still has to answer in text, because some hosts will never draw it.

This is part 25 of my series on what an MCP server does under the 2026-07-28 specification. Part 24 showed how an app’s user interface (UI) reaches the screen, and this one is the builder’s side. The facts are as I read them in October 2026.

In brief

1. The server declares and the host enforces. It declares a ui:// HyperText Markup Language (HTML) resource served as text/html;profile=mcp-app, a tool whose _meta.ui.resourceUri points at it, and the domains its view may reach.
2. visibility decides who may call a tool, so a tool marked ["app"] serves the view’s buttons without ever reaching the model’s tool list.
3. Tools MUST return meaningful content even when a UI is available, and servers SHOULD give text-only hosts a fallback.
4. Web hosts run the view in two iframes, on a different origin from the host, under a Content Security Policy (CSP) that can be tightened but never loosened.
5. My advice: ship one self-contained HTML file, have the view call your tools rather than your application programming interfaces (APIs), and test every tool in a text-only host.

What the server declares

The UI resource

An MCP App starts with a resource whose Uniform Resource Identifier (URI) names a page. The MCP Apps specification sets four rules for it:

The resource’s own _meta.ui says what the page needs from its sandbox:

The tool link

A tool points at its page with _meta.ui.resourceUri, and _meta.ui.visibility says who may call it:

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "inputSchema": { "type": "object", "properties": { "location": { "type": "string" } } },
  "_meta": { "ui": { "resourceUri": "ui://weather-server/dashboard", "visibility": ["model", "app"] } }
}

The older flat key, _meta["ui/resourceUri"], is deprecated. Use _meta.ui.resourceUri.

Results for two audiences

A UI-enabled tool’s result has two readers, as part 8 set out:

Tools MUST return meaningful content even when a UI is available, and servers SHOULD provide text-only fallback behaviour for every UI-enabled tool.

Keeping structuredContent from the model is only a convention: Claude Code and its Agent software development kit (SDK) pass it to the model in place of the text blocks of content, and ChatGPT lets the model see it. My advice, as in part 8: write each half to stand on its own.

In Python

The official Python SDK, mcp 2.3.0, has MCP Apps built in. First the page, declaring the one origin its script comes from:

from mcp.server import MCPServer
from mcp.server.apps import Apps, ResourceCsp, client_supports_apps
from mcp.server.mcpserver import Context
from mcp.types import CallToolResult, TextContent

SALES = {"north": 1200, "south": 950}
UI = "ui://sales/dashboard.html"
apps = Apps()

apps.add_html_resource(
    UI,
    """<!doctype html>
<html><head><meta charset="utf-8"><title>Sales</title></head>
<body><div id="app">Loading sales...</div>
<script type="module" src="https://cdn.example.com/sales-view.js"></script>
</body></html>""",
    csp=ResourceCsp(resource_domains=["https://cdn.example.com"]),
    prefers_border=True,
)

Then the tool linked to the page. When client_supports_apps(ctx) is False (the client didn’t declare Apps support), it puts every figure in its text. A second, app-only tool serves the view’s clicks:

@apps.tool(resource_uri=UI)
def get_sales(ctx: Context) -> CallToolResult:
    """Sales by region for this quarter."""
    total = sum(SALES.values())
    if not client_supports_apps(ctx):
        lines = [f"{region}: {amount}" for region, amount in SALES.items()]
        text = f"Sales this quarter: {total}.\n" + "\n".join(lines)
        return CallToolResult(content=[TextContent(type="text", text=text)])
    summary = f"Sales this quarter: {total}, shown in the dashboard."
    return CallToolResult(
        content=[TextContent(type="text", text=summary)],
        structured_content={"regions": SALES},
    )


@apps.tool(resource_uri=UI, visibility=["app"])
def get_region_detail(region: str) -> str:
    """Details for one region, for the dashboard's click handler."""
    return f"{region}: {SALES[region]}"


mcp = MCPServer("sales", extensions=[apps])

A client declares Apps support by advertising the extension with its media type. The in-memory Client below connects once that way, like an Apps host, and once without, like a text-only host:

import anyio
from mcp import Client
from mcp.client import advertise

APPS = advertise("io.modelcontextprotocol/ui", {"mimeTypes": ["text/html;profile=mcp-app"]})


async def main():
    async with Client(mcp, extensions=[APPS]) as client:
        result = await client.call_tool("get_sales", {})
        print("apps host:", result.content[0].text, result.structured_content)
    async with Client(mcp) as client:
        result = await client.call_tool("get_sales", {})
        print("text host:", repr(result.content[0].text), result.structured_content)


anyio.run(main)

apps host: Sales this quarter: 2150, shown in the dashboard. {'regions': {'north': 1200, 'south': 950}}
text host: 'Sales this quarter: 2150.\nnorth: 1200\nsouth: 950' None

In an Apps host the text is shorter but still answers with the total, and the view below tells the model which region the user picks.

The SDK writes _meta.ui on the tools and the page for you, and serves the page as text/html;profile=mcp-app. It raises a ValueError for a URI that isn’t ui://, and building the MCPServer raises one if a tool points at a page you didn’t register. It still lists the app-only tool in tools/list: hiding it from the model is the host’s job.

What the view does

The view is the page, and it talks only to the host:

A click can then call an app-only tool. The host checks visibility and policy, and may ask the user, before forwarding it:

The view runs in the browser, so here it’s TypeScript. The App class of @modelcontextprotocol/ext-apps 2.0.3 does the handshake in connect() and turns on the size notifications. The tool’s result arrives as the toolresult event, the ui/notifications/tool-result message of part 24:

import { App } from "@modelcontextprotocol/ext-apps";

const root = document.getElementById("app")!;
const detailLine = document.createElement("p");
const app = new App(
  { name: "Sales dashboard", version: "1.0.0" },
  { availableDisplayModes: ["inline", "fullscreen"] },
);

function render(regions: Record<string, number>) {
  root.replaceChildren(detailLine);
  for (const [region, amount] of Object.entries(regions)) {
    const button = document.createElement("button");
    button.textContent = `${region}: ${amount}`;
    button.onclick = async () => {
      const detail = await app.callServerTool({ name: "get_region_detail", arguments: { region } });
      const [block] = detail.content;
      if (detail.isError || block?.type !== "text") return;
      detailLine.textContent = block.text;
      await app.updateModelContext({
        content: [{ type: "text", text: `The user selected the ${region} region.` }],
      });
    };
    root.append(button);
  }
}

// Register handlers before connecting, so the tool result isn't missed.
app.addEventListener("toolresult", (result) => {
  const data = result.structuredContent as { regions?: Record<string, number> } | undefined;
  if (data?.regions) render(data.regions);
});
app.onteardown = async () => ({});

await app.connect();

How hosts contain it

Hosts contain the view in three ways:

On the web, the view sits in an inner iframe inside a sandbox proxy on a different origin from the host:

The security model, in short:

Part 21 places UI phishing in the wider threat model.

Where it runs, and how I’d build one

In October 2026, the official extension support matrix lists MCP Apps support in Claude (web) and Claude Desktop, ChatGPT, VS Code GitHub Copilot, Microsoft 365 Copilot, Cursor, Goose, Postman, MCPJam, Archestra.AI and PostHog Code. Claude Code runs in a terminal, so it filters ui:// resources out of its resource suggestions instead of rendering them.

The rules above are the specification’s. My advice goes further:

• The app SDK is a convenience. @modelcontextprotocol/ext-apps provides it, with React hooks and an App Bridge for hosts, but you can speak the postMessage protocol directly. Starter templates exist for React, Vue, Svelte, Preact, Solid and vanilla JavaScript.
• Ship one self-contained HTML file, bundled with Vite and a single-file plugin. Every external script needs resourceDomains, and every API call connectDomains; my sample loads its script from another origin only to show the declaration.
• Call tools, not APIs. The host relays the view’s tool calls over the server’s existing authorized connection, which avoids CORS, CSP and auth problems.
• Prefer small frameworks, such as Svelte or vanilla views. Heavy runtimes such as Blazor WebAssembly are likely a poor fit for inline widgets: they’re large to download, and compiling WebAssembly needs a wasm-unsafe-eval script source the spec’s default CSP doesn’t include.
• Degrade cleanly. Test every UI-enabled tool in a text-only host. If the answer isn’t useful as plain text, the tool isn’t finished.
• Pick the right jobs: exploring complex data, configuration with many interdependent options, rich media viewers, live monitoring, and multi-step workflows such as approvals or triage.

Before you submit an app, try it outside a host. My survey of MCP testing tools lists the emulators, previews and audits for that.

Method and caveats

• Built from my guide’s chapter on MCP Apps, written against the 2026-07-28 specification and the MCP Apps specification of 2026-01-26. Host support is as of October 2026.
• The Python sample ran against mcp 2.3.0 on 9 October 2026 and printed the output above. The notes on what the SDK writes and checks come from the package’s source and a short probe. The sales figures and cdn.example.com are placeholders.
• The TypeScript view was type-checked with tsc --noEmit (TypeScript 7.0.2, @modelcontextprotocol/ext-apps 2.0.3), skipping library checks because one dependency expects Node’s types, but not run in a host.
• Where the hosts’ documentation, read on 8 October 2026, is more precise than my notes (some hosts do pass structuredContent to the model), this article follows it.