MCP Apps

MCP Apps

@ai-sdk/mcp 의 MCP Apps 헬퍼는 MCP 호스트가 UI 지원을 광고하고, 모델에 보이는 tools와 앱에 보이는 tools를 분리하고, 렌더링을 위해 ui:// HTML 리소스를 읽도록 도와줘요.

출처: 문서

본문

Import

<Snippet text={import { MCP_APP_MIME_TYPE, mcpAppClientCapabilities, readMCPAppResource, splitMCPAppTools, } from "@ai-sdk/mcp"} prompt={false} />

MCP_APP_MIME_TYPE

MCP Apps로 렌더링해야 하는 HTML 리소스의 MIME 타입이에요.

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

mcpAppClientCapabilities

여러분의 호스트가 MCP Apps를 지원할 때 createMCPClient 에 전달할 클라이언트 기능이에요.

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

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

광고되는 기능은:

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

splitMCPAppTools()

MCP tool 정의를 모델에 보이는 tools와 앱에 보이는 tools로 나눠요.

MCP Apps 가시성 메타데이터가 없는 tools는 모델에 보이는 상태로 유지돼요. _meta.ui.visibility 에 "app" 이 포함된 tools는 appVisible 로 반환돼요.

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

const tools = client.toolsFromDefinitions(modelVisible);

매개변수 (Parameters)

<PropertiesTable content={[ { name: 'definitions', type: 'ListToolsResult', description: 'The tool definitions returned by client.listTools().', }, ]} />

반환값 (Returns)

<PropertiesTable content={[ { name: 'modelVisible', type: 'ListToolsResult', description: 'Tool definitions that can be exposed to the language model.', }, { name: 'appVisible', type: 'ListToolsResult', description: 'Tool definitions that can be called by an MCP App through the host bridge.', }, ]} />

readMCPAppResource()

MCP 서버에서 ui:// 리소스를 읽고 HTML과 렌더링 메타데이터로 정규화해요.

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

이 헬퍼는 URI가 ui:// 로 시작하는지 검증하고, text/html;profile=mcp-app MIME 타입을 요구하며, 리소스 콘텐츠를 텍스트 또는 base64 blob 데이터로 반환하는 것을 지원해요.

매개변수 (Parameters)

<PropertiesTable content={[ { name: 'client', type: "Pick<MCPClient, 'readResource'>", description: 'The MCP client used to read the resource.', }, { name: 'uri', type: 'string', description: 'The ui:// resource URI to read.', }, { name: 'options', type: 'RequestOptions', isOptional: true, description: 'Optional request options, such as an abort signal or timeout.', }, ]} />

반환값 (Returns)

Promise<MCPAppResource> 를 반환해요.

<PropertiesTable content={[ { name: 'uri', type: 'string', description: 'The ui:// resource URI.', }, { name: 'mimeType', type: "'text/html;profile=mcp-app'", description: 'The MCP Apps HTML MIME type.', }, { name: 'html', type: 'string', description: 'The app HTML to render in a sandboxed iframe.', }, { name: 'meta', type: 'MCPAppResourceMeta', isOptional: true, description: 'Rendering metadata from resource _meta.ui, such as CSP, permissions, and prefersBorder.', }, ]} />

함께 보기 (See Also)

<ExampleLinks examples={[ { title: 'MCP Apps guide', link: '/docs/ai-sdk-core/mcp-apps', }, { title: 'createMCPClient', link: '/docs/reference/ai-sdk-core/create-mcp-client', }, ]} />

더 알아보기 (Learn more)

전체 사이트맵