React and Apps API reference

Public bindings, provider options, and protocol exports.

​

createApp

createApp<Tools extends ToolMap>() from @toolgrain/react returns AppProvider, useToolResult, useToolCall, useHostContext, and useHostActions. It does not read browser globals or connect until mounting.

This reference describes the stable Toolgrain 0.3.0 API. Start with the Vite walkthrough for a runnable project, then add only the hooks your widget uses.

​

AppProvider

Prop	Contract
appInfo	Required nonempty name/version; fixed for the mount
tool	A registered tool name for a separate entry; exclusive with resolveTool
resolveTool	Shared-entry selector receiving result and host context; returns a registered name or undefined
timeoutMs	Positive integer deadline, default 30000 milliseconds
hostOrigin	Optional exact parent origin; default allows opaque sandbox origins
applyHostStyles	Apply/restore host fonts and CSS variables, default true
autoResize	Report size through ResizeObserver when available, default true
availableDisplayModes	Nonempty readonly list of modes this widget supports; default ["inline"], fixed for the mount
children	React component tree sharing this connection

A connection is terminal after closure. Remount to reconnect or change identity/routing. Unmount and teardown remove owned resources. Server rendering does not connect.

​

Hooks

useToolResult(name?) returns status, selected tool name, optional original wire input, full result, and lifecycle/routing error. Without a name, the selected name discriminates the registered tool union. With a name, other active tools appear as waiting.

useToolCall(name) returns call(input, options?), pending, optional full result, and optional error. Options accept AbortSignal and timeoutMs. Explicit tool errors resolve; RPC/transport failures reject. Each hook tracks its latest invocation independently of the initiating result.

useHostContext() returns live AppHostContext. Fields are optional and self-reported by the host.

useHostActions() returns available and stable request functions:

Function	Parameters	Resolved result
openLink	Absolute URL string, optional request options	AppActionResult
sendMessage	AppMessageParams, optional request options	AppActionResult
updateModelContext	AppModelContextParams, optional request options	AppActionResult
requestDisplayMode	AppDisplayMode, optional request options	AppDisplayModeResult

Request options accept signal and timeoutMs; the provider default is 30000 milliseconds. Capability/content checks happen before sending. Explicit isError acknowledgements resolve; RPC/transport/validation failures reject. The hook owns no pending/error state. See host actions for availability, replacement context, and actual display-mode behavior.

Exported authoring types: AppProviderProps, AppState, ToolState, ToolName, ToolInput, ToolResult, ToolCall, and ToolCallOptions. Host-action types are HostActions, HostActionAvailability, and HostActionOptions.

​

Server and wire contracts

getAppSupport(ctx) and AppSupport are exported by @toolgrain/mcp. Existing mcpResult() types preserve inferred metadata through an optional second generic parameter; existing single-generic usage remains valid.

@toolgrain/protocol/apps exports APPS_PROTOCOL_VERSION, APPS_EXTENSION_ID, APPS_MIME_TYPE, AppToolMeta, AppResourceMeta, AppHostContext, AppHostCapabilities, AppDisplayMode, AppToolResult, AppInitializeParams, and AppInitializeResult. This export has no runtime dependencies and does not replace either supported outer MCP revision.

Additional named exports describe resource settings, host presentation, and host-action envelopes:

Type	Contract
AppResourceCsp	Readonly domain lists for network, resource, nested-frame, and base-URI CSP directives
AppResourcePermissions	Camera, microphone, geolocation, and clipboard-write requests expressed as empty objects
AppTheme	light or dark
AppStyleVariableKey	Standardized color, typography, radius, border-width, and shadow token names
AppStyleVariables	Optional standard variables plus string-valued host/application extensions
AppHostCss	Host font-loading CSS and extension fields
AppHostStyles	Variables and CSS supplied in host context
AppContentModalities	Content kinds advertised for optional host actions
AppMessageParams	User role and readonly MCP content-block array
AppModelContextParams	Optional content blocks and object-root structured replacement context
AppActionResult	Host acknowledgement with optional isError and preserved extensions
AppDisplayModeResult	Actual selected display mode and preserved extensions

AppHostCapabilities now names sandbox grants/CSP, experimental extensions, content-message/context modalities, download support, and sampling tools, alongside existing server tool/resource, link, and logging advertisements. Unknown capability fields are preserved. The support table distinguishes implemented requests from other advertisements.

Styling variables are optional. Use CSS fallbacks such as var(--color-text-primary, #111) and var(--font-sans, sans-serif). The provider applies supplied variables and font CSS by default; applyHostStyles={false} disables that behavior.

The metadata guide includes resource fields and border examples. AppToolMeta rejects resource-only CSP/permissions, including when metadata is assigned through another variable. The runtime still preserves supplied metadata; the host owns enforcement.

apps-provenance.json pins the reviewed stable specification and upstream type reference, including their SHA-256 hashes. Some type-reference advertisements go beyond the stable prose; their presence alone does not implement a React action.