MCP App Tool Metadata: resourceUri, visibility, and App-Only Tools

Most MCP App rendering bugs start before React mounts.

The model calls a tool. The host looks at the tool metadata. If the tool points at a missing ui:// resource, the iframe never loads. If the visibility is wrong, the model can see a tool it should not call, or the app cannot call a tool it needs for pagination, validation, or submit actions.

That small _meta.ui object is the routing table for your app.

TL;DR: Use _meta.ui.resourceUri to link a tool to the UI resource the host should render. Use _meta.ui.visibility to decide whether the model, the rendered app, or both can call the tool. Prefer the standard MCP Apps fields for new cross-host apps. Add ChatGPT compatibility keys only when you need to support older ChatGPT Apps SDK behavior. Test the metadata with tools/list and resources/read before debugging your frontend.

The Tool Metadata Fields That Matter

For a UI-capable MCP tool, the important fields are:

Field	Goes on	Purpose
_meta.ui.resourceUri	Tool descriptor	Points at the ui:// resource to render
_meta.ui.visibility	Tool descriptor	Controls model vs app access
_meta["openai/outputTemplate"]	Tool descriptor	ChatGPT compatibility alias for the UI resource URI
_meta["openai/widgetAccessible"]	Tool descriptor	Older ChatGPT compatibility flag for widget-to-tool calls
_meta["openai/visibility"]	Tool descriptor	Older ChatGPT compatibility visibility field

The first two are the standard MCP Apps fields. The OpenAI-specific keys are useful when you need compatibility with older ChatGPT Apps SDK examples or host behavior, but they should not be the center of a new cross-host implementation.

The OpenAI Apps SDK reference now says to prefer _meta.ui.resourceUri for linking a tool to a UI template, with _meta["openai/outputTemplate"] as an optional compatibility alias. The MCP Apps reference defines the portable shape: resourceUri?: string and visibility?: ("model" | "app")[].

resourceUri Links a Tool to a View

_meta.ui.resourceUri tells the host which resource to render when a tool runs.

import { registerAppTool } from '@modelcontextprotocol/ext-apps/server';
import { z } from 'zod';

registerAppTool(
  server,
  'get-weather',
  {
    title: 'Get Weather',
    description: 'Get current weather for a location',
    inputSchema: {
      location: z.string(),
    },
    _meta: {
      ui: {
        resourceUri: 'ui://weather/view.html',
      },
    },
  },
  async ({ location }) => {
    const forecast = await getForecast(location);

    return {
      content: [{ type: 'text', text: `Displayed weather for ${location}.` }],
      structuredContent: forecast,
    };
  },
);

That URI must match a resource your MCP server registers. The host flow is:

1. The host lists tools and sees _meta.ui.resourceUri.
2. The host reads the matching ui:// resource.
3. The host renders that HTML in a sandboxed iframe.
4. The host passes tool input and tool output into the resource.

If the resource URI is wrong, the backend tool may still return valid data, but the app UI will not render. This is why resourceUri belongs in your first test layer, before E2E tests.

The sunpeak Tool File Version

In sunpeak projects, you usually do not write resourceUri by hand. You link a tool file to a resource directory with the resource field:

// src/tools/get-weather.ts
import { z } from 'zod';
import type { AppToolConfig, ToolHandlerExtra } from 'sunpeak/mcp';

export const tool: AppToolConfig = {
  resource: 'weather',
  title: 'Get Weather',
  description: 'Get current weather for a location',
  annotations: { readOnlyHint: true },
  _meta: {
    ui: {
      visibility: ['model', 'app'],
    },
  },
};

export const schema = {
  location: z.string().describe('City and region, such as Chicago, IL'),
};

type Args = z.infer<z.ZodObject<typeof schema>>;

export default async function (args: Args, _extra: ToolHandlerExtra) {
  const forecast = await getForecast(args.location);

  return {
    content: [{ type: 'text' as const, text: `Displayed weather for ${args.location}.` }],
    structuredContent: forecast,
  };
}

resource: 'weather' maps to src/resources/weather/. sunpeak generates and registers the corresponding MCP App resource URI during build and dev. You still control visibility through _meta.ui.visibility.

That split is useful. Application code stays simple, while generated server output still uses standard MCP Apps metadata.

visibility Controls Who Can Call the Tool

_meta.ui.visibility accepts an array with "model", "app", or both.

Value	Meaning	Good for
["model", "app"]	The model can call it and the rendered app can call it	Search, display, refresh, and read actions
["model"]	Only the model can call it	Conversation-driven tools the UI should never trigger
["app"]	Only the rendered app can call it	Pagination, polling, validation, draft saves, confirmed button actions

If you omit visibility, the default is usually ["model", "app"]. That is a fine default for simple tools, but it becomes too broad as your app grows.

App-only tools are the pattern many developers miss.

Imagine an invoice viewer. The model should call show-invoices when the user asks for invoices. The UI should call load-more-invoices when the user clicks “Next page.” The model does not need to see that pagination tool, and hiding it reduces tool-list noise.

export const tool: AppToolConfig = {
  title: 'Load More Invoices',
  description: 'Load the next page of invoices for the current invoice view',
  annotations: { readOnlyHint: true },
  _meta: {
    ui: {
      visibility: ['app'],
    },
  },
};

Then the resource calls the tool from the UI:

import { useCallServerTool, useToolData } from 'sunpeak';

interface InvoicePage {
  invoices: Array<{ id: string; customer: string; total: string }>;
  nextCursor?: string;
}

export function InvoiceResource() {
  const { output } = useToolData<unknown, InvoicePage>();
  const callServerTool = useCallServerTool();

  if (!output) return null;

  async function loadMore() {
    if (!output.nextCursor) return;

    await callServerTool({
      name: 'load-more-invoices',
      arguments: {
        cursor: output.nextCursor,
      },
    });
  }

  return (
    <button onClick={loadMore} disabled={!output.nextCursor}>
      Next page
    </button>
  );
}

That keeps the user workflow interactive without giving the model a low-level paging tool it does not need.

A Practical Visibility Model

Use this rule when designing tools:

If the tool answers a user request, make it model-visible. If the tool handles a UI event after the app is already open, make it app-visible. If both paths are valid, expose it to both.

Common patterns:

Tool	Visibility	Why
show-dashboard	["model", "app"]	The model opens it, and the app may refresh it
load-dashboard-page	["app"]	Pagination is a UI concern
validate-form-field	["app"]	The model should not call field validation directly
submit-review-decision	["app"]	The UI calls it after a user clicks confirm or cancel
explain-report	["model"]	The model uses it in conversation, not the iframe

For write actions, visibility is not enough by itself. You still need server-side auth, input validation, idempotency where possible, and explicit user confirmation for risky work. Tool visibility reduces accidental exposure. It does not replace authorization.

ChatGPT Compatibility Keys

Older ChatGPT Apps SDK examples often use keys like:

_meta: {
  'openai/outputTemplate': 'ui://weather/view.html',
  'openai/widgetAccessible': true,
}

For new MCP Apps, prefer:

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

If you need compatibility with older ChatGPT behavior, you can include both fields with the same URI:

_meta: {
  ui: {
    resourceUri: 'ui://weather/view.html',
    visibility: ['model', 'app'],
  },
  'openai/outputTemplate': 'ui://weather/view.html',
  'openai/widgetAccessible': true,
}

Keep one source of truth. If the standard resourceUri and the OpenAI alias point at different resources, debugging gets messy fast because each host may pick a different path.

The same idea applies to visibility. Prefer _meta.ui.visibility. Only add _meta["openai/visibility"] when you are targeting a host path that still needs it.

What Does Not Belong on Tool Metadata

Do not put iframe security settings on the tool.

These belong on resource metadata:

• CSP domains, such as connectDomains, resourceDomains, and frameDomains
• Browser permissions, such as camera, microphone, geolocation, and clipboard write
• Stable sandbox domains
• Border and framing hints

The tool answers “what can be called, and which UI should appear?” The resource answers “how should this iframe be rendered and sandboxed?”

That separation matters because multiple tools can share one resource. If show-cart, apply-discount, and refresh-cart all render ui://shop/cart.html, the CSP should live with the cart resource, not be duplicated across every tool.

Test Tool Metadata Before the Browser

A conformance test catches metadata bugs faster than a rendered UI test.

import { test, expect } from 'sunpeak/test';

test('ui tools point at readable app resources', async ({ mcp }) => {
  const tools = await mcp.listTools();
  const appTools = tools.filter((tool) => tool._meta?.ui?.resourceUri);

  expect(appTools.length).toBeGreaterThan(0);

  for (const tool of appTools) {
    const ui = tool._meta?.ui;

    expect(ui?.resourceUri).toMatch(/^ui:\/\//);
    expect(ui?.visibility ?? ['model', 'app']).toEqual(expect.arrayContaining(['model']));

    const resource = await mcp.readResource(ui.resourceUri);
    expect(resource.contents).toHaveLength(1);
    expect(resource.contents[0].mimeType).toBe('text/html;profile=mcp-app');
  }
});

For app-only tools, test the other direction:

test('app-only tools are marked app visible', async ({ mcp }) => {
  const tools = await mcp.listTools({ includeAppOnly: true });
  const loadMore = tools.find((tool) => tool.name === 'load-more-invoices');

  expect(loadMore?._meta?.ui?.visibility).toEqual(['app']);
});

Your exact test harness may expose model-visible and app-visible tool lists differently. The intent is what matters: assert the metadata contract directly, then run browser tests after that passes.

Debugging Checklist

When an MCP App or ChatGPT App tool runs but no UI appears, check these in order:

1. The tool appears in tools/list.
2. The tool has _meta.ui.resourceUri.
3. The URI starts with ui://.
4. The URI matches a registered resource.
5. resources/read returns HTML for that URI.
6. The resource MIME type is text/html;profile=mcp-app.
7. CSP and permissions are on the resource, not the tool.
8. App-only tools include "app" in _meta.ui.visibility.
9. Model-only tools include "model" and are not expected to be called from the iframe.
10. ChatGPT compatibility aliases, if present, point at the same resource as _meta.ui.resourceUri.

If those checks pass, move to frontend debugging: console errors, bridge initialization, useToolData() shape, display mode layout, and CSP-blocked network calls.

Where sunpeak Helps

You can write all of this by hand with the MCP Apps SDK. For production apps, the hard part is keeping it correct as tools and resources change.

sunpeak keeps the common path short:

• resource: 'weather' links a tool file to src/resources/weather/.
• _meta.ui.visibility stays available when you need explicit model vs app access.
• The inspector lets you run tools and inspect tool metadata locally.
• The mcp fixture lets you test tools/list, resources/read, and tool results in CI.

That means you can treat tool metadata as a contract, not a thing you inspect manually after ChatGPT or Claude fails to render a card.

Start with the MCP App framework if you are building a portable app, or use the testing framework if you already have an MCP server and want metadata checks in CI.