MCP App Requirements Checklist

​

1. Negotiate MCP Apps Support

import { getUiCapability, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';

server.server.oninitialized = () => {
  const clientCapabilities = server.server.getClientCapabilities();
  const uiCap = getUiCapability(clientCapabilities);
  const supportsMcpApps = uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE);

  if (supportsMcpApps) {
    registerUiTools();
  } else {
    registerTextFallbackTools();
  }
};

• The fallback tool uses the same core name and behavior where possible.
• Text-only clients receive useful content.
• Your server does not require iframe support for the workflow to succeed.

​

2. Register the UI Resource

import { registerAppResource, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';

const resourceUri = 'ui://orders/view.html';

registerAppResource(
  server,
  'Orders View',
  resourceUri,
  { mimeType: RESOURCE_MIME_TYPE },
  async () => ({
    contents: [
      {
        uri: resourceUri,
        mimeType: RESOURCE_MIME_TYPE,
        text: html,
        _meta: {
          ui: {
            prefersBorder: true,
            csp: {
              connectDomains: ['https://api.example.com'],
              resourceDomains: ['https://cdn.example.com'],
            },
          },
        },
      },
    ],
  })
);

• The resource URI starts with ui://.
• mimeType is RESOURCE_MIME_TYPE, which is text/html;profile=mcp-app.
• The HTML is a complete document with a root node for your app.
• Listing-level resource metadata and content-item metadata do not conflict.
• prefersBorder is set deliberately because host defaults vary.

​

3. Link the Tool to the Resource

registerAppTool(
  server,
  'search-orders',
  {
    title: 'Search Orders',
    description: 'Search orders and display the results.',
    inputSchema: { query: z.string() },
    _meta: {
      ui: {
        resourceUri,
        visibility: ['model', 'app'],
      },
    },
  },
  handler
);

• _meta.ui.resourceUri matches the resource URI exactly.
• Tools that launch a View include "model" in visibility unless they should be app-only.
• App-only helper tools use visibility: ["app"] and are not exposed to the model.
• Backend-only tools omit MCP Apps UI metadata.

​

4. Return the Right Result Channels

return {
  content: [{ type: 'text', text: 'Found 12 matching orders.' }],
  structuredContent: {
    orders,
    nextCursor,
  },
  _meta: {
    cursorToken,
  },
};

• content is short and readable.
• structuredContent contains model-safe data your View renders.
• _meta contains only host or component-only data that the model should not read.
• outputSchema, when present, matches structuredContent.
• Large or sensitive data is fetched through app-only tools or resources instead of being pushed into model context.

​

5. Declare Security Metadata

• Every API origin used by fetch, XHR, EventSource, or WebSocket is in connectDomains.
• Every script, stylesheet, image, font, video, and audio origin is in resourceDomains.
• Every nested iframe origin is in frameDomains.
• Browser permissions such as camera, microphone, geolocation, or clipboardWrite are requested only when needed.
• The View still behaves sensibly if a host denies a permission.
• Any stable domain value is host-specific and is not your own MCP server domain.

​

6. Add Tool Annotations

annotations: {
  readOnlyHint: true,
  openWorldHint: false,
}

• Read tools set readOnlyHint: true.
• Write, send, charge, delete, overwrite, or cancel tools set the right destructive and idempotent hints.
• Tools that reach outside your own backend set openWorldHint correctly.
• Tool descriptions state what the tool does without broad triggering language.

​

7. Wire the View Runtime

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

const app = new App({ name: 'OrdersView', version: '1.0.0' });

app.ontoolinput = ({ arguments: input }) => {
  renderInput(input);
};

app.ontoolresult = (result) => {
  renderOrders(result.structuredContent);
};

app.onhostcontextchanged = (context) => {
  applyTheme(context.theme);
};

await app.connect();

• The View listens for tool input and tool result updates.
• The View adapts to host context such as theme, locale, display mode, and container size.
• The View uses callServerTool() only for tools visible to "app".
• Model-visible UI selections use updateModelContext() or a sunpeak state hook.
• Host-specific APIs are optional branches, not required for the standard MCP App path.

​

8. Test the Contract

npx sunpeak inspect --server http://localhost:8000/mcp
npx sunpeak test

• tools/list shows UI tools with _meta.ui.resourceUri.
• resources/read returns the expected ui:// resource and MIME type.
• Calling the UI tool returns readable content and valid structuredContent.
• The inspector renders the View in both ChatGPT and Claude host modes.
• The View works in light and dark themes.
• App-only tools can be called from the View and stay hidden from the model.
• Live tests cover any host-specific behavior you rely on.

​

Pre-Ship Summary

​

Related Pages