MCP Apps

The MCP Apps helpers in @ai-sdk/mcp help an MCP host advertise UI support, keep model-visible and app-visible tools separate, and read ui:// HTML resources for rendering.

Import

import {
MCP_APP_MIME_TYPE,
mcpAppClientCapabilities,
readMCPAppResource,
splitMCPAppTools,
} from "@ai-sdk/mcp"

MCP_APP_MIME_TYPE

The MIME type for HTML resources that should be rendered as MCP Apps.

const MCP_APP_MIME_TYPE = 'text/html;profile=mcp-app';

mcpAppClientCapabilities

Client capabilities to pass to createMCPClient when your host supports MCP Apps.

import { createMCPClient, mcpAppClientCapabilities } from '@ai-sdk/mcp';

const client = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://example.com/mcp',
  },
  capabilities: mcpAppClientCapabilities,
});

The advertised capability is:

{
  "extensions": {
    "io.modelcontextprotocol/ui": {
      "mimeTypes": ["text/html;profile=mcp-app"]
    }
  }
}

splitMCPAppTools()

Splits MCP tool definitions into model-visible tools and app-visible tools.

Tools without MCP Apps visibility metadata remain model-visible. Tools whose _meta.ui.visibility includes "app" are returned in appVisible.

const definitions = await client.listTools();
const { modelVisible, appVisible } = splitMCPAppTools(definitions);

const tools = client.toolsFromDefinitions(modelVisible);

Parameters

• definitions (ListToolsResult): The tool definitions returned by client.listTools().

Returns

• modelVisible (ListToolsResult): Tool definitions that can be exposed to the language model.
• appVisible (ListToolsResult): Tool definitions that can be called by an MCP App through the host bridge.

readMCPAppResource()

Reads a ui:// resource from an MCP server and normalizes it into HTML plus rendering metadata.

const resource = await readMCPAppResource({
  client,
  uri: 'ui://example/dashboard',
});

The helper validates that the URI starts with ui://, requires the text/html;profile=mcp-app MIME type, and supports resource contents returned as either text or base64 blob data.

Parameters

• client (Pick<MCPClient, 'readResource'>): The MCP client used to read the resource.
• uri (string): The ui:// resource URI to read.
• options? (RequestOptions): Optional request options, such as an abort signal or timeout.

Returns

Returns a Promise<MCPAppResource>.

• uri (string): The ui:// resource URI.
• mimeType ('text/html;profile=mcp-app'): The MCP Apps HTML MIME type.
• html (string): The app HTML to render in a sandboxed iframe.
• meta? (MCPAppResourceMeta): Rendering metadata from resource _meta.ui, such as CSP, permissions, and prefersBorder.

See Also

• MCP Apps guide
• createMCPClient