@mcp-apps-kit/ui-react

React bindings for MCP applications.

@mcp-apps-kit/ui-react builds on @mcp-apps-kit/ui to provide React context and hooks for tool calls, tool results, and host context.

Table of Contents

• Background
• Features
• Compatibility
• Install
• Usage
• Examples
• API
• Contributing
• License

Background

React widgets often need host-aware APIs for tool calls and UI state. This package provides a React-first wrapper around the vanilla UI SDK so you can use hooks instead of manual subscriptions.

Features

• AppsProvider context wrapper
• Hooks for tools, host context, and widget state
• Typed tool calls with generics
• Optional debug logger hook
• Host capabilities - Query what the host supports (theming, display modes, file upload, etc.)
• Size notifications - Automatic resize observer integration
• Partial tool input - React to streaming tool inputs

Compatibility

• Hosts: MCP Apps and ChatGPT (OpenAI Apps SDK)
• Node.js: >= 18 for tooling/builds (browser runtime)
• Peer dependencies: react and react-dom ^18 || ^19

Install

npm install @mcp-apps-kit/ui-react

Usage

Quick start

import { AppsProvider, useAppsClient, useToolResult, useHostContext } from "@mcp-apps-kit/ui-react";

function Widget() {
  const client = useAppsClient();
  const result = useToolResult();
  const host = useHostContext();

  return (
    <div data-theme={host.theme}>
      <button onClick={() => client.callTool("greet", { name: "Alice" })}>Greet</button>
      <pre>{JSON.stringify(result, null, 2)}</pre>
    </div>
  );
}

export function App() {
  return (
    <AppsProvider>
      <Widget />
    </AppsProvider>
  );
}

Typed tools and results

Use ClientToolsFromCore from @mcp-apps-kit/core for end-to-end type safety:

import { AppsProvider, useAppsClient, useToolResult } from "@mcp-apps-kit/ui-react";
import type { AppClientTools } from "../server"; // Exported from your server

function Widget() {
  // Typed client - callTool arguments and return types are inferred
  const client = useAppsClient<AppClientTools>();

  // Typed results - result?.greet?.message is typed as string | undefined
  const result = useToolResult<AppClientTools>();

  const handleGreet = async () => {
    // Option 1: Using callTool with tool name string
    await client.callTool("greet", { name: "Alice" });

    // Option 2: Using the typed tools proxy (recommended)
    await client.tools.callGreet({ name: "Alice" });
  };

  if (result?.greet) {
    return (
      <div>
        <p>{result.greet.message}</p>
        <p>at {result.greet.timestamp}</p>
      </div>
    );
  }

  return <button onClick={handleGreet}>Greet</button>;
}

export function App() {
  return (
    <AppsProvider>
      <Widget />
    </AppsProvider>
  );
}

Automatic size notifications

By default, the MCP adapter automatically reports UI size changes to the host using a ResizeObserver. This feature is only supported in MCP Apps and is silently ignored in ChatGPT.

To disable automatic resizing:

export function App() {
  return (
    <AppsProvider autoResize={false}>
      <Widget />
    </AppsProvider>
  );
}

Note: The autoResize option is only applied during initial mount. Changing it at runtime has no effect.

The AppClientTools type is generated in your server code:

// server/index.ts
import { createApp, defineTool, type ClientToolsFromCore } from "@mcp-apps-kit/core";

const app = createApp({
  tools: {
    greet: defineTool({
      input: z.object({ name: z.string() }),
      output: z.object({ message: z.string(), timestamp: z.string() }),
      handler: async (input) => ({ ... }),
    }),
  },
});

// Export for UI code
export type AppClientTools = ClientToolsFromCore<typeof app.tools>;

Examples

• kanban-mcp-example

API

Provider

• AppsProvider - Context wrapper for all hooks
  • client? - Pre-initialized client instance (optional)
  • forceAdapter? - Force a specific adapter ("mcp" | "openai" | "mock")
  • autoResize? - Enable/disable automatic size change notifications (default: true). Only supported in MCP Apps; ignored in ChatGPT. Note: changing this prop after initial mount has no effect.
  • fallback? - Component to show while client initializes
  • errorFallback? - Component to show on initialization error

Core Hooks

| Hook | Description | | ---------------- | ----------------------------------------- | | useAppsClient | Client instance for tool calls | | useToolResult | Current tool result data | | useToolInput | Tool input parameters | | useHostContext | Host info (theme, viewport, locale, etc.) | | useWidgetState | Persisted state across reloads | | useDisplayMode | Fullscreen/panel mode control | | useDebugLogger | Debug logging configuration |

Typed Tools Proxy

The client returned by useAppsClient includes a tools property with typed method wrappers:

import { useAppsClient } from "@mcp-apps-kit/ui-react";
import type { AppClientTools } from "../server";

function Widget() {
  const client = useAppsClient<AppClientTools>();

  const handleClick = async () => {
    // Tool name "greet" becomes method "callGreet"
    const result = await client.tools.callGreet({ name: "Alice" });
    console.log(result.message);
  };

  return <button onClick={handleClick}>Greet</button>;
}

Method names are generated by prepending "call" and capitalizing the first letter of the tool name (e.g., greet → callGreet, searchRestaurants → callSearchRestaurants).

Host Capabilities & Version

import { useHostCapabilities, useHostVersion } from "@mcp-apps-kit/ui-react";

function Widget() {
  const capabilities = useHostCapabilities();
  const version = useHostVersion();

  // Common capabilities (both platforms)
  const themes = capabilities?.theming?.themes; // ["light", "dark"]
  const modes = capabilities?.displayModes?.modes; // ["inline", "fullscreen", "pip"]

  // MCP Apps specific
  const hasPartialInput = !!capabilities?.partialToolInput;

  // ChatGPT specific
  const hasFileUpload = !!capabilities?.fileUpload;

  // Host version (MCP Apps only)
  // { name: "MCP Host", version: "1.0.0" }
  return <div>Host: {version?.name}</div>;
}

Size Notifications (MCP Apps)

import { useSizeChangedNotifications } from "@mcp-apps-kit/ui-react";

function Widget() {
  // Attach to container to auto-report size changes
  const containerRef = useSizeChangedNotifications();

  return <div ref={containerRef}>Content that may resize</div>;
}

Partial Tool Input (MCP Apps)

import { useOnToolInputPartial } from "@mcp-apps-kit/ui-react";

function Widget() {
  useOnToolInputPartial((input) => {
    // React to streaming partial input from the model
    console.log("Partial input:", input);
  });

  return <div>Streaming input widget</div>;
}

Theme & Style Hooks

| Hook | Description | | ----------------------- | --------------------------------- | | useHostStyleVariables | Apply host-provided CSS variables | | useDocumentTheme | Sync document theme with host | | useSafeAreaInsets | Safe area insets (ChatGPT) |

Lifecycle Hooks

| Hook | Description | | -------------------- | -------------------------------------- | | useOnToolCancelled | Callback when tool is cancelled | | useOnTeardown | Cleanup callback before widget removal |

File Operations (ChatGPT)

| Hook | Description | | ----------------- | ---------------------- | | useFileUpload | Upload files to host | | useFileDownload | Get file download URLs |

Layout (ChatGPT)

| Hook | Description | | -------------------- | --------------------------- | | useIntrinsicHeight | Set widget intrinsic height | | useView | View management |

Modals (ChatGPT)

| Hook | Description | | ---------- | ----------------------- | | useModal | Modal dialog management |

Contributing

See ../../CONTRIBUTING.md for development setup and guidelines. Issues and pull requests are welcome.

License

MIT