Build an MCP App

​

How OpenWork runs tools inside an App

​

Supported host protocol

• After initialization, the host sends complete ui/notifications/tool-input arguments before ui/notifications/tool-result. Result delivery retains content, structuredContent, _meta, and the optional isError flag, including explicit false.
• Eligible dashboard refreshes use notification updates in that same document: ordered input/result delivery updates the data without another initialization. App result handlers must accept subsequent results rather than treating the first result as the only one.
• Writable Apps advertise serverTools and openLinks. Tool calls retain the originating endpoint, workspace, session, engine (when supplied), and live launch lease through dispatch. Automatic read-only helpers are allowed; writes require the recent single-use trusted interaction described above, without an additional host confirmation. OpenWork’s sandbox proxy verifies the interaction and overwrites request _meta["openwork/userInteraction"]; an App cannot authorize itself by supplying that field. Link requests require an active writable view, use the host’s HTTP(S)-only opener, and report failures.
• Only inline display is available. Valid ui/request-display-mode requests return the current inline mode, including requests for fullscreen or picture-in-picture; they do not change the layout.
• Size notifications adjust the inline height within host limits. Unmount retains the existing bounded ui/resource-teardown handshake and bridge close.
• Message/context writes, View-provided tools, and resource proxy requests are not supported by this renderer. Unsupported requests receive protocol errors, not successful empty responses. There is no full progress or cancellation forwarding.

​

Provider data and gateway additions

​

Requirements OpenWork checks

• The tool’s _meta.ui.resourceUri is a string starting with ui://.
• If _meta.ui.visibility is set, it includes "app".
• resources/read for that URI returns exactly one content item with mimeType text/html;profile=mcp-app, at most 768 KiB.
• Optional _meta.ui.csp on the resource supports connectDomains, resourceDomains, frameDomains, and baseUriDomains: HTTPS origins only, up to 16 each. permissions and domain are not supported; OpenWork rejects a resource containing either.
• The server is reachable over HTTP(S) as a remote Streamable HTTP MCP server. Local stdio servers cannot be added as an organization connection.
• Mark read-only tools with annotations: { readOnlyHint: true } and do not mark them destructive. Helpers with this annotation and without destructiveHint: true can run automatically in an active writable App. Other helper calls require a recent single-use trusted click. Launch tools without the read-only annotation, or with destructiveHint: true, run only on request.
• OpenWork uses the tool’s title, or annotations.title, as the App’s name.

​

Example: a Team budget widget

import express from "express";
import { readFile } from "node:fs/promises";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";

const server = new McpServer({ name: "team-budget", version: "1.0.0" });
const html = await readFile(new URL("./view.html", import.meta.url), "utf8");

registerAppResource(
  server,
  "budget-view",
  "ui://team-budget/view.html",
  { mimeType: RESOURCE_MIME_TYPE },
  async () => ({
    contents: [{
      uri: "ui://team-budget/view.html",
      mimeType: RESOURCE_MIME_TYPE,
      text: html,
    }],
  }),
);

registerAppTool(
  server,
  "get_budget",
  {
    title: "Team budget",
    description: "Current budget allocation by team",
    inputSchema: {},
    annotations: { readOnlyHint: true },
    _meta: { ui: { resourceUri: "ui://team-budget/view.html" } },
  },
  async () => {
    const data = { teams: [
      { name: "Engineering", percent: 42 },
      { name: "Sales", percent: 33 },
      { name: "Operations", percent: 25 },
    ] };
    return {
      content: [{ type: "text", text: JSON.stringify(data) }],
      structuredContent: data,
    };
  },
);

const app = express();
app.use(express.json());
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
await server.connect(transport);
app.all("/mcp", (req, res) => transport.handleRequest(req, res, req.body));
app.listen(3000);

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Team budget</title>
    <style>
      body { font: 14px system-ui; margin: 0; padding: 16px; color: #18181b; }
      h2 { font-size: 16px; margin: 0 0 16px; }
      .team { display: grid; grid-template-columns: 100px 1fr 40px; gap: 8px; margin: 10px 0; }
      .track { background: #e4e4e7; border-radius: 4px; overflow: hidden; }
      .bar { background: #2563eb; height: 100%; }
      .value { text-align: right; }
    </style>
  </head>
  <body>
    <h2>Team budget</h2>
    <div id="teams">Loading…</div>
    <script type="module">
      import { App } from "@modelcontextprotocol/ext-apps";

      const root = document.querySelector("#teams");
      const render = (data) => {
        root.replaceChildren(...data.teams.map(({ name, percent }) => {
          const row = document.createElement("div");
          row.className = "team";
          row.innerHTML = `<span>${name}</span><span class="track"><span class="bar" style="display:block;width:${percent}%"></span></span><span class="value">${percent}%</span>`;
          return row;
        }));
      };

      const app = new App({ name: "Team budget", version: "1.0.0" });
      app.addEventListener("toolresult", (params) => render(params.structuredContent));
      await app.connect();
    </script>
  </body>
</html>

​

Tips

• Keep the resource self-contained. If it loads remote assets, declare their origins in _meta.ui.csp.
• Return shared result data in structuredContent and readable fallback text in content. Treat both as model-visible; put view-only data in result _meta.
• One tool can drive one view. Ship several tools for several widgets.