@apify/mcp-widgets

React components that render the output of Apify MCP tools. One source for every host: Apify Console renders them in its own React tree, the Apify MCP server bundles them into the HTML it serves to MCP Apps hosts (Claude, ChatGPT).

Install

pnpm add @apify/mcp-widgets

Peer dependencies: react, react-dom, styled-components. The components build on @apify/ui-library, so the tree must also be wrapped in its UiDependencyProvider.

Usage

Components take the tool's structuredContent as props and reach the environment through WidgetHostProvider:

import { ActorSearchWidget, WidgetHostProvider } from '@apify/mcp-widgets';

<WidgetHostProvider host={{ openLink: (url) => window.open(url, '_blank', 'noopener') }}>
    <ActorSearchWidget output={toolResult.structuredContent} />
</WidgetHostProvider>;

ActorRunWidget only renders what it is given. LiveActorRunWidget keeps a run fresh on its own through the host's callTool, starting from as little as { runId }.

WidgetHost has one required member, openLink. requestDisplayMode, maxHeight, isInPage and callTool are optional: hosts with a single display mode, no height limit, an iframe of their own or no way to call MCP tools leave them out.

Exports: ActorSearchWidget, ActorRunWidget, LiveActorRunWidget, ActorSearchDetail, ActorCard, ActorSearchResultsSkeleton, ActorSearchDetailSkeleton, WidgetLayout, SkeletonBlock, WidgetHostProvider, useWidgetHost and the tool output types. Test ids for Playwright live under @apify/mcp-widgets/test-ids.

Development

Inside the apify-core monorepo:

pnpm run storybook                        # shared Storybook, section "MCP-Widgets"
pnpm --filter @apify/mcp-widgets test     # unit tests
pnpm --filter @apify/mcp-widgets build    # dist/ (components + d.ts)