MCP App metadata and resources

Use this guide when building an MCP server or a host that displays its views through MCP Gateway. For the product workflow, see Use MCP Apps.

What a server supplies

A server declares the relationship between a tool and its view in the tool definition:

{
  "name": "show_report",
  "description": "Show an interactive report",
  "inputSchema": { "type": "object", "properties": {} },
  "_meta": {
    "ui": {
      "resourceUri": "ui://reports/main",
      "visibility": ["model", "app"]
    }
  }
}

This example is a provider definition, not a Registry create request. The server must also answer MCP resources/read for that URI with HTML of MIME type text/html;profile=mcp-app. Resource metadata can declare CSP origins and optional browser permissions. A ui:// URI is a protocol identifier; it is not a public URL for the browser to fetch directly.

What the gateway stores

Discovery and catalog refresh preserve the supported UI declaration in the existing mcp_tool artifact. The wire definition’s _meta.ui is stored under metadata.meta.ui in the Registry artifact representation, alongside the tool’s existing name, schema, description and annotations. The catalog also records the owning server and endpoint provenance. The gateway stores bounded, supported metadata rather than every provider _meta namespace. It fetches UI HTML from the owning MCP server on demand; it does not persist that HTML as a new Registry artifact. No separate App artifact or uploaded HTML bundle is required. A server can offer multiple views, and tools on that server can share a resource. Use the server’s catalog refresh workflow when declarations change. A saved REST catalog is a discovery projection; authenticated MCP discovery is authoritative for what a client can currently call. Refreshing the catalog does not grant access or connect a user’s provider account.

How clients read resources

Connection	Resource behavior
Aggregate MCP at `/mcp`	The gateway advertises owner-specific App resource URIs. It supplies a wrapper that renders the provider HTML and routes supported callbacks to the owning server.
Server-scoped MCP at `/mcp/v1/servers/{server_id}/mcp`	Preserves the server’s native tool names and `ui://` resource URIs. Reads are authorized against that server.
Browser host using the public API	Reads the catalog-bound resource through the authenticated endpoint below. The caller cannot supply an arbitrary URI or URL.

For a browser host such as Studio, the public API exposes:

GET /mcp/v1/servers/{server_id}/tools/{tool_id}/app-resource
Authorization: Bearer <token>

Use your existing API authentication. The response contains server_id, tool_id, resource_uri, mime_type, html, and optional meta with resource policy declarations. Find mcp.readToolAppResource in the MCP section of the Public API for the published response schema and errors. The read checks caller access, the current tool declaration and owning endpoint, then resolves the provider credential. This endpoint returns source data; it neither runs the tool nor renders the App. Provider credentials stay at the gateway.

Treat html as untrusted code. Never insert it into your application’s page. A host needs an isolated MCP Apps sandbox, policy validation and a bridge that explicitly limits supported operations. The resource-read API does not supply these protections to a custom renderer automatically.

Rendering and callbacks

Clients may preload the resource before execution. Only successful native execution creates the short-lived context used for aggregate callbacks. That context binds the caller, organization, session, server, tool, resource and policy; possessing it does not grant permission. Never construct or persist those handles as durable App links.

Compatibility and limits

The aggregate bridge supports rendering, tool input and result delivery, authorized tool callbacks, host context, resizing and supported inline/expanded display modes. It does not forward App resource reads or listing, tool listing, model-context updates, messages, links or downloads. Optional camera, microphone, location and clipboard permissions are denied, reported through hostCapabilities.sandbox.permissions as an empty object. Providers must feature-detect the host’s capabilities. An App that requires an unsupported operation needs additional compatibility work; registering its server is not sufficient.

Bound	Limit
Supported metadata or resource policy	16 KiB
UI HTML	2 MiB
Transport payload	8 MiB
Aggregate view lifetime	At most five minutes, also bounded by identity expiry
Live aggregate views per principal	32

Studio uses a separately hosted sandbox. External clients use their own renderer and sandbox. Failures to prepare the App preserve a successful tool result; no original operation is replayed automatically. An expired view or changed bridge revision can require a new native entry call. Check whether that operation changes data before repeating it.

CLI

SDK

MCP

API

MCP App metadata and resources

What a server supplies

What the gateway stores

How clients read resources

Rendering and callbacks

Compatibility and limits

​What a server supplies

​What the gateway stores

​How clients read resources

​Rendering and callbacks

​Compatibility and limits

What a server supplies

What the gateway stores

How clients read resources

Rendering and callbacks

Compatibility and limits