mcp-ui-ext-apps-openai

Unified utility for building apps that work on both OpenAI ChatGPT and MCP Apps platforms.

Author: lkm1developer

Installation

npm install mcp-ui-ext-apps-openai

Peer Dependencies

This package requires the following peer dependencies:

npm install @modelcontextprotocol/ext-apps react

Usage

React Hook (Recommended)

import { useUnifiedApp } from "mcp-ui-ext-apps-openai/react";
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";

// Define your structured data type
interface CounterData {
  status: boolean;
  value?: number;
  error?: string;
}

function CounterApp() {
  const {
    app,
    isConnected,
    platform,
    hostContext,
    initialProps,
    widgetState,
    setWidgetState,
  } = useUnifiedApp({
    appInfo: { name: "Counter App", version: "1.0.0" },
    capabilities: {},
    onError: (e) => console.error("[CounterApp]", e),
  });

  // Get counter value from widget state
  const counter = (widgetState as { value?: number } | null)?.value ?? 0;

  // Fetch counter from server
  const fetchCounter = async () => {
    if (!app) return;

    const result = await app.callServerTool({ name: "get-counter", arguments: {} });
    const data = (result as CallToolResult).structuredContent as unknown as CounterData;

    if (data.status && data.value !== undefined) {
      setWidgetState({ value: data.value });
    }
  };

  // Initialize from initialProps (OpenAI) or fetch from server (MCP)
  useEffect(() => {
    if (!app || !isConnected) return;

    if (initialProps !== undefined) {
      const data = (initialProps as CallToolResult).structuredContent as unknown as CounterData;
      if (data?.status && data.value !== undefined) {
        setWidgetState({ value: data.value });
        return;
      }
    }

    fetchCounter();
  }, [app, isConnected, initialProps]);

  // Increment counter
  const handleIncrement = async () => {
    if (!app) return;

    const newValue = counter + 1;
    setWidgetState({ value: newValue }); // Optimistic update

    const result = await app.callServerTool({
      name: "set-counter",
      arguments: { value: newValue }
    });
    const data = (result as CallToolResult).structuredContent as unknown as CounterData;

    if (!data.status) {
      setWidgetState({ value: counter }); // Revert on error
    }
  };

  return (
    <div>
      <p>Platform: {platform}</p>
      <p>Theme: {hostContext?.theme}</p>
      <p>Counter: {counter}</p>
      <button onClick={handleIncrement}>+</button>
      <button onClick={fetchCounter}>Refresh</button>
    </div>
  );
}

Core Utilities (No React)

import { detectPlatform, isOpenAI, isMCP, createUnifiedApp } from "mcp-ui-ext-apps-openai";

// Check platform
const platform = detectPlatform(); // "openai" | "mcp" | "unknown"

if (isOpenAI()) {
  console.log("Running on OpenAI ChatGPT");
} else if (isMCP()) {
  console.log("Running on MCP Apps");
}

// Create unified app (for OpenAI only - use React hook for MCP)
const { app, isConnected, error } = createUnifiedApp({
  appInfo: { name: "My App", version: "1.0.0" },
  onError: console.error,
});

if (app && isConnected) {
  const result = await app.callServerTool({ name: "my-tool", arguments: {} });
}

API Reference

useUnifiedApp(options)

React hook that provides a unified app interface for both platforms.

Options

Option	Type	Description
appInfo	{ name: string; version: string }	App information
capabilities	McpUiAppCapabilities	Optional capabilities
onToolInput	(input: unknown) => void	Called when tool input is received
onToolResult	(result: UnifiedToolResult) => void	Called when tool result is received
onHostContextChanged	(context: UnifiedHostContext) => void	Called when host context changes
onTeardown	() => void	Called when app is being torn down
onError	(error: Error) => void	Called on errors (also logs to console)

Returns

Property	Type	Description
app	UnifiedApp | null	The unified app instance
isConnected	boolean	Whether connected to host
error	Error | null	Any connection error
platform	"openai" | "mcp" | "unknown"	Detected platform
hostContext	UnifiedHostContext	Current host context (theme, locale, etc.)
initialProps	unknown	Initial props from toolOutput (OpenAI only)
widgetProps	Record<string, unknown>	Widget props (OpenAI only)
widgetState	unknown	Widget state (works on both platforms)
setWidgetState	(state: T) => void	Set widget state
updateWidgetState	(state: Partial<T>) => void	Partially update widget state

UnifiedApp Interface

Method	Description
callServerTool({ name, arguments })	Call a server tool
sendMessage(message, options?)	Send a message to the host
sendLog({ level, data })	Send a log message
openLink({ url })	Open an external link
getHostContext()	Get current host context
setWidgetState(state)	Set widget state (OpenAI only)
updateWidgetState(state)	Update widget state partially (OpenAI only)
requestDisplayMode(mode)	Request display mode (OpenAI only)
requestClose()	Request to close widget (OpenAI only)
uploadFile(file)	Upload a file (OpenAI only)
getFileDownloadUrl({ fileId })	Get file download URL (OpenAI only)

Platform-Specific Behavior

Feature	OpenAI	MCP
widgetState	Syncs to OpenAI + React state	React state only
initialProps	From toolOutput	undefined
widgetProps	From widget.props	{}
uploadFile	Works	Throws error
requestDisplayMode	Works	No-op
callCompletion	Works	Throws error

Structured Tool Data

Tools should return structured data in structuredContent:

// Server tool response format
{
  status: true,
  value: 42,
  // or on error:
  // status: false,
  // error: "Something went wrong"
}

// Access in client
const result = await app.callServerTool({ name: "get-counter", arguments: {} });
const data = (result as CallToolResult).structuredContent as unknown as CounterData;

if (data.status) {
  console.log("Value:", data.value);
} else {
  console.error("Error:", data.error);
}

License

MIT

Examples

The examples/ directory contains a complete counter app example:

Structure

examples/
├── server/          # MCP server with counter tools
│   ├── server.ts    # Express + MCP server
│   └── package.json
└── ui/              # React counter app
    ├── src/main.tsx # Counter UI using useUnifiedApp
    └── package.json

Server Example (examples/server/)

A fully-featured MCP server that:

• Auto-detects OpenAI vs MCP Apps clients via user-agent
• Uses proper MIME types (text/html+skybridge for OpenAI, standard for MCP)
• Registers resources with registerAppResource
• Registers tools with registerAppTool
• Manages sessions (stateful, 5 min timeout)

Tools:

• counter - Widget tool with resource binding
• get-counter - Returns { status: true, value: number }
• set-counter - Accepts { value: number }, returns { status: true, value: number }

Run:

cd examples/server
npm install
npm run dev  # Starts on http://localhost:3001

UI Example (examples/ui/)

A React counter app that:

• Uses useUnifiedApp hook for cross-platform support
• Initializes from initialProps (OpenAI) or fetches via get-counter (MCP)
• Shows counter with +/- buttons
• Optimistically updates UI, reverts on error
• Persists changes via set-counter tool

Run:

cd examples/ui
npm install
npm run build  # Builds to dist/index.html

The built dist/index.html is served by the server as the widget HTML resource.

Running the Full Example

1. Build the UI:

   cd examples/ui && npm install && npm run build
   

2. Start the server:

   cd examples/server && npm install && npm run dev
   

3. Connect from OpenAI ChatGPT or MCP Apps client to http://localhost:3001/mcp