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

Returns

modelVisible:

ListToolsResult

appVisible:

ListToolsResult

`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'>

uri:

string

options?:

RequestOptions

Returns

Returns a Promise<MCPAppResource>.

uri:

string

mimeType:

'text/html;profile=mcp-app'

html:

string

meta?:

MCPAppResourceMeta