MCP Apps

For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.

What is an MCP App?

An MCP App is an iframe-based UI that communicates with its host through PostMessage and JSON-RPC. The host provides capabilities like tool calling, resource reads, display-mode switching, and conversation messaging. Your app discovers what the host supports at connection time and can adapt accordingly.

The MCP App runtime is exported from the main xmcp package at xmcp/host-bridge. The @xmcp-dev/ui package re-exports a React hook (useMcpApp()) that wraps one shared bridge for the iframe lifetime. React component cleanup unsubscribes only its observer, so Strict Mode remounts do not dispose the shared host connection.

useMcpApp() hook

The recommended way to use MCP App capabilities in React:

import { useMcpApp } from "@xmcp-dev/ui";

export default function MyApp() {
  const {
    callTool,
    openLink,
    requestDisplayMode,
    readResource,
    sendMessage,
    updateModelContext,
    logMessage,
    notifySizeChanged,
    isConnected,
    hostContext,
    hostCapabilities,
  } = useMcpApp();

  // ...
}

Capabilities

callTool(name, args?)

Invoke an MCP tool through the host. The host routes the call to the connected MCP server and returns the result.

const result = await callTool("getWeather", { city: "Buenos Aires" });
// result.content: array of content items (text, images, etc.)
// result.isError: true if the tool returned an error

openLink(url)

Open a URL in the host's browser. Falls back to window.open when no host is connected.

await openLink("https://docs.example.com/api");

requestDisplayMode(mode)

Ask the host to switch the app's display mode. Supported modes:

• "inline": embedded in the conversation flow (default)
• "fullscreen": takes over the full viewport
• "pip": picture-in-picture floating window

The host may not grant the requested mode. The returned object tells you which mode was actually applied.

const { mode } = await requestDisplayMode("fullscreen");
// mode: the mode the host actually set

readResource(uri)

Read an MCP resource from the server through the host.

const result = await readResource("docs://api-reference");
// result.contents: array of { uri, mimeType, text, blob }

sendMessage(params)

Send a message to the host conversation. This lets the app communicate back to the user or model through the host's chat interface.

const reply = await sendMessage({
  role: "user",
  content: "Task completed successfully",
});

updateModelContext(params)

Inject context into the model's next turn. Use this to provide the model with information it should consider in its response.

await updateModelContext({
  role: "system",
  content: "The user just approved the deployment",
});

logMessage(params)

Emit a log notification to the host. This is fire-and-forget and does not wait for a response.

logMessage({ content: "Processing started" });

notifySizeChanged(dimensions)

Tell the host that the app's rendered size has changed. The host can use this to resize the iframe container.

notifySizeChanged({ width: 600, height: 400 });

For automatic size reporting, use useAutoMcpAppSize() instead of calling this manually.

Reactive state

isConnected

Boolean indicating whether the bridge has an active connection to the host. The bridge starts connected if it detects a parent window, then marks disconnected if no host traffic arrives within the connection timeout (2 seconds by default).

hostContext

The host environment context, updated reactively when the host sends ui/notifications/host-context-changed. Contains:

hostCapabilities

What the host advertises it supports. Use this to conditionally enable features:

const { hostCapabilities, openLink } = useMcpApp();

// Only show the link button if the host supports it
if (hostCapabilities?.openLinks) {
  await openLink("https://example.com");
}

Auto size reporting

useAutoMcpAppSize() uses ResizeObserver to automatically report size changes to the host:

import { useRef } from "react";
import { AppShell, useAutoMcpAppSize } from "@xmcp-dev/ui";

export default function MyApp() {
  const rootRef = useRef<HTMLDivElement>(null);
  useAutoMcpAppSize(rootRef);

  return <AppShell ref={rootRef}>...</AppShell>;
}

Framework-agnostic usage

If you are not using React or @xmcp-dev/ui, the host bridge is available directly from the main xmcp package:

import { createMcpHostBridge } from "xmcp/host-bridge";

const bridge = createMcpHostBridge();

bridge.subscribe((state) => {
  console.log("Connected:", state.isConnected);
  console.log("Host context:", state.hostContext);
});

const result = await bridge.callTool("myTool", { key: "value" });

The bridge exposes the same methods as useMcpApp() plus lifecycle controls:

• getState(): current bridge state
• getHostContext(): current host context
• getHostCapabilities(): current host capabilities
• isConnected(): connection status
• subscribe(listener): listen for state changes (returns unsubscribe fn)
• dispose(): clean up listeners and reject pending requests

References

• UI Rendering
• Tools
• CSS