Skip to content
Fractal frac

useMcpAppContext

The useMcpAppContext hook is a low-level hook that subscribes to context values from the MCP Apps host. This hook powers many of the other frac hooks when running in MCP Apps clients and can be used directly when you need access to specific context values.

Basic usage

Section titled “Basic usage”
import { useMcpAppContext } from "@usefractal/frac/web";


function ThemeDisplay() {
  const theme = useMcpAppContext("theme");


  return <p>Current theme: {theme}</p>;
}

Parameters

Section titled “Parameters”

key

Section titled “key”
key: keyof McpAppContext

Required

The key of the context value to subscribe to. Available keys include:

KeyTypeDescription
theme"light" | "dark"The current color theme
localestringThe user’s locale (e.g., "en-US")
displayMode"inline" | "fullscreen"The view’s display mode
maxHeightnumberMaximum height available for the view
toolInputobject | nullThe input arguments passed to the tool
toolResultobject | nullThe tool execution result
toolCancelledobject | nullTool cancellation details (if cancelled)

options

Section titled “options”
options?: { appInfo?: { name: string; version: string } }

Optional

Initialization options for the MCP App bridge. Only used on first instantiation.

requestTimeout

Section titled “requestTimeout”
requestTimeout?: number

Optional

Timeout in milliseconds for the initialization request. Defaults to 10000 (10 seconds).

Returns

Section titled “Returns”
value: McpAppContext[K] | undefined

The current value of the specified context key, or undefined if not yet available.

Examples

Section titled “Examples”

Reading Theme

Section titled “Reading Theme”
import { useMcpAppContext } from "@usefractal/frac/web";


function ThemedView() {
  const theme = useMcpAppContext("theme");


  return (
    <div style={{
      backgroundColor: theme === "dark" ? "#1a1a1a" : "#ffffff",
      color: theme === "dark" ? "#ffffff" : "#000000"
    }}>
      <p>Current theme: {theme}</p>
    </div>
  );
}

Accessing Tool Input

Section titled “Accessing Tool Input”
import { useMcpAppContext } from "@usefractal/frac/web";


function ToolInputDisplay() {
  const toolInput = useMcpAppContext("toolInput");


  if (!toolInput) {
    return <p>No tool input yet...</p>;
  }


  return (
    <div>
      <h3>Tool Input:</h3>
      <pre>{JSON.stringify(toolInput, null, 2)}</pre>
    </div>
  );
}

Checking Tool Result

Section titled “Checking Tool Result”
import { useMcpAppContext } from "@usefractal/frac/web";


function ToolResultDisplay() {
  const toolResult = useMcpAppContext("toolResult");
  const toolCancelled = useMcpAppContext("toolCancelled");


  if (toolCancelled) {
    return <p>Tool was cancelled: {toolCancelled.reason}</p>;
  }


  if (!toolResult) {
    return <p>Waiting for tool result...</p>;
  }


  return (
    <div>
      <h3>Tool Result:</h3>
      <pre>{JSON.stringify(toolResult, null, 2)}</pre>
    </div>
  );
}

Multiple Context Values

Section titled “Multiple Context Values”
import { useMcpAppContext } from "@usefractal/frac/web";


function EnvironmentInfo() {
  const theme = useMcpAppContext("theme");
  const locale = useMcpAppContext("locale");
  const displayMode = useMcpAppContext("displayMode");
  const maxHeight = useMcpAppContext("maxHeight");


  return (
    <div>
      <h3>MCP App Environment</h3>
      <ul>
        <li>Theme: {theme}</li>
        <li>Locale: {locale}</li>
        <li>Display Mode: {displayMode}</li>
        <li>Max Height: {maxHeight}px</li>
      </ul>
    </div>
  );
}

Type Reference

Section titled “Type Reference”

McpAppContext

Section titled “McpAppContext”
type McpAppContext = McpUiHostContext & McpToolState;

Combines the host context from the MCP ext-apps spec with tool execution state.

McpToolState

Section titled “McpToolState”
type McpToolState = {
  toolInput: Record<string, unknown> | null;
  toolResult: {
    content: Array<{ type: string; text?: string }>;
    isError?: boolean;
  } | null;
  toolCancelled: {
    reason?: string;
  } | null;
};
Section titled “Related”