MCP App Tool and Resource Contract

MCP Apps SDK An MCP App is a normal MCP tool plus a ui:// HTML resource. The tool returns data. The resource renders the UI. The link between them is _meta.ui.resourceUri. Use this page as the server-side contract to check before testing in a host.

Choose the Right Tool Shape

Most MCP App servers have three tool shapes. Use this table before adding metadata:

Tool shape	Model can call	View can call	Renders a View	Required metadata
UI-launching tool	Yes	Usually yes	Yes	`_meta.ui.resourceUri` plus optional `visibility`.
App-only helper tool	No	Yes	No	`_meta.ui.visibility: ["app"]`. `resourceUri` is optional.
Backend-only standard tool	Yes	No	No	No MCP Apps metadata. Use normal MCP tool metadata.

Use UI-launching tools for the actions a user can ask the model to perform, such as “show orders.” Use app-only helper tools for actions the rendered View triggers directly, such as refresh, pagination, autosave, or form submit. Use backend-only tools when the result belongs in the conversation and no UI should render.

Required Pieces for a UI Tool

Piece	Where it appears	What it does
Tool definition	`tools/list`	Gives the model a callable tool with `name`, `description`, `inputSchema`, and optional `outputSchema`.
Tool annotations	`tool.annotations`	Gives hosts safety hints such as read-only, destructive, idempotent, or external-system behavior.
Tool UI metadata	`tool._meta.ui.resourceUri`	Points the host at the HTML resource to render after the tool call.
Resource definition	`resources/list` or tool-linked discovery	Declares the `ui://` resource and `text/html;profile=mcp-app` MIME type.
Resource contents	`resources/read`	Returns the HTML document and any iframe metadata under `contents[]._meta.ui`.
Tool result	`tools/call` result	Returns model-readable `content` and UI-readable `structuredContent`.

MCP Apps are optional. Servers should check the host’s MCP Apps capability before registering UI metadata, then fall back to text-only MCP tools when the host does not support text/html;profile=mcp-app.

Minimal Contract

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE,
} from '@modelcontextprotocol/ext-apps/server';
import { z } from 'zod';

const server = new McpServer({ name: 'orders', version: '1.0.0' });
const resourceUri = 'ui://orders/view.html';

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

registerAppTool(
  server,
  'search-orders',
  {
    title: 'Search Orders',
    description: 'Search orders and display the results.',
    inputSchema: { query: z.string() },
    outputSchema: {
      query: z.string(),
      orders: z.array(z.object({ id: z.string(), total: z.number() })),
    },
    annotations: {
      readOnlyHint: true,
      openWorldHint: false,
    },
    _meta: {
      ui: {
        resourceUri,
        visibility: ['model', 'app'],
      },
    },
  },
  async ({ query }) => {
    const result = {
      query,
      orders: [{ id: 'ord_123', total: 128.5 }],
    };

    return {
      content: [{ type: 'text', text: JSON.stringify(result) }],
      structuredContent: result,
    };
  }
);

Tool Annotations

Use standard MCP annotations to describe what the tool does. Use _meta.ui to describe MCP App behavior such as View linkage and visibility.

Annotation	Use it for	Example
`readOnlyHint`	Tools that do not modify state.	Search, list, preview, load dashboard.
`destructiveHint`	Tools that can delete, overwrite, cancel, charge, or send.	Cancel order, delete record, submit payment.
`idempotentHint`	Tools that are safe to retry with the same arguments.	Save draft by stable id, refresh cache.
`openWorldHint`	Tools that interact with systems outside your backend.	Email, payment, public web, third-party APIs.

Tool visibility and annotations are independent. An app-only helper can still be destructive, and a UI-launching model tool can be read-only.

annotations: {
  readOnlyHint: true,
  openWorldHint: false,
},
_meta: {
  ui: {
    resourceUri: "ui://orders/view.html",
    visibility: ["model", "app"],
  },
}

See Tool Annotations for examples of read-only UI tools, app-only write helpers, and destructive actions.

Tool Metadata

Put UI linkage on the tool, not in the tool result:

_meta: {
  ui: {
    resourceUri: "ui://orders/view.html",
    visibility: ["model", "app"],
  },
}

Field	Requirement	Notes
`_meta.ui.resourceUri`	Required for UI-launching tools	Must match the resource URI exactly. Use `ui://`. Optional for app-only helpers that do not render a View.
`_meta.ui.visibility`	Optional	Defaults to `["model", "app"]`. Use `["app"]` for UI-only actions.
`_meta["ui/resourceUri"]`	Deprecated	`registerAppTool` writes compatibility metadata for older hosts. New code should use `_meta.ui.resourceUri`.

Resource Contents

The resource is the HTML template. The tool result is the data. Keep them separate so hosts can read, inspect, and cache UI HTML before the tool runs.

{
  contents: [
    {
      uri: "ui://orders/view.html",
      mimeType: "text/html;profile=mcp-app",
      text: html,
      _meta: {
        ui: {
          csp: {
            connectDomains: ["https://api.example.com"],
            resourceDomains: ["https://cdn.example.com"],
          },
          permissions: { clipboardWrite: {} },
          prefersBorder: true,
        },
      },
    },
  ],
}

Field	Requirement	Notes
`uri`	Required	Must match the tool’s `_meta.ui.resourceUri`.
`mimeType`	Required	Use `RESOURCE_MIME_TYPE`, which is `text/html;profile=mcp-app`.
`text` or `blob`	Required	Return a valid HTML document as text or base64 HTML.
`_meta.ui.csp`	Required when loading outside origins	Declare fetch, script, style, font, image, media, and nested iframe origins.
`_meta.ui.permissions`	Optional	Hosts may grant requested browser capabilities, but apps must handle denial.
`_meta.ui.domain`	Optional	Host-specific stable sandbox origin for CORS, OAuth callbacks, or origin-restricted APIs.
`_meta.ui.prefersBorder`	Recommended	Set this explicitly because host defaults vary.

Tool Results

Use both MCP result channels:

return {
  content: [{ type: 'text', text: JSON.stringify(result) }],
  structuredContent: result,
};

Field	Audience	Guidance
`content`	Model and text-only clients	Include a short text summary. For structured results, MCP recommends also serializing the JSON into a text block for compatibility.
`structuredContent`	Host, View, and typed clients	Put the object your UI renders here. If you declare `outputSchema`, this object must match it.
`_meta`	Host or component-only metadata	Use sparingly. Do not rely on it for model-visible facts.
`isError`	Host and model	Set `true` for tool execution errors that should still return a tool result. Use JSON-RPC errors for protocol failures.

App-Only Helper Tools

Set visibility: ["app"] when the View needs a server round trip that the model should not see, such as refresh, pagination, autosave, or form submit. An app-only helper tool may include resourceUri when it belongs to a specific View, but it does not have to. Omitting resourceUri means the helper is callable from the app connection but does not tell the host to render a new iframe when the tool is called.

registerAppTool(
  server,
  'refresh-orders',
  {
    description: 'Refresh order data for the app UI.',
    inputSchema: { query: z.string() },
    _meta: {
      ui: {
        visibility: ['app'],
      },
    },
  },
  async ({ query }) => {
    const result = await searchOrders(query);

    return {
      content: [{ type: 'text', text: JSON.stringify(result) }],
      structuredContent: result,
    };
  }
);

The host must hide app-only tools from the model tool list and reject View calls to tools whose visibility does not include "app".

Server Checklist

Before testing in a real host, verify the server response shape:

Check	Why it matters
`initialize` advertises MCP Apps support	Lets the server decide whether to send UI metadata or fall back to text tools.
`tools/list` includes `_meta.ui`	Gives MCP Apps hosts the `resourceUri` and `visibility` contract.
`resources/read` returns app HTML	Hosts render the returned HTML in a sandboxed iframe.
HTML uses `text/html;profile=mcp-app`	Distinguishes an MCP App View from a plain MCP resource.
CSP lists every external origin	Fetches, scripts, images, fonts, media, and nested iframes are otherwise blocked.
Tool annotations match behavior	Lets hosts apply useful review UI and avoid treating writes as reads.
`outputSchema` matches `structuredContent`	Lets clients validate the typed tool result that the View consumes.
`content` includes text fallback	Keeps text-only MCP clients and older hosts useful.
App-only helpers use `visibility`	Stops the model from calling UI-only actions such as refresh or submit.

Common Failures

Symptom	Likely cause	Fix
The tool runs but no UI appears	Missing or mismatched `_meta.ui.resourceUri`	Check that the tool URI and resource URI are identical.
The iframe is blank	Wrong MIME type or invalid HTML	Use `RESOURCE_MIME_TYPE` and return a full HTML document.
Images, scripts, or fetch calls fail	Missing CSP metadata	Add the origin to `resourceDomains`, `connectDomains`, or `frameDomains`.
The model calls a refresh or pagination tool	Tool is visible to `"model"`	Set `visibility: ["app"]`.
The View receives hard-to-parse text	Tool only returned `content`	Add `structuredContent` and an `outputSchema`.
A text-only host gets unusable output	Tool only returned `structuredContent`	Also return model-readable `content`.

Build an MCP App Server

Complete server example with capability detection and fallback tools.

Add a UI to an MCP Tool

Convert a standard MCP tool into a UI-rendering MCP App.

Tool _meta

Full reference for resource linkage and tool visibility.

Tool Annotations

Add host-facing safety hints to MCP App tools.

Resource _meta

Full reference for CSP, permissions, stable domains, and borders.

​Choose the Right Tool Shape

​Required Pieces for a UI Tool

​Minimal Contract

​Tool Annotations

​Tool Metadata

​Resource Contents

​Tool Results

​App-Only Helper Tools

​Server Checklist

​Common Failures

​Related

Build an MCP App Server

Add a UI to an MCP Tool

Tool _meta

Tool Annotations

Resource _meta

Choose the Right Tool Shape

Required Pieces for a UI Tool

Minimal Contract

Tool Annotations

Tool Metadata

Resource Contents

Tool Results

App-Only Helper Tools

Server Checklist

Common Failures

Related